The Identity Provider Federation section

  • Applies to: All Board Cloud subscriptions  associated with a Subscription Hub

WHAT: Introduction to the Identity Provider Federation section

In the Identity Provider Federation section you can add and configure third-party services that will handle users' identity information and authentication for logging into Board. These services are called federated identity providers, or external identity providers (IDPs), and may comply to a number of standards: Board supports identity providers based on SAML2 and OIDC standards.

Federated identity providers are responsible for validating user identities and to exchange user authentication and authorization data. They can also provide pieces of information about each identity through JSON web tokens claims that are sent to application services via an encoded ID token (a sequence of characters).

The application receives an encoded ID token when a user successfully authenticates using a federated identity provider. The ID token is then decoded and user information is extracted from it, in the form of JSON web tokens claims.

Such claims appear as a key-value pair: the key must be a string, while the value must be a valid JSON data type (string, number, object, array, boolean or null).

For example, a JSON object can contain the following three claims ("name", "email", "phone"):

 

 {    
         "name": "John Smith"
         "email": "john@acme.com"
         "phone": "+1-541-754-3010"
 }

 

In the Identity Provider Federation section of the Subscription Hub you can manually map claims for every listed IDP in order to retrieve information from ID tokens and store it into Board user accounts.

For example, you can map the "Email" field of the user profile with the appropriate claim sent by an external IDP in order to retrieve the user's email at each login.

This information is updated each time a user logs in and overwrites any previously saved manual changes.
If mapped claims are missing (null response) or return an empty or whitespace value, the system will fall back on system-defined mapping rules for default User metadata.  If, again, mapped claims are missing (null response) or return an empty or whitespace value, no overwriting occurs and the information will remain as previously saved.

When you navigate to the Identity Provider Federation home page, you will see all configured IDPs in a list sorted by creation date. Other information showed right from the list is the protocol each IDP is based on and its last configuration update.

Identity Provider Federation home page

By clicking on an item in the list, you can check its configuration and modify it if necessary.

If a federated identity provider is associated with one or more users, it cannot be deleted. To delete it, first remove the association from the Authentication type dropdown in the User profile panel for each associated User account.
If a federated identity provider is used in an Enrollment process, it cannot be deleted. To delete it, deselect it from the Authentication type dropdown in the Default Authorizations page.

 

HOW: Add a new Identity Provider

To add a new federated identity provider you will need all necessary technical information and configuration values, depending on the protocol it is based on (SAML2 or OIDC): be sure to have them at hands.

 

Identity Provider based on SAML2 authentication protocol

To add a new SAM2-based IDP, proceed as follows:

  1. Click on “+IDENTITY PROVIDER”, fill in the Identity Provider Name and choose the SAML2 protocol type.
    The Identity Provider Name cannot be longer than 50 characters
  2. Fill in all required fields and tick the checkboxes if applicable.

    The "MODULE PATH" value must be unique.

    The "IDP LOAD METADATA" checkbox specifies the external IDP metadata location. When loading metadata for an IDP, SAML2 normally interprets the EntityId as a URL to the metadata. If the metadata is located somewhere else it can be specified by ticking this checkbox and by configuring the "METADATA TYPE" and "METADATA LOCATION" fields. 
    The required configuration settings must be sent in XML format, using a simple URL that points to the file location online or by uploading a properly formatted XML file. In both cases, the XML file must comply to SAML2 schema specifications.

    The "ALLOW IDP INITIATED LOGIN" checkbox, when checked, indicates that the external IDP can initiate the authentication process. If unchecked, the authentication process must be initiated by an Authentication Request from the Subscription Hub.

  3. (Optional) Upload a SAML signing certificate used to sign SAML requests, responses, and assertions from the Subscription Hub to the Federated Identity Provider

  4. (Optional) Click on "All settings" to reveal the full list of optional settings. Configure them as needed

  5. (Optional) Configure claim mapping. Click the "ADD NEW" button and, in the table below, configure the newly created row: select a user metadata attribute from the dropdown list in the "User metadata " column and enter the corresponding assertion claim used by the IDP in the "Assertion claim" column. Press Enter or click outside the table to save mapping information.
    Click on the recycle bin icon to delete the corresponding claim mapping information.

    The key entered in the Assertion Claim field must match exactly the key sent by the external IDP: claim mapping is case-sensitive.

    The following user metadata are present in the "User metadata" dropdown list by default:

    • Avatar Image

    • Culture

    • Email

    • Name

    • Phone Number

    All custom User Metadata attributes are also included in the "User metadata" dropdown list by default.

    In case of wrong or absent mapping, the system will look for a valid value in commonly used claims sent by the external IDP to fill in default user metadata. To know more about this process, please refer to this page.

  6. If the configuration has been properly done, the "ADD" button will activate. Click on it to save the newly configured Identity Provider.

Once you've successfully configured a new SAML2-based IDP, please ensure that the ID token it generates during user login contains a valid value for either the "sub" claim or the "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier" claim.
This information is mandatory, case-sensitive and must be properly formatted: if it doesn't match the accountname value stored in the User account within the Subscription Hub or it's missing, the user won't be able to access Board and no user account will be created at login, in case a direct approval enrollment process is active.

 

Identity Provider based on OIDC authentication protocol

To add a new OIDC-based IDP, proceed as follows:

  1. Click on “+IDENTITY PROVIDER”, fill in the Identity Provider Name and choose the OIDC protocol type.
    The Identity Provider Name cannot be longer than 50 characters
  2. Fill in all required fields and tick the checkboxes if applicable.

    The "SAVE TOKENS" checkbox, if enabled, allows access and refresh tokens to be stored in the authentication cookie after a successful authentication.
    The "REQUIRES HTTPS METADATA" checkbox, if enabled, defines whether HTTPS is required for the metadata address or the "AUTHORITY" field.

  3. (Optional) Click on "All settings" to reveal the full list of optional settings. Configure them as needed
  4. (Optional) Configure claim mapping. Click the "ADD NEW" button and, in the table below, configure the newly created row: select a user metadata attribute from the dropdown list in the "User metadata " column and enter the corresponding assertion claim used by the IDP in the "Assertion claim" column. Press Enter or click outside the table to save mapping information.
    Click on the recycle bin icon to delete the corresponding claim mapping information.

    The key entered in the Assertion Claim field must match exactly the key sent by the external IDP: claim mapping is case-sensitive.

    The following user metadata are present in the "User metadata" dropdown list by default:

    • Name

    • Email

    • Phone Number

    • Culture

    • Avatar Image

    All custom User Metadata attributes are also included in the "User metadata" dropdown list by default.

    In case of wrong or absent mapping, the system will look for a valid value in commonly used claims sent by the external IDP to fill in default user metadata. To know more about this process, please refer to this page.

  5. If the configuration has been properly done, the "ADD" button will activate. Click on it to save the newly configured Identity Provider.

Once you've successfully configured a new OIDC-based IDP, please ensure that the ID token it generates during user login contains a valid value for either the "sub" claim or the "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier" claim.
If the claims mentioned above are missing (null response) or return an empty or whitespace value, the Subscription Hub identity provider will look for valid data in the claim specified in the "nameClaimType" claim (default value: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name").
This information is mandatory, case-sensitive and must be properly formatted: if it doesn't match the accountname value stored in the User account within the Subscription Hub or it's missing, the user won't be able to access Board and no user account will be created at login, in case a direct approval enrollment process is active.