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

codebeamer Application Lifecycle Management (ALM)
Login
 Projects
 Wiki
Last ModifiedRecently Visited Items
Search In Project
Search inClear
anonymous
[WIKIPAGE-5376270] OpenID Connect (OAuth2)
Tags:  not added yet

Table of Contents

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

Enable OpenID by environment variable (default = true) 

CB_openId_enabled=true

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


user info


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 configurable 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: ssoId, username, email


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


OpenID


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 PublicWeb 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 Scopesrequired 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 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 effect 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",
        "validatorCacheTTL" : "60min",
        "symmetricKeyValidatorCacheTTL" : "24hours",
        "audienceWhitelist" : "a,b"
    }



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/authenticationconfiguration:
    • 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 requestto the authorization end-point, e.g.
       authOptions : {
       "acr_values" : "special1 special2"
   }
  • tokenOptions are additional parameters to pass in the token requestto 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_jwtare 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 userinfoclaims, 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 ConnectProvider 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 userclaims 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 username := "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 (v1) requires an OAuth2access 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

Since 21.04-SP1 white list for audience can be set

  • audienceWhitelist comma separated list name of audiences

Since 21.04-SP2 expiration time for certificates can be set

  • validatorCacheTTL expiration time of JWT Keys, e.g. 1:30h, 20min or 90s. Default is 60min
  • symmetricKeyValidatorCacheTTL expiration time of symmetrical validator cache for clients based on client secrets, e.g. 1:30h, 20min or 90s. Default is 24h


Since CB-10.0 redirectUri must be set 

"openId" : {
  "authentication" : {
     ...
     "redirectUri" : https://<domain>/(cb)/login/oauth/authenticate.spr
     ...
  }
}


OpenID Configuration Using PingFederate

You can create a Codebeamer PingFederate OAuth client to verify the authenticity of the access tokens received by the Codebeamer server.


For a given Codebeamer server, you must first enable OpenID on the PingFederate server.


On the PingFed server under OAuth Settings ► Authorization Server Settings, ensure that the following check boxes are selected:

  • AUTHORIZATION CODE
  • BYPASS AUTHORIZATION FOR PREVIOUSLY APPROVED PERSISTENT GRANTS (under Authorization Consent)

To create this OAuth client, complete the following steps:

  1. On the OAuth Settings page, locate the Clients section and click Create New.
  2. Enter a Client ID. Make a note of this value as it will be needed when configuring the Windchill securityContext.properties file.
  3. Select Client Secret and enter a client secret value. Make a note of this value as it will be needed when configuring the Windchill securityContext.properties file.
  4. In the Name field, enter a descriptive value. This value is displayed in the PingFederate Clients list.
  5. Enter a Description.
  6. In the Allow Grant Types section, select Refresh Token, Authorization Code, Resource Owner Password Credentials, Assertion Grants, and Access Token Validation (Client is a Resource Server).
  7. In the Persistent Grants Expiration section, select Use Global Setting.
  8. In the Refresh Token Rolling Policy section, select Don’t roll.

For example, if the Codebeamer Client id is CB_Client, the openId will appear as: 

"openId" : {
        "allowSignUp" : true,
        "audienceWhitelist" : "",
        "cacheFailureTTL" : "15min",
        "cacheSuccessTTL" : "10min",
        "enabled" : true,
        "forceOAuth" : false,
        "reuseDefaultAccount" : false,
        "server" : {
            "authorizationEndpointUri" : "https://pwdcsv-wcqa18d.ptcnet.ptc.com:9031/as/authorization.oauth2",
            "introspectionEndpointUri" : "https://pwdcsv-wcqa18d.ptcnet.ptc.com:9031/as/introspect.oauth2",
            "issuer" : "https://pwdcsv-wcqa18d.ptcnet.ptc.com:9031",
            "jwksUri" : "https://pwdcsv-wcqa18d.ptcnet.ptc.com:9031/pf/JWKS",
            "registrationEndpointUri" : "",
            "requestTokenUri" : "https://pwdcsv-wcqa18d.ptcnet.ptc.com:9031/idp/SSO.saml2",
            "revocationEndpointUri" : "",
            "tokenEndpointUri" : "https://pwdcsv-wcqa18d.ptcnet.ptc.com:9031/as/token.oauth2",
            "userInfoUri" : "https://pwdcsv-wcqa18d.ptcnet.ptc.com:9031/idp/userinfo.openid"
        },
        "client" : {
            "authType" : "ACCESSTOKEN",
            "clientId" : "CB_Client",
            "clientName" : "CB_Client",
            "clientSecret" : "cbTest",
            "domain" : "",
            "introspectUserResolveAttribute" : "ssoid",
            "redirectUri" : "https://ppuwsv-alm15t.ptcnet.ptc.com:9152/login/oauth/authenticate.spr",
            "refreshTokenScope" : "WINDCHILL_READ",
            "scope" : "openid, profile, email, WINDCHILL_READ",
            "tokenEndpointAuthMethod" : "client_secret_basic",
            "userName" : "sub",
            "userResolveResource" : "INTROSPECTION"
        }


DPT-Specific Keys

The following keys are DPT-specific and are required when using OAuth configuration for DPT:

  • requestTokenUri
  • authType
  • introspectUserResolveAttribute
  • refreshTokenScope
  • userResolveResource

Also, the oAuthConfigId specified in the OSLC configuration, must match the issuer key value specified here under openId OAuth configuration.


For instance: 

"oslc" : {
"enabled" : true,
"oAuthConfigId" : "https://pwdcsv-wcqa18d.ptcnet.ptc.com:9031",
.
.
.
}


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:

  • issuerDiscoverycan 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

Machine-to-Machine (M2M) Authentication


Since the release of 22.04-SP1 (FELICITY), codebeamer supports the Machine-to-Machine type of authentication.

M2M tokens cannot always be used for the retrieval of user information from the OpenID servers.

Prerequisites

  1. There must be a codebeamer user available for the authorization.
  2. To activate M2M authentication in codebeamer, the OpenID configuration needs to be amended by adding one of the following code snippets:


  • username configuration
    "openId" : {
   "client" : "...",
   "server" : "...",
   "m2m" : {
      "username" : "myApiUser"
   }
}
Applying the "username" configuration, the API call uses the relevant user for the authorization. The user must have an API access.


  • usernameAttribute configuration
    "openId" : {
   "client" : "...",
   "server" : "...",
   "m2m" : {
     "usernameAttribute" : "aud"
   }
}
With the usage of the "usernameAttribute" configuration, codebeamer collects the username from the token according to the defined attribute name. In case of array type claims, codebeamer uses the first element.

Flow of the API calls

Without M2M configuration

  1. Start an API call with the Authorization: Bearer <Token>header
  2. Issuer configuration is found by the token
  3. Token is validated
  4. UserInfo endpoint is called, and the response is processed
  5. User is found based on the user information, and is used for authorization


M2M configuration with username

  1. Start an API call with the Authorization: Bearer header
  2. Issuer configuration is found by the token
  3. Token is validated
  4. User is found based on the username, from the M2M configuration
  5. User is used for authorization


M2M configuration with usernameAttribute

  1. Start an API call with the Authorization: Bearer header
  2. Issuer configuration is found by the token
  3. Token is validated
  4. Username is retrieved from the token based on the usernameAttribute
  5. User is found based on the username
  6. User is used for authorization

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 password.
Fast Links

codebeamer Overview
What is new?
How-to videos

codebeamer Knowledge Base
User's Guide (user manual)
Administrator's Guide
Installation Guide
Developer's Guide
Localization Guide

Services by Intland Software
Product Support
Consulting
Training

Integrations