Search for answers or browse our knowledge base.
Deploying Epicor ECM SAML 2.0 in Microsoft Azure
Introduction 📚
Setting up Epicor ECM for SAML 2.0 authentication with Microsoft Azure Active Directory (Azure AD) enables a secure and seamless Single Sign-On (SSO) experience for your users. This guide will walk you through the complete process of configuring SAML, obtaining the required metadata, and integrating it with Epicor ECM.
💡 Pro Tip: If you need help during this setup, contact Mosaic Support at support@mosaiccorp.com and provide the App Federation Metadata URL from Azure.
Step 1: Creating a Non-Gallery Enterprise Application 🔧
1️⃣ Sign in to Microsoft Azure
- Go to the Azure Portal and sign in with your administrator account.
2️⃣ Navigate to Azure Active Directory
- Select Azure Active Directory from the left-hand menu.
- Click Enterprise Applications and then + New Application.
3️⃣ Create a Non-Gallery Application
- Under Add your own application, enter a name (e.g.,
Epicor ECM SSO) and click Create.
4️⃣ Configure Single Sign-On
- In the application overview, select Single Sign-On, then choose SAML as the SSO method.
Step 2: Add a User Group for Single Sign-On 👥
1️⃣ Assign Users and Groups
- Go to the Users and Groups section of your newly created application.
- Click Add User/Group and select the appropriate user group.
2️⃣ Grant Access
- Ensure the selected group has access by clicking Assign.
Step 3: Obtain the Federation Metadata URL and Configure Epicor ECM 🔗
1️⃣ Go to Single Sign-On Setup in Azure
- Locate and copy the App Federation Metadata URL under Single Sign-On > SAML.
2️⃣ Configure Epicor ECM
- As an Epicor ECM site administrator:
- Navigate to Admin Tab > Authenticated Providers.
- Click Create New SAML 2.0 Provider.
- Paste the App Federation Metadata URL from Azure and click Save.
3️⃣ Retrieve Your Application Federation Metadata and Sign-On URL
- After saving, Epicor ECM will generate a Sign-On URL and Application Federation Metadata URL.
- 📢 Note: The Sign-On URL will be needed in Step 4 for the Log-In URL configuration in Azure.
4️⃣ Download the Federation XML
- Open the Application Federation Metadata URL in a browser to download the
federation.xmlfile. - Open this file using Notepad or Notepad++.
5️⃣ Locate the Required Information
- Entity ID: Found in the
<md:EntityDescriptor>element (entityIDattribute). - Sign-Out URL: Located in the
<md:SingleLogoutService>element (Locationattribute). - Assertion Consumer Service (ACS) URL: Found in the
<md:AssertionConsumerService>element (Locationattribute).
Step 4: Add the Obtained Entity ID, URLs, and Relay State to Azure 🔑
1️⃣ Go Back to Azure
- Return to Single Sign-On > SAML in your Enterprise Application.
2️⃣ Enter the Following Details:
- Identifier (Entity ID): Enter the value from the
<md:EntityDescriptor>element. - Reply URL (ACS URL): Use the URL from the
<md:AssertionConsumerService>element. - Sign-Out URL: Found in the
<md:SingleLogoutService>element. - Relay State: Provided by the Epicor ECM setup process.
- Log-In URL: Enter the Sign-On URL generated in Epicor ECM during the Authenticated Providers setup.
3️⃣ Save the Configuration
Azure will validate the URLs. If no errors are detected, your SAML setup for Epicor ECM is complete. 🎉
Step 5: Test Your Configuration from Azure 🔍
1️⃣ In Azure, go back to the Single Sign-On > SAML page.
2️⃣ Click the Test Button at the top.
3️⃣ Select “Test sign-in” to simulate a login using your saved configuration.
💡 If successful, you’ll see a confirmation message indicating the configuration works.
⚠️ If it fails, Azure will provide error details to help with troubleshooting.
Example Epicor ECM Application Federation XML File 📄
Below is an example federation.xml file for Epicor ECM. Note: This example may differ depending on your environment—especially if you’re using a cloud-based Epicor ECM. Replace yourdomainhere and yourappid with your actual Epicor ECM Domain and Application ID.
<md:EntityDescriptor entityID="https://yourdomainhere/eclipseserver/sso/integratedauthentication.ashx" ID="_unique-entity-id-here" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
<md:SPSSODescriptor ID="_unique-sp-id-here" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" AuthnRequestsSigned="false" WantAssertionsSigned="false">
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://yourdomainhere/eclipseserver/sso/integratedauthentication.ashx?type=saml&idpid=yourappid&isresponse=true"/>
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://yourdomainhere/eclipseserver/sso/integratedauthentication.ashx?type=saml&idpid=yourappid&isresponse=true"/>
<md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://yourdomainhere/eclipseserver/sso/integratedauthentication.ashx?type=saml&idpid=yourappid&isresponse=true" index="0" isDefault="true"/>
</md:SPSSODescriptor>
</md:EntityDescriptor>
Example URLs Derived from the Federation XML File
Note: These URLs are based on the example above and may differ for your environment.
- Entity ID (Identifier):
https://yourdomainhere/eclipseserver/sso/integratedauthentication.ashx - Assertion Consumer Service (ACS) URL (Reply URL):
https://yourdomainhere/eclipseserver/sso/integratedauthentication.ashx?type=saml&idpid=yourappid&isresponse=true - Sign-Out URL:
https://yourdomainhere/eclipseserver/sso/integratedauthentication.ashx?type=saml&idpid=yourappid&isresponse=true - Log-In URL:
https://yourdomainhere/eclipseserver/sso/integratedauthentication.ashx
Additional Resources 📖
👉 Epicor Documentation
👉 Microsoft Learn Resources
Conclusion 🎯
By following this guide, you’ll successfully set up Epicor ECM SAML 2.0 with Microsoft Azure AD. This setup will improve user experience and ensure secure authentication. For further assistance, contact Mosaic Support and share your App Federation Metadata URL from Azure.
📢 Need Help?
Contact Mosaic Support at support@mosaiccorp.com for assistance
