Skip to main content
Version: Release 22.2

Set Up the OpenID Connect (OIDC) Authentication for Release

This topic describes how to configure Release authentication using the OpenID Connect (OIDC) protocol. OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 protocol and supported by various OAuth 2.0 providers.

  • OIDC defines a sign-in flow that enables a client application to authenticate a user. User identity information is encoded in a secure JSON Web Token (JWT), called ID token.
  • You can log into Release using various Identity providers that support the OIDC authentication protocol, such as OKTA, Keycloak, and Azure Active Directory (Office 365).
  • You can easily add an additional layer of security for Release by enabling multi-factor authentication (MFA).
  • Using MFA, and depending on your identity provider settings, users are required to acknowledge a verification phone call, text message, or app notification on their smart phones after correctly entering their passwords.

Requirements​

The Release OIDC Authentication plugin must be installed.

Do you want to login as an internal user?​

  • The Release OIDC Authentication plugin offers a seamless user experience by automatically redirecting an unauthenticated user to the Identity Provider's login page.
  • This does not allow you to sign in directly as an Internal User. If you want to sign in as an Internal User, you can go directly to the login page, xl-release.example.com/login, for example.
  • The xl-release.example.com/login page is also an entry point when a local account has an identical username with another user from your Identity Provider. The user is automatically redirected to the page with a corresponding message.
  • OpenID Connect provider and Release instances should be time synchronized. For example, on NTP.

Configure Digital.ai Release for OIDC Authentication​

Do this on the Digital.ai Release server.

Step 1—Download and Install the Release OIDC Authentication Plugin​

The Release OIDC Authentication plugin is bundled with the distribution for Release 10.1.0 and later. You can also download it from the distribution site if required and follow install a plugin steps in Release.

Step 2—Configure the OIDC Authentication Plugin​

This step includes retrieving metadata, modifying the config file, and setting up the post-login URL.

  1. Retrieve the metadata using a discovery endpoint.

    • The discovery endpoint is a static page that you use to retrieve metadata about your OIDC Identity Provider.
    • In most of the cases the discovery endpoint is available through /.well-known/openid-configuration relative to the base address of your Identity Provider.
    • For example: https://login.microsoftonline.com/xebialabs.com/.well-known/openid-configuration.
    • The field names and values are defined in the OpenID Connect Discovery Specification.
    • In OIDC there are notions called scopes and claims that define the settings to obtain information about a specific user, such as the username, name, email, and group.

    You can provide the required claims using the following configuration properties:

    • rolesClaim - In Release, the OIDC roles become principals that you can assign to roles inside Release. Each time you login, the rolesClaim is matched to the principal assigned to the role in Release. This grants access according to the permissions of the role in Release.

      Nested Claims for Release Roles Mapping:

      • Digital.ai Release supports nested claims for Release roles mapping. The . acts as a path separator and if needed can be escaped with backslash \\..
            {​
              ...​
              "realm_access": {​
                "roles": [​
                  "default-roles-digitalai",​
                  "dai-user",​
                  "offline_access",​
                  "uma_authorization"​
                ]​
              }...​
            }​
      • Nested claim such as rolesClaim="realm_access.roles" are supported, where . acts as a path separator.
      • To prevent nesting and use dot literally, escape the dot with backslash (\.). For example, rolesClaim="realm_access\\.roles"​

    • userNameClaim - A unique username for both internal and external users. You cannot sign in with a user if a local account with the same username exists.

    • emailClaim - An email address is required to send notifications. For example, you can be notified when a task that is assigned to you starts.

    • fullNameClaim - The full name of the user profile.

    • externalIdClaim - A unique external ID such as the user's employee ID or GitHub ID. This is an optional claim.

