Configure DPA to use SAML authentication with Microsoft Entra ID

SAML authentication in DPA offers single sign-on (SSO) and the opportunity to use different credential storage or multifactor authentications using third-party identity providers like Microsoft Entra ID (previously Azure AD), Okta, or Keycloak. Complete the following tasks to configure SAML authentication and single sign-on with Microsoft Entra ID as the identity provider.

If DPA is running behind a load balancer (or API Gateway) and you want to enable SAML SSO authentication in DPA, you must enable SSL communication between the load balancer (or API Gateway) and DPA.

(Optional) Configure SAML keystore properties

By default, the keystore file from the classpath resource (saml.keystore) is used for SAML authentication. If you use the default keystore file, you do not need to modify the SAML keystore properties.

If you would like to use a different keystore file, specify values for the following properties in the system.properties file.

1. Open the following file in a text editor:

   DPA-install-dir\iwc\tomcat\ignite_config\idc\system.properties

2. Add or uncomment the following properties and specify the values.

   Property	Value
   com.confio.security.saml.keystore.path	The keystore file path.
   com.confio.security.saml.keystore.password	The password of the keystore file.
   com.confio.security.saml.keystore.privatekey.alias	The alias of the private key stored in the keystore file.
   com.confio.security.saml.keystore.privatekey.password	The password of the private key certificate added in the keystore file. The value for this property can be the same as the value for the property com.confio.security.saml.keystore.password. If the private key certificate does not have a password, uncomment or add the property but do not enter a value.
   com.confio.security.saml.keystore.type	The file type of the keystore file. This property is optional. If the custom keystore file is not JKS or PKCS12, use this property to specify the type.

3. Restart DPA for the new properties to take effect.

Prepare the identity provider (IdP): Microsoft Entra ID

When configuring Microsoft Entra ID to communicate with DPA, you will be working with both Microsoft Entra ID and DPA at the same time. You must keep both systems open to copy information from one system into the other.

Before you start

• DPA must be configured to use SSL to protect data during transmission. To enable SSL for DPA, see Configure DPA to use a custom certificate for SSL/TLS.

• DPA must be running on an HTTPS connection.

• If you do not want to use the default keystore file (saml.keystore), configure the SAML keystore properties in the system.properties file.

Task 1: In DPA, obtain the DPA endpoint URLs for the identity provider

1. Log in to DPA as a user with administrative privileges.

2. From the DPA menu in the upper-right corner, click Options.

3. Under Administration > Users & Contacts, click Configure SAML.

   On the Prepare Identify Provider (IdP) page, the following information is automatically added:

   • DPA URL
   • Audience URI
   • Single Sign On Service URL
   • Default RelayState

   

   You will copy and paste this information into the configuration in Azure AD.

4. Keep DPA open, and continue in Azure.

Task 2: In Microsoft Entra ID, create the SAML application, configure URLs and the URI, and specify users for SAML login

1. Log in to your Microsoft Entra ID portal with administrative privileges to add the application for SAML authentication.

2. Create the enterprise application and then select SAML as the single sign-on method.

   

   The Set up Single Sign-On with SAML screen opens.

   

3. In Basic SAML Configuration, click the Edit icon.

4. Paste the following values from DPA into Microsoft Entra ID:

   DPA field	Microsoft Entra ID field	Notes
   Audience URI	Identifier (Entity ID)	This is the intended audience of the SAML assertion. This is most often the SP Entity ID of your application.
   Single Sign On Service URL	Reply URL (Assertion Consumer Service URL)	The reply URL is where the application expects to receive the authentication token. This is also referred to as the “Assertion Consumer Service” (ACS) in SAML.
   Default RelayState	Default RelayState	This is default landing page in the IDP initiated flow.

   

5. In Attributes & Claims, click the Edit icon. Then click Add a group claim.

6. In the Group Claims panel, specify the following:

   1. Under the Which groups associated with the user option, select Groups assigned to the application.

   2. Under Source attribute, select sAMAccountName.

   3. Expand Advanced options. Then select Customize the name of the group claim, and enter DPAGroups in the Name box.

      

   4. Click Save.

      The Set up Single Sign-On with SAML displays the information you entered.

      

Complete the identity provider configuration in DPA

