OpenID Connect (OAuth2) Single Sign-On via

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:

[!Authorization Code Flow.png!]

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

revoke the OAuth2 access tokens associated with the codeBeamer user session, and
redirect the user to the end session endpoint of the Authorization Server.

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:

[!Sign In Google.png!] [!Sign in Google 2.png!]

<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:

[!Google Logout.png!]

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:

[!MITRE Login.png!]

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

[!MITRE Approval.png!]

<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:

[!MITRE Logout.png!]

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 Legacy REST API (v1)), 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:

[!OAuth2 Resource Access.png!]

Before you can configure a codeBeamer instance to authenticate users via OpenID Connect|https://openid.net/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 or a PrivateKey

OpenID Connect Configuration

The configuration for OpenID Connect is stored in System Admin → Application 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 for testing 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
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 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"
   }
```
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)

In CB-9.4 and newer there are also direct openID settings:

forceOAuth if this is true, then access to the Legacy REST API (v1) 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
  - WebfingerIssuerService
  - ThirdPartyIssuerService
- 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.

Fast Links