Notes:

  • The userNameClaim, emailClaim, and fullNameClaim properties are used to create the user profile when you log on to Release for the first time. Thereafter, profile update happens every time the user logs on to Digital.ai Release. Roles are used dynamically.
  • Optionally, you can also add the externalIdClaim—which can be the user's employee ID or GitHub ID, for example—to the user profile.
  • The fields described above must be present in the scopes that you can provide from scopes.
  • The issuer, accessTokenUri, userAuthorizationUri, and logoutUri options are also usually presented in the JSON metadata that the Identity Provider server publishes at the discovery endpoint.
  • The redirectUri endpoint must always point to the /oidc-login Release endpoint. The redirectUri is an endpoint where authentication responses can be sent and received by Release. It must exactly match one of the redirect_uris you registered in OKTA and Azure AD portal and it must be URL encoded. For Keycloak you can register a pattern for redirect_uri from the Keycloak Admin Panel (For example, you can provide a mask such as: http://example.com/mask** that matches http://example.com/mask/ or http://example.com/mask).

  1. Modify the xl-release.conf file.

    To configure the OIDC Authentication plugin, modify the XL_RELEASE_SERVER_HOME/conf/xl-release.conf file by adding a xl.security.auth.providers section. Here's an example.

    xl {
      security {
        auth {
          providers {
            oidc {
              clientId="<your client id here>"
              clientSecret="<your client secret here>"

              issuer="<OpenID Provider Issuer here>"        
              redirectUri="https://xl-release.example.com/oidc-login"
              postLogoutRedirectUri="https://xl-release.example.com/oidc-login"

              scopes=["<your>", "<scopes>", "<here>"]

              rolesClaim="<your roles claim here>"
              userNameClaim="<your username claim here>"
              emailClaim="<your email claim here>"
              fullNameClaim="<your fullName claim here>"
              externalIdClaim="<user's employee ID or GitHub ID, for example>" //This is an optional claim
            }
          }
        }
      }
    }

    The above configuration automatically fetches the required configuration from the discovery endpoint. The discovery endpoint is a static page that you use to retrieve metadata about your OIDC Identity Provider.

    In most of the cases, the discovery endpoint is available through /.well-known/openid-configuration relative to the base address of your Identity Provider. For example: https://login.microsoftonline.com/xebialabs.com/.well-known/openid-configuration.

    For more information, see OpenID Connect Discovery Specification.

  2. Override the values from the discovery endpoint.

    It is possible to override the values for keyRetrievalUri, accessTokenUri, userAuthorizationUri, and logoutUri by adding the values explicitly. This is useful if the discovery endpoint is not reachable. Here's an example.

    xl {
      security {
        auth {
          providers {
            oidc {
              clientId="<your client id here>"
              clientSecret="<your client secret here>"
              clientAuthMethod="<your client authentication method here>"
              issuer="<OpenID Provider Issuer here>"        

              keyRetrievalUri="<The jwks_uri to retrieve keys>"
              accessTokenUri="<The redirect URI to use for returning the access token>"                  
              userAuthorizationUri="<The authorize endpoint to request tokens or authorization codes via the browser>"
              logoutUri="<The logout endpoint to revoke token via the browser>"

              redirectUri="https://xl-release.example.com/oidc-login"
              postLogoutRedirectUri="https://xl-release.example.com/oidc-login"

              scopes=["<your>", "<scopes>", "<here>"]
              idTokenJWSAlg="<The ID token signature verification algorithm>"

              rolesClaim="<your roles claim here>"
              userNameClaim="<your username claim here>"
              emailClaim="<your email claim here>"
              fullNameClaim="<your fullName claim here>"
              externalIdClaim="<user's employee ID or GitHub ID, for example>" //This is an optional claim          

              // proxyPort and proxyHost are optional parameters -
              // available in Release 8.2.0 and later.
              proxyHost="your-proxy-host-here.example.com"
              proxyPort="3128"
            }
          }
        }
      }
    }

  3. Set up the post-logout URL.

    • The logout works by directing the user’s browser to the end-session endpoint of the OpenID Connect provider, with the logout request parameters encoded in the URL query string.
    • If you need to redirect to the login page after logout, you can use your redirectUri as the postLogoutRedirectUri.

  4. Do you want to send additional parameters to the OIDC provider?

    You can send additional parameters to the OIDC provider as part of the OIDC authentication request.

    Here's an example, in which you can find two additional parameters—param1 and param2.

    xl {
      security {
        auth {
          providers {
            oidc {
              clientId = "aiRelease"
              clientSecret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

              issuer = "<OpenID Provider Issuer here>"
              redirectUri = "https://xl-release.example.com/oidc-login"
              postLogoutRedirectUri = "https://xl-release.example.com/oidc-login"

              scopes = ["openid", "workforce"]

              rolesClaim = "ad_groups"
              userNameClaim = "sub"
              emailClaim = "attr_email"
              fullNameClaim = "attr_lastname"
              additionalParameters = {
                "param1" = false
                "param2" = "str"
              }
            }
          }
        }
      }
    }

    With such a configuration, the additional parameters are passed in the login URL as shown in the following example request URL.

    https://example.okta.com/oauth2/.../.../code_challenge=xyz&`param1=false&param2=str`

Client Authentication​

Clients are required to authenticate against an authorization server (such as Keycloak).

The following client authentication methods are supported:

ValueDescription
client_secret_basicAuthenticate using HTTP Basic authentication scheme
client_secret_postAuthenticate by including the Client Credentials in the request body. This is the default authentication method supported by Digital.ai Release.
client_secret_jwtOne of the client authentication methods defined in OpenID Connect Client Authentication.
private_key_jwtOne of the client authentication methods defined in OpenID Connect Client Authentication.

For more information, see Client Authentication

By default, client_secret_post authentication method is used. You can also override default values as shown below.

xl {
  security {
    auth {
      providers {
        oidc {
          clientAuthMethod = "<Expected client authentication method>"
          ...
        }
      }
    }
  }
}

For more information, see Using OpenID Connect to secure applications and services.

  • Digital.ai Deploy and Release—22.1 and later—support client_secret_jwt and private_key_jwt methods to authenticate clients with OIDC-based ID providers such as Keycloak.
  • The JWT assertion must be digitally signed using a private key in asymmetric cryptography.
  • Digital.ai Deploy and Release—22.1 and later—support signed JWTs only—it does not extend to encrypted JWTs encoded in a JSON Web Encryption (JWE) structure.

ID Token Signature Verification​

The ID Token is represented as a JSON Web Token (JWT) and MUST be signed using JSON Web Signature (JWS).

Clients are required to validate ID Token. The default algorithm for signature verification is RS256. You can use idTokenJWSAlg parameter as described in above configuration file to set different value. The following JSON Web Algorithms (JWA) are supported:

ValueDigital Signature or MAC Algorithm
RS256RSASSA-PKCS1-v1_5 using SHA-256
RS384RSASSA-PKCS1-v1_5 using SHA-384
RS512RSASSA-PKCS1-v1_5 using SHA-512
ES256ECDSA using P-256 and SHA-256
ES384ECDSA using P-384 and SHA-384
ES512ECDSA using P-521 and SHA-512
PS256RSASSA-PSS using SHA-256 and MGF1 with SHA-256
PS384RSASSA-PSS using SHA-384 and MGF1 with SHA-384
PS512RSASSA-PSS using SHA-512 and MGF1 with SHA-512
HS256HMAC using SHA-256
HS384HMAC using SHA-384
HS512HMAC using SHA-512
note

For MAC based algorithms such as HS256, HS384 or HS512, the clientSecret corresponding to the clientId is used as the symmetric key for signature verification.

Client Authentication​ Using client_secret_jwt​

Digital.ai Release supports client authentication using the client_secret_jwt method.

The following JSON Web Algorithms (JWA) are supported:

  • HS256 (HMAC using SHA-256)​—this is the default if you use the client_secret_jwt authentication method
  • HS384 (HMAC using SHA-384)​
  • HS512 (HMAC using SHA-512)

You can configure the desired JWS algorithm using the xl.security.auth.providers.oidc.clientAuthJwt.jwsAlg​ key.

Here's an example xl-release.conf file that uses the client_secret_jwt authentication method.

xl {​
  security {​
    auth {​
      providers {​
        oidc {​
          clientAuthMethod = "client_secret_jwt"        
          clientAuthJwt {​
            jwsAlg = "HS256​" // Expected JSON Web Algorithm
          }​

          ...​
​
        }​
      }​
    }​
  }​
}

Client Authentication​ Using private_key_jwt​

Digital.ai Release supports client authentication using the private_key_jwt method.

The following JSON Web Algorithms (JWA) are supported:

  • RS256 (RSASSA-PKCS1-v1_5 using SHA-256)​​—this is the default if you use the private_key_jwt authentication method
  • RS384 (RSASSA-PKCS1-v1_5 using SHA-384)​
  • RS512 (RSASSA-PKCS1-v1_5 using SHA-512)​
  • ES256 (ECDSA using P-256 and SHA-256)​
  • ES384 (ECDSA using P-384 and SHA-384)​
  • ES512 (ECDSA using P-521 and SHA-512)​
  • PS256 (RSASSA-PSS using SHA-256 and MGF1 with SHA-256)​
  • PS384 (RSASSA-PSS using SHA-384 and MGF1 with SHA-384)​
  • PS512 (RSASSA-PSS using SHA-512 and MGF1 with SHA-512)​

Here's an example xl-release.conf file that uses the private_key_jwt authentication method.

xl {​
  security {​
    auth {​
      providers {​
        oidc {​
          clientAuthMethod = "private_key_jwt"​
          clientAuthJwt {​
            jwsAlg = "PS256"​​ // Expected JSON Web Algorithm
            keyStore {​
              path = "conf/oidc-keystore.p12"​ // The key store file path
              password = "mypassword"​ // The key store password
            }​
            key {​
              alias = mykeyAlias // Private key alias inside the key store
              password = "mykeyAliasPassword"​ // Private key password
            }​
            tokenKeyId = "mykey"​ // This is a token key identifier 'kid' header - set it if your OpenID Connect provider requires it
          }​
          ...
        }​
      }​
    }​
  }​
}​

Bearer Token Authentication for REST APIs​

It is possible to use OAuth 2.0 token to access public REST APIs. By default, RS256 algorithm is used to validate the token. You can also override default values as shown below.

xl {
  security {
    auth {
      providers {
        oidc {
          ...
          access-token {
            issuer = "<Expected issuer 'iss' claim value>"
            audience = "<Expected audience 'aud' claim value>"
            keyRetrievalUri = "<The jwks_uri to retrieve keys for the token>"
            jwsAlg = "<The token signature verification algorithm>"
            secretKey = "<The secret key if MAC based algorithms is used for the token>"
          ...
          }
        }
      }
    }
  }
}

Default values for access token configuration properties are described below:

Configuration propertyDefault
xl.security.auth.providers.oidc.access-token.issuerOIDC issuer xl.security.auth.providers.oidc.issuer
xl.security.auth.providers.oidc.access-token.audienceOIDC clientId xl.security.auth.providers.oidc.clientId
xl.security.auth.providers.oidc.access-token.keyRetrievalUriOIDC jwks_uri xl.security.auth.providers.oidc.keyRetrievalUri
xl.security.auth.providers.oidc.access-token.jwsAlgRS256
note

Token must contain userNameClaim and rolesClaim to map proper roles in release.

Disable OIDC Authentication​

By default, Release checks for the path xl.security.auth.providers.oidc in xl-release.conf file. If it is present, Release will enable OIDC Authentication. You can also use below toggle to enable and disable the behavior.

xl {
  security {
    auth {
      providers {
        oidc {
          enabled = true //false if you want to disable OIDC Authentication
          ...
        }
      }
    }
  }
}

Integration with Keycloak Identity Provider​

Installing Keycloak​

  1. Download the latest version of Keycloak
  2. Unpack the file, open a terminal window and go to the directory where you extracted the file.
  3. Go to the bin directory and run standalone.sh.
  4. By default, Keycloak runs on port 8080. Using your browser, navigate to that location and create an admin user (example: admin/admin).
  5. When the admin user is created, go to the Administration Console.

Setting Up Keycloak for Release​

For more information, see Configure OpenID Connect (OIDC) Authentication with Keycloak.

  1. On the top left, navigate to Master, open the drop down menu, and click Add realm.

  2. Set the name to XLRelease, and save it.

  3. Set the Display name to Release.

  4. On the sidebar, select Clients

  5. Click create, set the client ID to Release Server, and click Save.

  6. Set Access Type to Confidential, and add the URL to your Release server (for example: http://localhost:4516/) as Valid Redirect URI.

  7. Click Save. A new Credentials tab appears.

    To add roles to Keycloak, select Roles on the sidebar. These will be mapped to the Release principals later. For example: If you create a user JohnDoe and you assign the role admins to the user, and in Release you assign admin permission to admins, then the JohnDoe user can log in as an admin in Release.

  8. On the sidebar, under Users, click Add user. Set the username to JohnDoe and click Save.

  9. Select the Credentials tab and specify a password.

    If you have created roles, go to the Role Mappings tab and add the desired roles.

  10. Click Clients in the sidebar, go to the Mappers tab, and click Create.

  11. Specify a name (for example: group memberships), set the Mapper Type to Group Membership, set the Token Claim Name to groups, and set the Add to ID Token to ON.

Integration with OKTA Identity Provider​

You can register an OAuth client by creating a new application integration from the OKTA Admin interface:

  1. Log in to your OKTA organization as an administrator.
  2. Click Admin.
  3. From Shortcuts on the right side of the screen, click Add Applications.
  4. Click Create New App on the left side of the screen.
  5. Select OpenID Connect as the Sign on method.
  6. Configure one or more Redirect URIs for your Release application.
  7. Click Finish

Using the People or Groups tabs, assign people to your newly created Release application.

note

Users cannot authenticate to your Release application if they are not assigned.

Find your Client ID in the Client Credentials section of the Groups tab. You will use the Client ID that you just obtained to configure the Release server as it was described above.

for more information on how to configure OKTA, refer to OKTA documentation.

Integration with Azure Active Directory (Office 365)​

Register your application as described here and use https://login.microsoftonline.com/{your tenant id}/.well-known/openid-configuration to collect configurations.

Using OIDC with DevOps as Code​

The DevOps as Code CLI is not compatible with OIDC's authentication method. As a workaround, if your Release instance is configured to use OIDC, you can create a devops-as-code internal system user to work with the CLI.

Debugging​

To enable extra debugging in case of any failures, modify logback.xml file and add below logger.

<logger name="org.springframework.security" level="trace" />