In DPA, the Add Identify Provider wizard is still open on the Prepare IdP page.

1. Click Next to open the Configure DPA page.

2. Enter an identifying name such as Microsoft Entra ID in the Identity Provider Name field.

3. Paste the following values from Microsoft Entra ID into DPA:

   Microsoft Entra ID field	DPA field
   Login URL	SSO Target URL (Endpoint)
   Microsoft Entra ID Identifier	Issuer (Entity ID)

4. Specify the IdP Metadata File Path:

   1. In Microsoft Entra ID, click the Download option next to Federation Metadata XML.

      

   2. In DPA, enter the absolute file path of downloaded Federation Metadata XML file.

      

5. Click Next.
6. On the Summary page, review the information and click Configure.
7. At the confirmation message, click Finish and go to the Options page.

8. Restart DPA for the settings to take effect.

   When the configuration is complete, the DPA system.properties file includes the following entries:

   • com.confio.security.saml.sso.targetUrl
   • com.confio.security.saml.entityId
   • com.confio.saml.sso.idp.metaData
   • com.confio.security.saml.enabled
   • com.confio.security.saml.defaultIDP
   • com.confio.security.saml.identityProviderName
   • com.confio.security.saml.dpaUrl

Create groups of users and configure user permissions

After you have set up DPA to use SAML authentication, do the following:

1. In the left pane of the SAML configuration page in the Azure AD portal, click Users and groups.

2. Click Add user/group.

3. Under Users and groups, click None Selected.

4. In the Users and groups panel, search for a group and select it.

   If the group does not exist, then create the group in Azure AD and add the users to that group.

   

5. Save the configuration and click Assign.

   The assigned groups are shown on the Users and groups screen.

6. Copy either the group name or ID (you will need this to create the SAML group in DPA):

   • If the group was created in an on-premises product and copied to Azure AD, copy the group name.

   • If the group was created directly in Azure AD, click the group name and copy the object ID of the group from the selected group page.

     

     If you do not know where the group was created, copy the object ID to enter into DPA. If that is not correct, users will receive the following message when they attempt to log in with SAML authentication: Domain user has no permissions in DPA. If this occurs, access DPA logs, open the auth.log file, and look for the entry Groups received in SAML response. If this entry contains the group name instead of the object ID, you must recreate the SAML group with the group name.

7. In DPA, create the SAML group:

   1. From the DPA menu in the upper-right corner, click Options.

   2. Under Administration > Users & Contacts, click User Administration.

   3. Click Add SAML Group.

   4. As the Group Name, enter the group name or object ID copied in the previous step.

   5. Assign privileges to the group, just as you would for a user.

      

   6. Click Save.

      You can add multiple groups in DPA. If a user is a member of more than one group, DPA grants them the combined privileges from all their groups.

Log in to DPA

When the SAML configuration is complete, the DPA login dialog includes an additional button: Login with SAML SSO.

Instead of entering credentials at the DPA login dialog, click Login with SAML SSO. The first time you log in, you will need to enter the credentials on the Microsoft Entra ID login page.

When you are already logged in to the Microsoft Entra ID portal or any other SAML application, you are automatically logged in to DPA when you click Login with SAML SSO. You are not prompted for credentials unless you are logged out of Microsoft Entra ID during a browser session, or you close the browser.

(Optional) Enable assertion encryption

SAML assertion encryption is optional. It’s an extra level of security in addition to the security provided by HTTPS. By default, assertion encryption is not enabled.

1. Log in to the Microsoft Entra ID portal with administrative privileges.

2. Select the DPA application that you want to configure assertion encryption for.

3. In the left pane under Security, click Token encryption.

4. Click Import Certificate, and upload the encryption certificate. If you use DPA’s default saml.keystore file, the encryption certificate is available in the following location:

   DPA-install-dir\iwc\tomcat\webapps\iwc\WEB-INF\classes\DefaultPublicCertForSaml.crt

   When the certificate is uploaded, it is shown in the list.

5. Click the three dots on the left side of the list item, and then click Activate token encryption certificate.

6. Click Yes to confirm the activation.

   When the assertion encryption is enabled, the Status column displays Active.

7. In the SAML Certificates section, click the Edit icon. Then verify that the Signing Option box contains the value Sign SAML response and assertion.