Integrate OSP with Keycloak using OIDC

You can configure One SSO Provider (OSP) as a relying party (client) with Keycloak as an external OpenID Connect (OIDC) 1.0 provider. This topic explains the complete process for both login and logout, including common troubleshooting steps.

In this topic:

Prerequisites

Before you begin, ensure that you have the following requirements in place:

• A running instance of OSP deployed on Apache Tomcat.

• A running instance of Keycloak.

• Administrative access to both OSP configuration files and the Keycloak Admin Console.

Back to top

Step 1: Configure Keycloak

Set up a realm and client in Keycloak for the OSP integration.

Create a realm

In Keycloak, create a new realm for your application (for example, Dimensions CM).

Create and configure a client

To create and configure a client:

1. Navigate to Clients and click Create client.

2. Set the Client ID (for example, DimCM).

3. Ensure Client authentication is set to On.

4. Click Next.

To configure client settings:

1. After creating the client, configure the following settings:

   • Client authentication: Set to On.

   • Authorization: Set to On.

   • Authentication flow: Ensure Standard flow is checked.

2. Configure Valid redirect URIs. This is a critical setting. The URL required here depends on how your application initiates the login flow.

   If you are logging in directly through the OSP login page, the URI will likely be OSP's internal callback endpoint:

   https://<YOUR_OSP_HOST>:<PORT>/osp/a/<TENANT_ID>/auth/app/contractcontinue*

   Example: https://localhost:8443/osp/a/dimensions/auth/app/contractcontinue*

   If you are being redirected from an integrated application (like Dimensions CM or Pulse), you will need to add that application's specific callback URL (for example, https://.../pulse/login/oauth2/code/default).

   Tip: If login fails with an "Invalid redirect_uri" error, check the Keycloak server logs or your browser's URL bar. The error message will show the exact URI that OSP sent, which you can then copy and add to this list.

3. Configure Valid post logout redirect URIs. This is critical for logout to work. Add the URL that OSP will use to finalize its logout process:

   https://<YOUR_OSP_HOST>:<PORT>/osp/a/<TENANT_ID>/auth/app/logout*

   Example: https://localhost:8443/osp/a/dimensions/auth/app/logout*

This is a crucial step to prevent invalid_client errors during login.

To set the client authenticator:

1. Navigate to the Credentials tab for your client.

2. Set Client Authenticator to Signed Jwt with Client Secret.

3. A client secret will be generated. Copy this value for use in the OSP configuration.

You need a user within your Keycloak realm to test the login process.

To create a user:

1. From the main menu, navigate to Users.

2. Click Add user.

3. Enter a Username (for example, dmsys).

4. Fill out any other required fields and click Create.

5. After the user is created, go to their Credentials tab.

6. Set a password for the user. You can set this as a temporary password, which the user will be prompted to change on first login, or turn that option off for a permanent password.

7. Click Set password to save it.

Back to top

Step 2: Configure OSP authcfg.xml

Edit the OSP configuration file to add the Keycloak OpenID data source, authentication source, and authentication contract.

This block defines the connection to Keycloak and is the most important part for solving the logout issue.

To add the OpenID data source:

1. Locate and open the OSP configuration file:

   /opt/netiq/idm/osp/config/authcfg.xml

2. Add the following data source configuration:

   Copy code

   <!-- Data source for Keycloak OpenID Connect provider -->
   <OpenIdDataSource
       id="ds-keycloak"
       displayName="Keycloak OIDC Data Source"
       enabled="true"
       issuer="http://<YOUR_KEYCLOAK_HOST>:<PORT>/realms/<YOUR_REALM>"
       clientId="DimCM"
       clientSecret="<YOUR_CLIENT_SECRET_FROM_KEYCLOAK>"
       scope="openid profile email">
       <!--
           This RedirectUrl is the critical fix for logout.
           It overrides OSP's default logout behavior and manually adds the required 'client_id' parameter.
       -->
       <RedirectUrl returnParamName="post_logout_redirect_uri">http://<YOUR_KEYCLOAK_HOST>:<PORT>/realms/<YOUR_REALM>/protocol/openid-connect/logout?client_id=DimCM</RedirectUrl>
   </OpenIdDataSource>

Add OpenID authentication source

This block maps user attributes from Keycloak's token to OSP's local session.

<!-- Authentication source for Keycloak -->
<OpenIdAuthenticationSource
    id="as-keycloak"
    displayName="Authentication from Keycloak"
    enabled="true">
    <Reference refId="ds-keycloak" type="DataSource"/>
    <AttributeMapping>
        <AttributeMapEntry localName="username" nativeName="preferred_username"/>
        <AttributeMapEntry localName="mail" nativeName="email"/>
        <AttributeMapEntry localName="givenName" nativeName="given_name"/>
        <AttributeMapEntry localName="surname" nativeName="family_name"/>
    </AttributeMapping>
</OpenIdAuthenticationSource>

Add authentication and authentication contract

These blocks define the login method and contract for Keycloak.

<Authentication allowDisabledContracts="true">
    <!-- Make Keycloak the default login method -->
    <Reference refId="keycloak-contract" type="AuthContractOrGroup" decorator="default"/>
    
    <!-- ... other authentication methods ... -->
    
    <OpenIdAuthentication
        id="keycloak-auth"
        displayName="Keycloak Login"
        enabled="true">
        <Reference refId="as-keycloak" type="AuthenticationSource"/>
    </OpenIdAuthentication>
    
    <!-- Authentication contract for Keycloak -->
    <AuthContract
        id="keycloak-contract"
        displayName="Keycloak Login"
        uri="dimensions:user:keycloak">
        <Reference refId="keycloak-auth" type="ContractExecutable"/>
    </AuthContract>
    
    <!-- ... other contracts ... -->
</Authentication>

Add security block

OSP's built-in Anti-CSRF protection can interfere with the OIDC redirect flow. Add this block to disable it if you encounter CSRF-related errors after authenticating with Keycloak.

<Security>
    <AntiCSRF>
        <DoubleSubmit enabled="false" useHostPrefix="false"/>
        <VerifyOrigin enabled="false" userRefererAsFallback="false"/>
    </AntiCSRF>
</Security>

Back to top

Step 3: Restart OSP

Restart OSP to apply the configuration changes.

To restart OSP:

Run one of the following commands:

sudo systemctl restart osp

Or:

sudo rcosp restart

Back to top

Troubleshooting

The following table describes common issues and their resolutions:

Back to top

See also:

• One SSO Provider (OSP)