Configure OAuth2 for DirX Identity Business User Interface and REST Service with Red Hat Keycloak IdP

Configure Red Hat Keycloak

All the settings described below are against RedHat Keycloak version 21.1 and are recommended settings for development and testing and should not be used in any production environment. All settings are suggested and for production environment consult official documentation available on product website.

Create a Keycloak realm

This is like a domain in DirX Identity and defines boundaries and settings for a IdP domain.

Authenticate to Administrative Console with an administrative account and create a new realm. Suggested realm name is my-company, enable this realm and click Create button.

Setup User federation

Switch to newly created realm.

Select User federation and click “Add new provider”, select “LDAP” as provider.

Provide a name (e.g DirX Directory), and at “Vendor” select “Other” from list.

  • Set “Connection URL” to DirX Directory server (e.g., ldap://DXIPTEST01-VM:389)

If highly recommended to evaluate all other options (Enable StartTLS, Use Trusted SPI, etc).

Click “Test connection” button to test connection to LDAP server.

  • Bind type - set as “simple”.

  • Bind DN - set to a proper DN for a admin user (e.g. cn=DomainAdmin,cn=My-Company).

  • Bind credentials – set authentication password for access to DirX Directory (e.g., dirx).

Click “Test authentication” button to test authentication against DirX Directory.

LDAP searching and updating

  • Edit mode - set as “READ_ONLY”.

  • User DN – set DN to Identity Users container (e.g. cn=Users,cn=My-Company)

  • Username LDAP attribute - set to “cn”.

  • RDN LDAP attribute – set to “dn”.

  • UUID LDAP attribute – set to “dirxEntryUUID”.

  • User object classes – leave unchanged. Default value is “inetOrgPerson, organizationalPerson”.

  • User LDAP filter – leave it empty or adjust according to requirements.

  • Search scope – select “Subtree” value.

  • Read timeout – leave it empty or adjust according to requirements.

  • Pagination – set to “Off” or adjust according to requirements.

Synchronization settings

  • Import users – set to “Off”

  • Sync Registration – set to “Off”

  • Batch size – leave empty

  • Periodic full sync – set to “Off”

  • Periodic changed users sync – set to “Off”

Kerberos integration

  • Everything set to “Off”

Cache settings

  • Cache policy – set to “DEFAULT”

Advanced settings

  • Everything set to “Off”.

Click “Save” button to save changes.

Setup Realm settings

  • Select General tab.

    • Realm ID – should be already set to a value provided on create realm action (e.g., my-company).

    • Display name – optional – plain text for realm name.

    • HTML Display name – optional – HTML text for realm name.

    • Frontend URL – optional – leave empty.

    • Required SSL – “External requests”,

    • ACT to LoA Mapping – optional – no entries.

    • User-managed access – set to “Off”.

Highly recommended to follow the “OpenID Endpoint Configuration” link from Endpoints and evaluate the content from this link. This content is used by OAuth2 client during the discovery process.

Click “Save” button to save changes.

  • Select Login tab.
    All values should be set to “Off”

  • Select Email tab.
    Adjust values according to requirements.

  • Select Themes tab.
    Adjust values according to requirements.

  • Select Keys tab.
    Use default values or adjust values according to requirements.

  • Select Events tab.
    Use default values or adjust values according to requirements.

  • Select Localization tab.
    Use default values or adjust values according to requirements.

  • Select Security defences tab.
    Use default values or adjust values according to requirements.

  • Select Sessions tab.
    Use default values or adjust values according to requirements.

    Here can be change the Offline Session tokens lifespan.

  • Select Tokens tab.
    Use default values or adjust values according to requirements.

    Here can be change the Session tokens lifespan and default signature algorithm, should be “RS256”.

  • Select Client policies tab.
    Use default values or adjust values according to requirements.

  • Select User registration tab.
    Use default values or adjust values according to requirements.

Setup a client

Click “Create client” button

  • Client type - select “OpenID Connect”.

  • Client ID – set client name (e.g., dxibui).

  • Name – display name for client (e.g., DirX Identity Business User Interface).

  • Description – description of the client.

  • Always display in UI – set to “On”

Click “Next” button to continue.

  • Client authentication – IMPORTANT – set to “Off”.

  • Authorization – set to “Off”.

  • Authentication flow – set “Standard flow” and “Direct access grants” to “On”, everything else set to “Off”

Click “Next” button to continue.

  • Root URL – optional – set this value according to requirements.

  • Home URL – optional – set this value according to requirements.

  • Valid redirect URL – set this value according to requirements (e.g., http://localhost:8080/BusinessUserInterface-My-Company/*.

  • Valid post logout redirect URIs – set this value according to requirements (e.g., for tests put + character).

  • Web origins – set this value according to requirements (e.g., for tests put + character).

Click “Save” button to save changes.

Select client for the list and review the settings in Settings tab.

  • Select Roles tab.

    • Leave empty.

  • Select Client scopes tab.

    • acr - set to “Default”

    • offline_access - set to “Default”

    • profile – set to “Default”

    Everything else set to “Optional”.

  • Select Sessions tab.

    • Should be empty

  • Select Advanced tab.

    • Change values according to requirements.

    • Proof Key for Code Exchange Code Challenge Method – IMPORTANT – set to “S256”

Click “Save” button to save changes.

Select a Client scope (Audience)

Select Client scopes menu entry.

Click “Create client scope” button.

  • Name – set a name for client scope (e.g., DXI_Audience)

  • Description – provide a description for client scope.

  • Type – set to “Default”.

  • Protocol – set to “OpenID Connect”.

  • Display on content screen – set to “On” or “Off”

  • Consent screen text – optional – provide a text for consent screen.

  • Include in token scope – IMPORTANT - set to “On”

  • Display Order – leave empty.

Click “Save” button to save changes.

Select newly created client scope from list.

  • Select Mappers tab.

    • Click “Add mapper” button and select “By Configuration” option.

    • Select “Audience” from list.

    • Mapper type – set to “Audience”.

    • Name – name of mapper (e.g., DXI_audience).

    • Included Client Audience – IMPORTANT – select from list the client (e.g., dxibui).

    • Included Custom Audience – leave empty.

    • Add to ID token – set to “Off”.

    • Add to access token – IMPORTANT – set of “On”

Click “Save” button to save changes.

Select Clients menu entry.

Click to the client (e.g., dxibui) from list.

Select tab Client scopes.

Click Add client scope, select client scope from the list, select Default and confirm changes.

Click “Save” button to save changes.

Now Keycloak should be ready for use for OAuth2-OIDC-PKCE setup.

Configure DirX Identity REST Services

  • Stop Apache Tomcat server

  • Locate security.properties file inside DirX Identity restServices installation folder.

    • Go to OAUTH2 / JWT authentication section.

    • Set auth.jwt.authenticationClaimAudiences to values from audicences map for client scope (e.g., dxibui)

    • Check value for auth.jwt.authenticationClaimName, default value is set to preferred_username.

    • Check value for all other entries. Default values are set to search for enabled users in DXI user container and use the CN as value select, search users by cn.

    • Save the file.

  • Locate security-oauth2.xml file inside authenticationSamples folder.

    • Inside file, find jwk-set-uri entry, and replace "place here jwk-set-uri url" text with the URL to Keycloak server. This value can be obtained by going to <realm-name> → Realm Settings menu → Endpoints → OpenID Endpoint Configuration (e.g., jwt-set-uri= "http://dxiptest01-vm:9090/realms/my-company/protocol/openid-connect/certs")

    • Save the file.

    There are two variants:

    Variant 1) Copy security-oauth2.xml to the upper folder with a new name security.xml and replace existing security.xml file.

    Variant 2) Merge content of security-oauth2.xml with content of the security.xml file for above folder.

  • Start Apache Tomcat server

