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

codeBeamer Application Lifecycle Management (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.

The option is available since codeBeamer 10.0

Automatic OpenID login is configurable.

  • true: Logging in automatically with OpenID
  • false: codeBeamer login page appears. You can choose Login with your codeBeamer user or Login with SSO.

Environment variable

CB_openId_automatic="true"

Application JSON

"openId" : { "client" : "automatic": true}

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 infovalues profile claims:

  • preferred_username
  • nickname
  • name

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


The option is available since codeBeamer 10.0

User account matching is configuratble in the following way.


Environment variable

CB_openId_client_resolveUserBy="email, username"

Application JSON

"openId" : {
  "client" : {
    "resolveUserBy" : "email, username"
  }
}

Available options: email, ssoId, username

Default values: username, ssoId


User account matching is done via the first non-empty value of the configured user infovalues profile claims.

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, if supported by provider)
    • Depending on the OpenID Connect provider, there can be additional scopes, that you can also configure. Please check the documentation of your provider.
  • 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 or a PrivateKey


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.


In CB-9.5 and newer, you can also configure the mapping of OpenID Connect provider specific user information to the codeBeamer user account attributes, e.g.
    "openId" : {
        "server" : {
            ...
        },
        "client" : {
            ...
        },
        "user" : {
	    "name"            : "preferred_username",
	    "firstName"       : "given_name",
   	    "lastName"        : "family_name",
	    "email"           : "email",
	    "phone"           : "phone_number",
	    "mobile"          : "mobile_number",
	    "language"        : "locale",
	    "timeZonePattern" : "zoneinfo"
        },
        ...
}



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
  • 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:
    • "none" (no client authentication necessary)
    • "client_secret_basic" (the default, if not specified)
    • "client_secret_post"
    • "client_secret_jwt"
    • "private_key_jwt" (only supported in CB-9.5 and newer)
  • clientSecret is the secret assigned to this codeBeamer instance during client registration, and is only required if tokenEndpointAuthMethod is "client_secret_{basic|post|jwt}".
  • privateKey is the client's (private) JSON Web Key, and only required if tokenEndpointAuthMethod is "private_key_jwt", e.g
       "privateKey" : {
    	"kid" : "ABC123DEFG",
    	"kty" : "EC",
    	"crv" : "P-256",
    	  "x" : "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
    	  "y" : "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
    	  "d" : "870MB6gfuTJ4HtUnUvYMyJpr5eUZNP4Bk43bVdj3eAE",
    	"use" : "sig"
       }
    
    The key must have a "kid". E.g. to Sign In with Apple, this must be the 10-character key identifier obtained from your developer account.
    The key "use" is optional, but must be "sig", if specified.

    If you have to create a public/private key pair yourself, you can use this JSON Web Key Generator.
    If the key pair is created by the Open ID Provider upon client registration, and the private key is only provided as a .pem or .p8 encoded file, e.g. when you create and download a private key to Sign In with Apple:
    -----BEGIN EC PRIVATE KEY-----
    MHcCAQEEINCC5ntCkm4N6+/7n2iDiU25nxXBNH86CJqRpxAHcbZPoAoGCCqGSM49
    AwEHoUQDQgAEskm1lUS3bdp8lXXZtFXeyxJHeUDLx6rK3Sgjre/gDZnuPwkUm0FJ
    5b0XS6qbhLFbJytOGH5g8U5AiwFoSQqRgw==
    -----END EC PRIVATE KEY-----
    
    You can convert the .pem or .p8 encoded file into a JSON Web Key, e.g. via pem-to-jwk.
    But you can also use the PEM encoded key directly, e.g.
       "privateKey" : {
    	"kid" : "ABC123DEFG",
    	"pem" : [ "-----BEGIN EC PRIVATE KEY-----",
    		  "MHcCAQEEINCC5ntCkm4N6+/7n2iDiU25nxXBNH86CJqRpxAHcbZPoAoGCCqGSM49",
    		  "AwEHoUQDQgAEskm1lUS3bdp8lXXZtFXeyxJHeUDLx6rK3Sgjre/gDZnuPwkUm0FJ",
    		  "5b0XS6qbhLFbJytOGH5g8U5AiwFoSQqRgw==",
    		  "-----END EC PRIVATE KEY-----" ]
       }
    
    Where "pem" are the lines from -----BEGIN PRIVATE KEY----- to -----END PRIVATE KEY----- (inclusive) as an array of strings.

  • scope is a comma-separated list of the requested Scopes, and only required in the client/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)
    • Depending on the OpenID Connect provider, there can be additional scopes, that you can also configure. Please check the documentation of your provider.

  • userName defines, which userinfo claim (in descending order) to use as the user name of an authenticated user.
    Only required, if there is no user info configuration (see below), and only in the client/authentication configuration, unless there is only a introspection configuration.


