You are not logged in. Click here to log in.

codeBeamer ALM

Search In Project

Search inClear

Tags:  not added yet

Single Sign-On via OpenID Connect (OAuth2)

Starting with release 9.3, codeBeamer also supports Single Sign-On via MITREid Connect, a certified OpenID Connect reference implementation in Java on the Spring platform by the MIT Internet Trust Consortium.

OpenID Connect is a simple identity layer on top of the OAuth2 protocol, that allows codeBeamer to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User.

Interactive authentication at Web GUI

When interactively accessing the codeBeamer Web GUI via a Web Browser (User Agent), codeBeamer will act as the Client Application and also as the Resource Server in the OpenID Connect Authorization Code Flow:

The authentication and authorization GUI is solely provided by the Authorization Server. See examples for Google and MITREid Connect below.

The codeBeamer Login Page will not be used and codeBeamer will also never know the credentials of the authenticated users.

If there is no account for an authenticated user yet, a new account will be created with the user info provided by the Authorization Server, and default settings for

  • User Licenses and
  • User Group Memberships.

User account matching is done via the first non-empty value of the following user info profile claims:

  • preferred_username
  • nickname
  • name
Any whitespace in the resulting codeBeamer user account name will be removed.

An interactive user logout at codeBeamer will
If the Authorization Server offers front-channel logout, logging out at the Authorization Server will also indirectly log out that user from codeBeamer.

Example 1: Sign In with Google

When using the Google Authorization Server, standard Google Web Single Sign-On will be applied, where you first have to enter you username/email and then your password:

<Client Name> will be the name of your codeBeamer instance.

Clicking Next on the second screen will redirect you to codeBeamer, where you are logged in with your Google account.

Upon logout from codeBeamer, the user will be redirected to Google's logout page:

Example 2: Sign In with MITREid Connect

When using the MITREid Connect Authorization Server, the screens are completely different:

If not already logged in (Single Sign-On), you have to authenticate yourself:

If you did not already authorize the current client (codeBeamer instance), you are asked to do so, which you may also Deny:

<Client Name> will be the name of your codeBeamer instance.

Before clicking on Authorize, you can optionally

  • restrict the client's access to your personal information, e.g. hide your address,
  • and also define how long this authorization should be valid.

Upon logout from codeBeamer, the user will be redirected to the OpenID Connect Server's logout page:

REST-API authentication via OAuth2

If a 3-rd party Client Application wants to access an OpenID Connect protected codeBeamer instance (e.g. via the REST API), then codeBeamer only acts as the Resource Server, and the Client Application is responsible for obtaining an OAuth2 access token from the appropriate Authorization Server and passing it on to codeBeamer with each request:

Before you can configure a codeBeamer instance to authenticate users via OpenID Connect/OAuth2, you have to register that codeBeamer instance as a Client at the chosen OpenID Provider (OP).

OpenID Provider

You can choose public OpenID Providers, e.g.

or you can setup your own (certified) corporate OpenID Connect provider, e.g.
One CodeBeamer instance can only have a single OpenID Provider.

OpenID Client Registration

The Client registration process depends on the chosen OpenID Provider, but typically you will always have to provide:

  • A Client Name and optional Description
  • Information about the Client Application:
    • Name, e.g. codeBeamer
    • Type (codeBeamer is a Public Web application)
    • Logo, e.g.
    • Homepage, e.g.
    • Privacy Policy link, e.g.
    • Terms of Service link (optional)
  • One ore more Contacts (email addresses)
  • The Scopes required by the Client:
    • openid (required)
    • profile (required)
    • email (required)
    • phone (optional but recommended)
    • address (optional but recommended)
    • offline_access (optional)
  • The Client Login Redirect URI (required for Step 4. of the Authorization Code Flow, see picture above)
    This must be the absolute login URL of the codeBeamer instance, e.g. http[s]://<hostname>[:<port>][/cb/]/login.spr.
  • The Client Front-Channel Logout URL (optional, not all Authorization Servers/OpenID Providers support front-channel logout)
    This must be the absolute logout URL of the codeBeamer instance, e.g. http[s]://<hostname>[:<port>][/cb/]/logout.spr.
  • Whether the Client is allowed to access the Token Introspection Endpoint.
    Introspection is required for codeBeamer in it's role as Resource Server!

After successful registration, the Client must also have:

  • A Client ID
  • A Client Secret

OpenID Connect Configuration

The configuration for OpenID Connect is stored in System AdminApplication Configuration in the section openId, e.g.:

    "openId" : {
        "client" : {
            "clientId" : "",
            "clientName" : "Your CodeBeamer Instance",
            "clientSecret" : "lkfjdu736ei7hJF#3",
            "tokenEndpointAuthMethod" : "SECRET_BASIC",
            "scope" : "openid, profile, email",
            "redirectUris" : "",
            "userName": "preferred_username",
            "reuseDefaultAccount" : true
        "server" : {
            "issuer"                   : "",
            "authorizationEndpointUri" : "",
            "tokenEndpointUri"         : "",
            "jwksUri"                  : "",
            "userInfoUri"              : "",
            "introspectionEndpointUri" : "",
            "revocationEndpointUri"    : "",
            "endSessionEndpoint"       : ""

The server section contains information about the OpenID Provider, e.g. Google.

The client section contains information about the registration of this codeBeamer instance at that OpenID Provider:
  • clientId is the unique ID assigned to this codeBeamer instance during client registration
  • clientName is the optional name assigned to this codeBeamer instance during client registration
  • clientSecret is the secret assigned to this codeBeamer instance during client registration, that is required for client authentication at the server.
  • scope is a comma-separated list of the Scopes required by the Client
    • openid (required)
    • profile (required)
    • email (required)
    • phone (optional but recommended, if supported by provider)
    • address (optional but recommended, if supported by provider)
    • offline_access (optional, if supported by provider)
  • redirectUris (required for Step 4. of the Authorization Code Flow, see picture above)
    This must be the same absolute login URL of the codeBeamer instance, e.g. http[s]://<hostname>[:<port>][/cb/]/login.spr as registered at the provider.
  • userName defines, which userinfo claim (in descending order) to use as the user name of an authenticated user
    • The default userName is sub, but depending on your OpenID Connect Provider, preferred_username may be more appropriate.
    • You can also specify multiple claims from the profile scope (comma-separated), e.g. "preferred_username, name".
      In this example: If a preferred_username is present, it's value will be used, otherwise the value of name, etc.
    • Even if sub is not specified, the value of sub will always be the default, if no claims are specified or none of the claims has a value.
  • reuseDefaultAccount if this is true, then the default/initial system admin account ("bond") will be reused for the first user, that logins in via OpenID Connect, making this user the default system administrator.
  • tokenEndpointAuthMethod should always be SECRET_BASIC, unless you are told differently by your OpenID Connect Provider.

Please note: The OpenID Connect configuration is only read once upon codeBeamer startup. Modifications of the Application Configuration will only have an affect after a re-start.

See also Docker compose with OpenID setup, how to configure a Docker container with OpenID Connect.


With OAuth2/OpenId Connect authentication in affect:

  • Interactive login to codeBeamer is only possible, if the OpenID Connect Provider (Authorization Server) is reachable from the Web Browser of the user.
    • Fallback to internal codeBeamer login is not possible, because user accounts, that were created from OpenID Connect user info, do not have a passwort.
  • Access to the REST API requires an OAuth2 access token.
    Basic and Digest authentication will not work.