Documentation forDatabase Performance Analyzer

Configure DPA to use SAML authentication with Keycloak

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

Task 1: Enable SSL/HTTPS for the Keycloak server

By default, Keycloak is not set up to handle SSL/HTTPS traffic. Complete the following steps to enable HTTPS.

  1. Generate a Java keystore that contains the private key and certificate for SSL/HTTPS traffic:

    1. Open a command prompt and run the following command:

      keytool -genkey -alias localhost -keyalg RSA -keystore keycloak.jks -validity 10950

    2. Respond to the prompts, and enter yes if the summarized information is correct.

      The certificate is created in the directory from which you ran the command.

    3. Optionally, copy the file to a different location on the Keycloak server.

  2. Configure the Keycloak server to use the keypair and certificate generated in the previous step.

    1. Locate the keycloak.conf file in the keycloak-version\conf folder, and open the file in a text editor.

    2. Add the following lines to the the keycloak.conf file, where:

      • Path is the location of the Keycloak.jks file.
      • Password is the password that you added when you created the certificate.
      • Port is the HTTPS port number. This line is required only if port 8443 (the default HTTPS port for Keycloak) is in use.
      https-key-store-file=Path
https-key-store-password=Password
https-key-store-type=jks
https-port=Port

    3. Save the file.

Task 2: Configure a new realm in Keycloak

  1. Log in to the Keycloak admin console, and click Create Realm.

  2. Name the realm and keep the default settings.

  3. Click the link SAML 2.0 Identity Provider Metadata option on the Realm settings page.

  4. Save the metadata to a file with a recognizable file name, such as IDP_Metadata.xml.

  5. Open the file in a text editor and verify that the value of WantAuthnRequestsSigned is false.

Task 3: Configure DPA to use SAML

  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

  4. Click Next to open the Configure DPA page.

  5. Enter Keycloak in the Identity Provider Name field.

  6. Enter the following values from the metadata file saved in Task 2:

    DPA field Value
    SSO Target URL (Endpoint)

    In the metadata file saved in Task 2:, locate the SingleSignOnService tag and enter the location value.
    Issuer (Entity ID)

    In the metadata file, locate the EntityDescriptor tag and enter the entityID value.
    IdP Metadata File Path Enter the path and file name of the metadata file.
  7. Click Next.
  8. On the Summary page, review the information and click Configure.
  9. At the confirmation message, click Finish and go to the Options page.

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

Task 4: Configure the client

  1. In DPA, download the service provider (DPA) metadata file:

    1. Under Administration > Users & Contacts, click Configure SAML to open the Prepare Identify Provider (IdP) page.

    2. On the Audience URI line, click Copy to clipboard.

    3. Paste the URI into the address bar of a browser, and press Enter.

      The spring_saml_metadata.xml is downloaded to the Downloads folder or your computer.

  2. In the Keycloak left pane, click Clients. Then click Import client.

  3. Click Browse, browse to the location of the spring_saml_metadata.xml file, and select it to upload.

    The contents of the file are shown in the Resource file box.

  4. Click Save.

    Information is automatically added to the Client details tabs.

  5. Add a mapper:

    1. On the Client scopes tab, click the existing automatically populated Assigned client scope name that starts with DPA URL (for example, https://DPA_URL/iwc/saml2/service-provider-metadata/saml2login-dedicated).

      The Dedicated scopes page opens.

    2. On the Mappers tab, click Configure a new mapper.

      The Mapper details page opens.

    3. As the Mapper type, select Group list, and enter a name.

    4. As the Group attribute name, you must enter DPAGroups.

  6. As the SAML Attribute Name Format, select Basic.

  7. Toggle the Single Group Attribute and Full group path to Off.

  8. Click Save.

Task 5: Configure users and groups

  1. In Keycloak, add one or more groups:

    1. In the Keycloak left pane, click Groups.

    2. Click Create group.

    3. Enter a name and click Create.

  2. In Keycloak, create one or more users, and add each user to a group:

    1. In the left pane, click Users.

    2. Click Add user.

    3. Enter the user name and email address, and click Create.

    4. On the Credentials tab, click Set password.

    5. Enter the password, click Save, and click Save password at the confirmation message.

    6. On the Groups tab, click Join Group.

    7. Select the group you created in step 2, and click Join.

  3. In DPA, create a SAML group for each group you created in Keycloak:

    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 same name you entered for the group in Keycloak.

    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, The Keycloak login page opens and you can enter your Keycloak credentials.

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