SAML configuration

In order to utilize SSO with SAML, it has to be configured first. There is 2 Web UI to do that: Applicaiton configuration UI and SAML configuration UI. On both UI there is option to enable SAML SSO and make it automatic to login. Other configurable options are detailed below.

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

CB 10.1: Identity provider entityId is removed. Automatically removed from Application config on next config save/update.

Application configuration UI

As with other configuration, SAML can be configured in the application configuration with the following JSON under the saml key:

"saml" : {
  "automatic" : false,
  "enabled" : true,
  "allowSignUp" : true,
  "idp" : { ... },
  "sp" : { ... },
  "user" : { ... }
}

Saml configuration UI

A dedicated configuration UI can be find on the Sysadmin page. It can be used to configure and validate SAML configuration.

Saml metadata UI

For easy use, the state and the metadata for the configured SAML components can be checked on the metadata UI on the sysadmin page.

It shows if the components are not yet reloaded.

It shows if the components are configured correctly.

It shows if the components are configured incorrectly.

General configuration

This section dedicated for common configurations:

• enabled - Enables/disables SAML SSO, even if it is configured. This allows the system administrator to easily control the login without modifying other configuration values.
• automatic - Enables automatic SAML SSO login.
• allowSignUp - Enables/disables registering new user, if SAML SSO not connected with registered user.
• domain - Comma separated domain list that allows filtering trusted domain based on email in SAML Auth response.

Service Provider configuration

The service provider is codeBeamer in the authentication process. The following properties are mandatory to configure:

• entityId - Unique identifier for the Service Provider in the authentication process for the Identity Provider.
• signMetadata - Flag to digitally sign the Service Provider Metadata xml, if fetched.
• signRequests - Flag to digitally sign the Service Provider authentication requests.
• wantAssertionsSigned - Flag to only accept digitally signed authentication responses from the Identity Provider.
• activeKey - Properties (private key, certificate and passphrase) for currently used key to digital signature and encryption. Note that the passphrase will be encrypted, and only visible as decrypted value on SAML configuration UI.
• standbyKey - Properties for the next key, will be included in the Service Provider metadata.

Example:

"sp" : {
    "entityId" : "cb-saml-sp",
    "signMetadata" : true,
    "signRequests" : true,
    "wantAssertionsSigned" : true,
    "activeKey" : {
      "certificate" : "...",
      "passphrase" : "...",
      "privateKey" : "..."
    },
    "standbyKey" : {
      "certificate" : "...",
      "passphrase" : "...",
      "privateKey" : "..."
    }
}

Identity Provider configuration

The identity provider is the external security domain in the authentication process. The following properties are mandatory to configure:

• NameID - Unique identifier for the Identity Provider in the authentication process for the Service Provider.
• url - Url to fetch Identity Provider metadata xml. This is mutually exclusive with xml.
• xml - XML metadata for the Identity Provider. This is mutually exclusive with url.

"idp" : {
    "entityId" : "C025kbbvq",
    "url" : "...",
    "xml" : "..."
}

User mapping configuration

User mapping is necessary to map users authenticated by the Identity Provider to codeBeamer users, by mapping the Assertion attributes provided in authentication response.

All user properties can be mapped, but the following are mandatory:

• ssoId
• name
• email

And the following will be ignored, regardless of mapping:

• password
• status
• language
• timeZonePattern

The full list of possible mapping keys are the following:

• name
• firstName
• lastName
• hostName
• title
• address
• zip
• city
• state
• sourceOfInterest
• scc
• teamSize
• divisionSize
• company
• country - 2 letter code based on ISO-3166
• email
• emailClient
• phone
• mobile
• dateFormatPattern - based on ISO-8601, like: 'dd MMM yyyy'
• browser
• skills
• downloadLimit

Example:

"user" : {
    "email" : "clientEmail",
    "firstName" : "userFirstName",
    "lastName" : "userLastName",
    "name" : "userName",
    "ssoId" : "id"
}

User Account Matching Configuration

User account matching is configurable in the following way.

Environment variable

CB_saml_resolveUserBy="ssoId, username, email"

Application JSON

"saml" : {
  "resolveUserBy" : "ssoId, username, email"
}

Available options: ssoId, username, email

Default values and order: ssoId, username, email

Key generation

For both active and standby keys the following command can be used:

1. Create an encrypted private key

openssl genrsa -des3 -passout pass:<passphrase> -out <privateKey> 4096

2. Generate a self-signed certificate with existing private key for a year

openssl req -x509 -sha256 -nodes -days 365 -key <privateKey> -out <certificate>

Endpoints

The following endpoints are added to handle SAML authentication flow:

• http-get://<cb-root-context>/saml/sp/metadata - Service Provider metadata xml is provided through this url
• http-get://<cb-root-context>/saml/sp/SSO/login/request/ - Starting point for SAML SSO login, this will redirect to the configured Identity Provider
• http-post://<cb-root-context>/saml/sp/SSO/alias/SAML2.spr - Callback url after successful login on Identity Provider, called by the Identity Provider

Resumee

With SAML authentication in affect:

• Interactive login to codeBeamer is only possible, if the configured SAML Identity Provider is reachable from the Web Browser of the user.
• Fallback to internal codeBeamer login is only possible, if the user configures his/her password beforehand.