Configure DPA to use SAML authentication with Okta

SAML authentication in DPA offers single sign-on (SSO) and the opportunity to use different credential storage or multifactor authentications using third-party providers like Okta, Microsoft Entra ID (previously Azure AD), or Keycloak. Complete the following tasks to configure SAML authentication and single sign-on with Okta 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): Okta

When configuring Okta to communicate with DPA, you will be working with both Okta 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 identity provider URL and URI

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 Okta.

4. Keep DPA open, and continue in Okta.

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

1. Log in to your Okta organization with administrative privileges.
2. In the left pane of the Admin Console, click Applications > Applications.

3. Click Create App Integration.

   

4. Select the SAML 2.0 option, and click Next.
5. In General Settings, enter a name for your SAML integration, and click Next.

6. In the SAML Settings section, make the following changes:

   1. In the General section, paste the following values from DPA into Okta:

      DPA field	Okta field	Notes
      Single Sign On Service URL	Single sign on URL	This SAML URL is used for the Recipient URL and Destination URL. This is a location where the SAML assertion is sent with an HTTP POST. This is often referred to as the SAML Assertion Consumer Service (ACS) URL for your application.
      Audience URI	Audience URI (SP Entity ID)	This is the intended audience of the SAML assertion. This is most often the SP Entity ID of your application.
      Default RelayState	Default RelayState (Optional)	This is default landing page in the IDP initiated flow.

      

   2. In the Attribute Statements section, add the following attribute statements:

      Name	Name format	Value
      Email	Unspecified	user.email
      FirstName	Unspecified	user.firstName
      LastName	Unspecified	user.lastName

      

   3. In the Group Attributes Statements section, add following attribute statements:

      Name	Name format	Filter	Value
      DPAGroups	Unspecified	Matches regex	.*

      

   4. Click Next, provide the requested background information about yourself, and click Finish.

7. Specify the users to access DPA through SAML login:

   1. In the left pane of the Admin Console, click Applications > Applications.

   2. Click Assign Users to App.

      

   3. Select the applications and people, click Next, and click Confirm Assignments.

8. On the Sign On tab, click the View Setup Instructions button in the Sign On Methods section. Keep the tab open so that you can copy and paste the information into DPA.

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 Okta in the Identity Provider Name field.

3. Paste the following values from Okta into DPA:

   Okta field	DPA field
   Identity Provider Single Sign-On URL	SSO Target URL (Endpoint)
   Identity Provider Issuer	Issuer (Entity ID)

4. In the IdP Metadata File Path in DPA, enter one of the following from Okta:

   • From the Optional section, enter the path of the XML file where content is saved.

     

   • Download the metadata.xml file from the Identity Provider metadata link and enter that absolute file path.

     

5. Click Next.
6. On the Summary page, review the information and click Configure.
7. At the confirmation message, click Finish and go to 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 Okta, assign application to users.

2. Assign an app integration to a group.

3. Determine which groups contain the users that you want to grant access to DPA. You may need to create a group if a suitable group does not exist.

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

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

6. Click Add SAML Group.

7. Add the same group name that was added in Okta.

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

9. 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, the Okta website opens and you can enter your Okta credentials.

When you are already logged in to Okta, DPA opens when you click Login with SAML SSO. You are not prompted for credentials unless you are logged out of Okta during a browser session, or you close the browser.

If the Okta admin user is also the DPA user, you are not prompted for credentials when you click Login with SAML SSO.

(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 your Okta organization with administrative privileges.
2. In the left pane of the Admin Console, click Applications.
3. Click the General tab.
4. In SAML Settings, click Edit. Then click Next.
5. On the Configure SAML page, click Show Advanced Settings.
6. From the Assertion Encryption drop-down, select Encrypted.

7. 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

8. Click Next and then Finish to exit the wizard.