Configure DirX Identity Business User Interface

all settings are case-sensitive.

  • Locate config.json file inside DirX Identity BUI installation folder.

  • Go to oauth2AuthServer section

    • protocol – set to “http” or “https”

    • host – set host name of the rest services (e.g., “DXIPTEST01-VM”)

    • port – set port for the rest services (e.g., “8080”)

    • domain – set the rest services DXI domain (e.g., “/DirXIdentityRestService-My-Company”

    • clearHashAfterLogin – leave to true

    • clientId – IMPORTANT – set the client id configured in Keycloak (e.g., “dxibui”)

    • issuer – IMPORTANT – set the issuer URL. This value can be obtained by going to <realm-name> → Realm Settings menu → Endpoints → OpenID Endpoint Configuration (e.g., http://dxiptest01-vm:9090/realms/my-company).

    • redirectUri – IMPORTANT – “/main”. This value must match with settings from Keycloak

    • requireHttps – IMPORTANT – For tests this value can be set to false, for production this must be always true.

    • scope – “openid offline_access” – “offline_access is required for token refresh action

    • sessionChecksEnbled – set to false,

    • showDebugInformation – set to true,

    • silentRefreshUri – not used.

    • timeoutFactor – default value in 0.75. This value represents a percent and is used to refresh an access token. As example, for default value, when ¾ of access token validity time is passed and a new access token is requested from Keycloak.

    • useHashLocationStrategy – for now only option is true

    • useSilentRefresh – set to false

  • Go to security section

    • authentication - add “OAUTH2” to the list. Order is important.

  • Save the file and reload Business User Interface in browser.