Configure the DirX Identity Business User Interface with OAuth2 (OIDC/PKCE)

Start DirX Access Services

Start DirX Directory service (if is necessary).
Start DirX Access Service domain service (e.g. DirX Access Services My-Company).
Start DirX Access domain LoadBalancer service (only if DirX Access is configured with Load Balancer feature enabled).
Start DirX Access Extensions Apps (optional).

Configure DirX Access for OAuth2 Protocol

This chapter describes how to configure DirX Access 9.x product (with SP1) for OAuth2 protocol. From OAuth2 protocol will use Open ID Connector with PKCE protocol extension.

Follow these steps:

Open in a web browser the DXA console interface (e.g., http://my-server.my-company.example:10114/console/ManagementFrameSet).
Authenticate to DXA console (default credentials are: dirxaccessadmin/dirxaccess)
Create and configure port assignments - this step will create port used by DirX Access to provide services (authentication and authorization) to other applications.
- Navigate to Servers→Port Assignments.
- Create or duplicate a new Port assignment (top-right button).
- Save changes
Create a new DirX Access server or use an existing one
- Navigate to Servers→Server list
- Create a new server (top-right button)
- Configure DXA server:
  - “Identifier” - this is the DXA server identifier and is used to identify this server through the DXA settings.
  - “IP address” - this is the DXA server IP address
  - “Server hostname” - this is the DXA hostname server. This value should be used in any connection settings and security settings (e.g., server certificates).
  - “Port assignment” - this port assignments are created and assigned to current server, from Port Assignments settings.
- Save changes
Check Users list from a connection to an LDAP server.
- Navigate to Users→List
- heck if users are available, and connection to DirX Directory works.
- If users are not available check settings in Configuration→User repository
Configure Client metadata
- Navigate to Federation→OAuth→Client metadata.
- Create new Client metadata (top-right button)
- Configure Client metadata:
  - “client_id” - client_id value will be used by the OAuth2 client application, e.g., for BUI can be dxiBUIApplication.
  - “client_type” - this defines where the OAuth2 client application is running. For almost all SPA web applications, this value must be set to public, because the web browser is not considered a trusted environment to run an application.
  - “token_endpoint_auth_method” - set this value to none. For other options, consult DXA official documentation.
  - “redirect_url” - this URL is used by the OAuth2 server to redirect back to the client after the authentication process is completed (with success or not). The client application must be able to handle this redirect and detect is authentication was successful (OpenID token is available and valid).
  - “grant_types” - this are grant type required by OAuth2 OpenID protocol and must be: authorization_code, implicit and refresh_token. For other available options, consult OpenID protocol specifications.
  - “response_type” - this are responses required by OAuth2 OpenID protocol and must be: code, token, id_token, id_token_token. For other available options, consult OpenID protocol specifications.
  - “scope” - this are scopes requested by the client. For this scenario only openid and offline_access are required, but if is necessary this scope can be extended with other values (profile, email, etc.).
- Save changes

Example for a Client metadata configuration for DirX Identity Business User Interface:

{
   "client_id": "dxiBUIApplication",
   "client_type": "public",
   "token_endpoint_auth_method": "none",
   "redirect_uris": [
      "https://bui.my-company.example:4123/login"
   ],
   "grant_types": [
      "authorization_code",
      "implicit",
      "refresh_token"
   ],
   "response_types": [
      "code",
      "token",
      "id_token",
      "id_token_token"
   ],
   "scope": "openid offline_access"
}

Configure Client endpoints (optional)
- Navigate to Federation → OAuth → Client endpoints
- Create a new or modify current Client endpoint (top-right button).
- Go to OAuth client endpoint settings.
- Change “OAuth authentication method” to OAuth Authentication.
- Change “Default partnership (client) metadata” to Client metadata configuration created above (e.g., dxiBUIApplication)
- Save changes.
Configure Keystore
- Navigate to Key management → Features → Generate Sample.
- Set “Identifier” (e.g., dxiBUIOAuthId).
- Set “Password” (e.g., dirx).
- “Client Verification” - set Sample type to Client Verification.
- Generate keystore.
Configure Subjects
- Navigate to Subjects → OAuth token → OAuth Attribute template Value Construction.
- Create a new template (top-right button)
- Set “Identifier” (e.g., buiLoginNameValue).
- Set “Return type” to STRING.
- Set “Container” to SSO_SERVICE.
- Set “Abstraction” to AUTHENTICATION_INFO.
- Set “Detail” to AUTHENTICATION_CN.
  
  This field defines which information will be provided to REST service inside the authentication token. In this example is CN.
- Save changes.
- Navigate to Subjects → OAuth token → OAuth Attribute template Construction.
- Create new template (top-right button).
- Set “Identifier” (e.g., dxiBUIOAuthId).
- Set Name (e.g., loginName).
  
  This field will be available in access token with CN of the authenticated user). This field must be processed by DXI REST service as authentication principal.