Advanced client/authentication settings (optional):

  • redirectUri (for Step 4. of the Authorization Code Flow, see picture above)
    In CB-9.4 and newer 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"
       }
    
  • tokenAuthJWTClaims : optional claims for the payload of the private_key_jwt, e.g.
       "tokenAuthJWTClaims" : {
          "iss" : "<Apple Team ID>",
          "aud" : "https://appleid.apple.com"
       }
    
    By default, the standard claims for private_key_jwt are used:
    • "iss" is the id of the client to authenticate, but you can override that. E.g. to Sign In with Apple: "iss" must be the 10-character Team ID, obtained from your Apple developer account.
    • "sub" must be the id of the client to authenticate and cannot be overridden.
    • "aud" should be the URL of the Authorization Server's Token Endpoint, but you can override that. E.g. to Sign In with Apple: "aud" must be "https://appleid.apple.com"
    • "exp" defaults to 60s, but you can override that. E.g. "exp" : "20min" or "exp" : "2:30h". But "exp" cannot be less than "10s" or more than 4380h (6 months)


The set of claims about the End-User, that will be returned from the User Info Endpoint of an OpenID Connect provider, is defined via the client/authentication configuration (see above):
  • the mandatory scope, e.g.
    "scope" : "openid, profile, email, phone, address"
    
  • and optionally (only in CB-9.5 and newer): Additional userinfo claims, explicitly requested via the authOptions (see above), e.g.
    "authOptions" : {
        "claims" : {
    	"userinfo" : {
    	     "department_number": null,
    	     "http://example.info/claims/groups": null
    	}
        }
    }
    
Using the claims parameter is the only way to request Claims outside the standard set. It is also the only way to request specific combinations of the standard Claims, that cannot be specified using scope values.

Please consult the /.well-known/openid-configuration of your provider, which it actually supports.


The optional user section (CB-9.5 and newer) is only required, if the OpenID Connect Provider does not return the standard OpenID Connect userinfo claims (e.g. Microsoft ADFS) or you need to map additional claims.

In CB-9.4 and older, or if you do not specify a provider specific user claims to codeBeamer account attributes mapping, the following default/standard mapping will be applied:
"user" : {
    "name"            : "sub",
    "title"           :  null,
    "firstName"       : "given_name",
    "lastName"        : "family_name",
    "company"         :  null,
    "industry"        :  null,
    "address"         : "address.street_address",
    "zip"             : "address.postal_code",
    "city"            : "address.locality",
    "state"           : "address.region",
    "country"         : "address.country",
    "language"        : "locale",
    "timeZonePattern" : "zoneinfo",
    "email"           : "email",
    "phone"           : "phone_number",
    "mobile"          :  null,
    "skills"          : "profile",
    "sourceOfInterest":  null,
    "divisionSize"    :  null,
    "teamSize"        :  null
}
Even if you do not specify a full custom user mapping, you can still override the default user name := "sub" mapping via the userName setting in the client/authentication configuration, e.g. "userName" : "preferred_username".

The left (target) side of the user info mapping is the codeBeamer account (UserDto) attribute name and these names are fixed.
But you only have to specify those attributes, that you actually want to map. At least name and email are required, all others are optional.

The right (value) side of the user info mapping is a comma-separated list of the claims, to map to this codeBeamer user attribute. If you specify multiple claims, the attribute value will be the value of the first claim, that is actually present, e.g.
"user" : {
    "name" : "preferred_username, name",
    ...
}
will only assign the value of the name claim to the codeBeamer user name, if there is no preferred_username claim. Precedence is from left to right.

To map aggregated claims, e.g. address, use the dot operator, e.g.
"user" : {
    ...
    "address"         : "address.street_address",
    "zip"             : "address.postal_code",
    "city"            : "address.locality",
    "state"           : "address.region",
    "country"         : "address.country",
    ...
}

A value of null for a user attribute, explicitly marks this attribute as do not map. Simply omitting the attribute has the same effect.

The attribute names divisionSize and "teamSize" are a little bit misleading, because they are not numbers but strings. So you can actually assign department name/ids or organizational unit names/ids to these fields, e.g.
"user" : {
    ...
    "divisionSize"    : "department_number",
    "teamSize"        : "http://example.info/claims/groups",
    ...
}

Please note, that codeBeamer user accounts do not have attributes for nickname, middle_name, gender and birthdate.
The mapping of the picture is currently also not supported.


Please note, that the Microsoft Active Directory Federation Services (ADFS) do not return the standard OpenID Connect userinfo claims by default!

Instead you get something like:
{
   "iss": "https://my-adfs.cloudapp.azure.com/adfs",
   "aud": "https://my-codebeamer.host",
   "sub": "248289761001",
   "upn": "Jane.Doe@example.com",
   "unique_name": "Jane.Doe",
   "sid": "S-1-5-21-72543-3645445-326572-242",
   ...
}
The actual response depends on the ADFS configuration, and will typically include more claims than shown above.

We suggest, to reconfigure ADFS to return standard OpenID Connect claims, but if that is not possible, you need a custom ADFS claims to codeBeamer user mapping (only CB-9.5 and newer).
E.g.
    "openId" : {
        "server" : {
            "issuer" : "https://my-adfs.cloudapp.azure.com/adfs"
        },
        "client" : {
            ...
        },
        "user" : {
	    "name"  : "unique_name",
	    "email" : "upn",
            ...
        },
        ...
    }


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.