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. https://codebeamer.com/cb/images/newskin/header/cblogo-xl.png
    • Homepage, e.g. https://intland.com/application-lifecycle-management/
    • Privacy Policy link, e.g. https://intland.com/privacy-policy/
    • 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.

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.


In CB-9.3, you could only configure one OAuth/OpenID Connect server and client:

    "openId" : {
        "client" : {
            "clientId" : "26576725-kdf73jgfgu7653flfhe7t53.apps.googleusercontent.com",
            "clientName" : "Your CodeBeamer Instance",
            "clientSecret" : "lkfjdu736ei7hJF#3",
            "tokenEndpointAuthMethod" : "SECRET_BASIC",
            "scope" : "openid, profile, email",
            "redirectUris" : "http://intservers.no-ip.biz:58800/cb/login.spr",
            "userName": "preferred_username",
            "reuseDefaultAccount" : true
        },
        "server" : {
            "issuer"                   : "https://accounts.google.com",
            "authorizationEndpointUri" : "https://accounts.google.com/o/oauth2/v2/auth",
            "tokenEndpointUri"         : "https://oauth2.googleapis.com/token",
            "jwksUri"                  : "https://www.googleapis.com/oauth2/v3/certs",
            "userInfoUri"              : "https://openidconnect.googleapis.com/v1/userinfo",
            "introspectionEndpointUri" : "https://www.googleapis.com/oauth2/v3/tokeninfo",
            "revocationEndpointUri"    : "https://oauth2.googleapis.com/revoke",
            "endSessionEndpoint"       : "https://accounts.google.com/logout"
        }
    }


In CB-9.4 and newer, an OAuth/OpenID Connect provider can have it's own

  • server configuration
and different client configurations for
  • OpenID Connect authentication and
  • OAuth2 access token introspection.

E.g.:

    "openId" : {
        "server" : {
            "issuer" : "http://my.oidc.provider"
        },
        "authentication" : {
            "clientId" : "cbAuth",
            "clientName" : "cbAuth@test-pc",
            "clientSecret" : "AIJ0OWXu ...",
            "tokenEndpointAuthMethod" : "client_secret_basic",
            "scope" : "openid, profile, email, phone, address, offline_access",
            "userName": "preferred_username"
        },
        "introspection" : {
            "clientId" : "cbIntro",
            "clientName" : "cbIntro@test-pc",
            "clientSecret" : "wEDO8i3Q ...",
            "tokenEndpointAuthMethod" : "client_secret_basic"
        },
        "reuseDefaultAccount" : true,
        "forceOAuth" : false,
        "cacheSuccessTTL" : "10min",
        "cacheFailureTTL" : "15min"
    }


If an OAuth/OpenID Connect provider does not require different clients for OpenID Connect authentication and OAuth2 access token introspection, then you do not need an extra introspection configuration: Introspection will be done with the authentication configuration.

In that case you can also use client as an alias for authentication.


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

If an OpenID Connect provider supports server configuration discovery, then in CB-9.4 and newer, you only have to provide the server issuer URI, e.g.

   "server" : {
        "issuer" : "https://accounts.google.com"
    }
Otherwise you have to provide information for all the necessary server end-points manually, e.g.:
    "server" : {
        "issuer"                   : "https://accounts.google.com",
        "authorizationEndpointUri" : "https://accounts.google.com/o/oauth2/v2/auth",
        "tokenEndpointUri"         : "https://oauth2.googleapis.com/token",
        "jwksUri"                  : "https://www.googleapis.com/oauth2/v3/certs",
        "userInfoUri"              : "https://openidconnect.googleapis.com/v1/userinfo",
        "introspectionEndpointUri" : "https://www.googleapis.com/oauth2/v3/tokeninfo",
        "revocationEndpointUri"    : "https://oauth2.googleapis.com/revoke",
        "endSessionEndpoint"       : "https://accounts.google.com/logout"
    }
Please note: Although Google supports server configuration discovery, the returned server configuration does not contain the "endSessionEndpoint". Therefore a static configuration is necessary.

If an OAuth/OpenID Connect provider does not require different client configurations for authentication and introspection, then you do not need an extra introspection configuration: Introspection will be done with the authentication (or client) configuration:
  • 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.
  • tokenEndpointAuthMethod defines the method of client authentication against the server (token and/or introspection) end-point.
    Please note: CB-9.3 does only support the special value "SECRET_BASIC", in CB-9.4 and newer, you should use the standard methods:
    • "client_secret_basic" (the default, if not specified)
    • "client_secret_post"
    • "client_secret_jwt"
    • "none"
  • scope is a comma-separated list of the requested Scopes, and only required in the authentication configuration:
    • 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)
  • userName defines, which userinfo claim (in descending order) to use as the user name of an authenticated user.
    Only required in the authentication configuration, unless there is only a introspection configuration
    • 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.

The mapping of other userinfo claims to codeBeamer user attributes is hardcoded as follows:

userinfo claim mapped to attribute
sub eauthid
userName name
given_name firstName
family_name lastName
email email
phone_number phone
address
street_address address
postal_code zip
locality city
region state
country country
locale language
zoneinfo timeZone
profile skills

The user info returned from the user info end-point may also contain other standard claims not listed above, e.g. gender, birthdate or picture, and also additional claims. But this additional info is ignored by codeBeamer.

Advanced authentication settings (optional):

  • redirectUri (for Step 4. of the Authorization Code Flow, see picture above)
    In CB-9.4 not longer required, because this URI will be build automatically.
  • codeChallengeMethod:
    • "S256"
    • "plain"
  • tokenEndpointAuthSigningAlg (only if tokenEndpointAuthMethod is "client_secret_jwt" or "private_key_jwt"): Currently only HMAC using a SHA-2 hash is supported:
    • "HS256"
    • "HS384"
    • "HS512"
  • idTokenSignedResponseAlg is the required signature of ID tokens returned from the token end-point.
    Leave this undefined, to accept any valid and supported signature.
  • authOptions are additional parameters to pass in the authentication request to the authorization end-point, e.g.
       authOptions : {
           "acr_values" : "special1 special2"
       }
    
  • tokenOptions are additional parameters to pass in the token request to the token end-point, e.g.
       tokenOptions : {
           "myOption" : "myValue"
       }
    


In CB-9.4 and newer there are also direct openID settings:
  • forceOAuth if this is true, then access to the REST API requires an OAuth2 access token.
    Default is false, which means Basic and Digest authentication are also allowed, but will only work for (technical) user accounts, where a password is set.
  • 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. Default is false.
  • cacheSuccessTTL the time successful OAuth2 access token introspections should be cached, e.g. 1:30h, 20min or 90s. Default is 10min
  • cacheFailureTTL the time unsuccessful OAuth2 access token introspections should be cached. Default is 15min


Multiple OAuth2/OpenId Connect providers

In CB-9.4 and newer, you can configure multiple OAuth/OpenID Connect providers, each provider having it's own

  • server configuration
and different client configurations for
  • OpenID Connect authentication and
  • OAuth2 access token introspection.

E.g.:

    "openId" : {
        "issuers" : [{
            "server" : {
                "issuer" : "http://my.oidc.provider"
            },
            "authentication" : {
                "clientId" : "cbAuth",
                "clientName" : "cbAuth@test-pc",
                "clientSecret" : "AIJ0OWXu ...",
                "tokenEndpointAuthMethod" : "client_secret_basic",
                "scope" : "openid, profile, email, phone, address, offline_access",
                "userName": "preferred_username"
            },
            "introspection" : {
                "clientId" : "cbIntro",
                "clientName" : "cbIntro@test-pc",
                "clientSecret" : "wEDO8i3Q ...",
                "tokenEndpointAuthMethod" : "client_secret_basic"
            }
        }, {
            "server" : {
                "issuer"                   : "https://accounts.google.com",
                "authorizationEndpointUri" : "https://accounts.google.com/o/oauth2/v2/auth",
                "tokenEndpointUri"         : "https://oauth2.googleapis.com/token",
                "jwksUri"                  : "https://www.googleapis.com/oauth2/v3/certs",
                "userInfoUri"              : "https://openidconnect.googleapis.com/v1/userinfo",
                "introspectionEndpointUri" : "https://www.googleapis.com/oauth2/v3/tokeninfo",
                "revocationEndpointUri"    : "https://oauth2.googleapis.com/revoke",
                "endSessionEndpoint"       : "https://accounts.google.com/logout"
            },
            "client" : {
                "clientId" : "26576725-kdf73jgfgu7653flfhe7t53.apps.googleusercontent.com",
                "clientName" : "Your CodeBeamer Instance",
                "clientSecret" : "lkfjdu736ei7hJF#3",
                "tokenEndpointAuthMethod" : "client_secret_basic",
                "scope" : "openid, profile, email",
                "userName": "preferred_username"
            }
        }],
        "issuerDiscovery" : "webFinger",
        ...
    }


But the default issuer discovery
  • will only authenticate against the first of the configured issuers, and
  • can only handle OAuth2 access tokens from additional issuers, if these access tokens are JSON Web Tokens (JWT), whose iss claim refers to a registered issuer.

If that is not sufficient, you have to specify the alternative method of issuer discovery:
  • issuerDiscovery can bei either
    • the name of a custom bean, deployed via my-applicationContext.xml, e.g. an instance of
    • the fully qualified name of a Java class (in the codeBeamer server classpath)
      • The class must have a no-argument constructor or a constructor with a single argument of type com.intland.codebeamer.security.openIdConnect.service.IssuerConfigurationService
      • The class can have @Autowired properties

The bean or class must either

  • implement IssuerService
  • implement com.intland.codebeamer.security.openIdConnect.service.IssuerDiscoveryService
  • extend com.intland.codebeamer.security.openIdConnect.service.impl.DefaultIssuerDiscoveryService

Resumee

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.