- Set “Mandatory” to true.
- Set “OAuth attribute value template” - this template was created in the previous step. (e.g., buiLoginNameValue).
- Save changes.
Configure OAuth2 server
- Navigate to Federation → OAuth → Servers.
- Create new OAuth2 server. (top-right button)
- Configure OAuth server:
- Basic settings:
  - “identifier” - set configuration identifier (e.g., dxiOAuthServer).
  - “description” - optional - set configuration description set description
  - “OAuth server endpoint” settings:
    
    check “issuer” (e.g., https://my-server.my-company.example:11115/auth)
    
    select “client metadata” (from right tree), and add newly created client metadata (e.g., dxiBUIApplication).
    
    set “HTTP redirect URI support” to true.
    
    set” Invalid client metadata support” to true for debug.
    
    set “Keystore identifier” (e.g., dxiBUIOAuthId).
    
    set “Keystore password” (e.g., dirx).
    
    set “Signing key alias” to federation-sign.dirxaccess
    
    set “Signing key password” (e.g., dirx or dirxaccess).
- Basic configuration
  - set “OAuth support” to true.
  - set “OpenID Connect support” to true.
- Authorization and Token endpoint configuration
  - set “Grant types” to: authorization_code, implicit and refresh_token.
    
    These values must match and be used the OAuth2 OpenID client application.
  - set “Scopes” to: offline_access and openid.
    
    These values must match and be used the OAuth2 OpenID client application.
  - set values:
    
    (optional) adjust “Authorization code validity” in seconds.
    
    (optional) adjust “Access token validity” in seconds.
    
    IMPORTANT set “Access token representation” to JWT.
    
    set “Refresh token”.
    
    set “Attribute templates” to newly created configuration template (e.g., dxiBuiOAuth).
    
    set “JWE signing key representation” to None.
    
    IMPORTANT set “PKCE for OAuth 2.0 support” to true.
    
    Make sure you installed the latest Service Pack for DirX Access 9.x (default version 9.0 does not work correctly with PKCE extension).
- Save changes.
- (optional) Check server metadata.

Example for a Server metadata configuration from:

https://my-server.my-company.example:11115/auth/.well-known/oauth-authorization-server

{
  "issuer": "https://my-server.my-company.example:11115/auth",
  "authorization_endpoint": "https://my-server.my-company.example:11115/auth/authz",
  "token_endpoint": "https://my-server.my-company.example:11115/auth/token",
  "jwks_uri": "https://my-server.my-company.example:11115/auth/.well-known/jwks.json",
  "scopes_supported": [
  "openid",
  "offline_access"
  ],
  "response_types_supported": [
  "id_token token",
  "code",
  "id_token",
  "token"
  ],
  "response_modes_supported": [
  "fragment",
  "query"
  ],
  "grant_types_supported": [
  "refresh_token",
  "implicit",
  "authorization_code"
  ],
  "token_endpoint_auth_methods_supported": [
  "client_secret_post",
  "none",
  "client_secret_basic"
  ],
  "subject_types_supported": [
  "public"
  ],
  "id_token_signing_alg_values_supported": [
  "HS256",
  "HS512",
  "RS256",
  "HS384"
  ],
  "display_values_supported": [
  "page"
  ],
  "claim_types_supported": [
  "normal"
  ],
  "claims_parameter_supported": false,
  "request_parameter_supported": false,
  "request_uri_parameter_supported": false,
  "require_request_uri_registration": false
}

Configure Provider endpoints
- Navigate to Federation → OAuth → Provider endpoint.
  - Create a new Provider endpoint.
- Set identifier for provider.
  - Set description (optional) for provider
  - Set OAuth server (e.g., dxiOAuthServer).
  - Set/check context path (e.g., /auth).
  - Set/check Primary port assignment identifier (e.g., 11115)
  - Check Token endpoint.
  - Save changes.
Create a new Policy rule - IMPORTANT
- Navigate to Policies → RBAC Authentication → Rules.
  - Create a new rule. (top-right button)
  - Set Identifier (e.g., dxiBUIRules).
  - Set Description (optional).
  - Set Actions (e.g., Any Action).
    
    Selected action: "Any Action" is to general, and should be changed to a more restricted value.
  - Save changes.
  - An authenticated user should be allowed to access DXA resources
  - Navigate to Policies → RBAC Authorization → Policies
  - Set Identifier to User.
  - Add dxiBUIRules as active rule.
  - Save changes.

Configure DXI REST Service

Configure BUI Application

Configuration settings are available in the config.json file, located in the Business User Interface installation folder install_path/web/BusinessUserInterface-domain/assets/config/. The content of this file is case sensitive.

Set following OAuth2 parameters in “oauth2AuthServer” entry:

“clientId” - the application ID used in OAuth2 Identity Provider configuration. The Business User Interface application must be registered to Identity Provider with this id.
“issuer” - the URL to OAuth2 provider.

Issuer examples for different OAuth2 providers:
- for DirX Access:
  https://my-server.my-company.example:11115/auth
- for RedHat Keycloak:
  http://localhost:8180/auth/realms/my-company