How Do Setup and Configure SSO Using OpenID Connect?

Compatibility

SSO using OpenID connect was introduced in version 12.0.0.17629, and is only available in this and later version of the community platform. While this functionality may work with other OpenID connect certified platforms, at this time it is only certified to work with the following:

Okta Identity Platform
Azure Active Directory*

*Azure Active Directory refers to the primary AD tenant, not Azure AD B2C. Azure AD B2C should work, however you must be able to present an email claim which may require additional configuration inside of Azure. Azure B2C is not certified at this time.

The following article is written accounting for expanded support in the future.

The OpenID Connect provider only supports the OAuth 2.0 confidential authorization code flow.

Add and Configure the Client Application

Depending on what OpenID Connect provider you use, you will usually have to add and configure some sort of application or integration within the provider. You should consult your provider's OpenID Connect documentation for further information. Below are links to configuration guides to platforms currently certified to work with your community. Only the providers listed here are fully supported, though others may work.

Okta

How Do I Configure Okta for OpenID Connect and SCIM Provisioning

Callback URLs

When configuring an application on Azure AD, or if you are using the generic OpenID connect application in Okta, you will need to specify the appropriate callback Urls. Note this applies to 12.1 and higher only.

Type	URL	Description
Redirect Uri	https://{communityURL}/sso/login	This is the URL that is called back to with an authorization code after a user is authenticated.
Logout Uri	https://{communityURL}/sso/logout	This is the url a user is redirected to after the session is terminated at the identity provider. Certain services have this as a specific field in the configuration, while others, like Azure AD, require it be added as an additional redirect uri.

Configure The OpenID Connect Plugin

The OpenID Connect Plugin can be found by going to Administration-> Authentication-> Authentication Methods, then select OpenID Connect Single Sign-On. It is recommended that you configure the required properties first and save before selecting the 'Enable' option. Otherwise your community's authentication process will be immediately replaced and you might have to utilize the emergency administration login to further configure the plugin.

Authorization Options

Option	Required	Default	Description
Authorization Server	Yes	None	This is the base URL of the OpenID authority. This URL is used to obtain the discovery information about the OpenID server, including the appropriate endpoints, JWT token keys and issuer.
Client Id	Yes	None	This is the client Id issued by the OpenID application configuration.
Client Secret	Yes	None	This is the client secret, or secret key, issued by the OpenID application configuration.
Additional Scopes	No	openid, profile, email	If your application has additional scope requirements, then they can be added here as a single line, each new claim separated by a space. (e.g. scope1 scope 2). By default the standard openid, email and profile scopes are requested. Requesting additional scopes does not guarantee the provider has access to new data.
Additional Discovery Information	No	None	Generally this is not needed, but if your authorization server requires additional querystring information you can add it here without the '?'. If that additional information is the application Client Id, you can utilize the previously set value by using the token {ClientId}. For example, client_id={ClientId}. If you are using static information, ensure the value is appropriately encoded for url use.

Community Options

Option	Required	Default	Description
Automatically Create User Accounts	No	Yes(Checked)	When checked, when a user successfully authenticates through OpenID Connect, if a matching community account is not found, it will be created automatically. If not checked, an error will be thrown. generally it is recommended to leave this checked unless you are managing the creation of user accounts in another way, such as through SCIM provisioning.

Mapping

Option	Required	Default	Description
Unique Id Claim	Yes	sub	This is the claim the acts as a a unique identifier in the identity platform for the user. By default it uses the 'sub' claim, or subject of the JWT token. This should be left as default unless you are certain that another claim is present and capable of acting as a unique identifier.
Email Address Claim	Yes	email	This claim is the user's email address. This will be used as the community account's private email address and is the primary lookup method for community accounts. It must be unique when presented to the community.
Username Claim	Yes	preferred_user_name	This is the claim that is used to assign a user's community username. It must be unique when presented the community, and when creating accounts if it is not unique, a number will be appended sequentially until it is. If the username is an email address, the '@' symbol and domain will be stripped and then same unique logic applied. This is to ensure that a user's email address is not unknowingly and unwillingly disclosed. Even if you intend to use an email address as a username, it will be modified.
Groups(Roles) claim	No	groups	This claim represents a user's groups, or as the community sees them roles. This is required for mapping role memberships in the community. If the authority does not support this or it is not presented as a simple list of names, this should be blank.
Mapping Configuration	No	None	Provides a utility for mapping profile and role data in the community using JSON. See Advanced Profile and Role Mapping for more information.

Advanced Profile and Role Mapping

You can use the Mapping Options to map claim information to custom profile fields and roles to a user when they are created and log in(if desired). It is defined using a specific JSON format. There are a few important considerations when deciding to use this feature.

If you are using SCIM user provisioning, it is recommended that you do not utilize this feature as SCIM is designed to handle this type of functionality itself. While you can use them together, there is the potential for conflict.
When defining profile fields, use a unique key. You can map to existing profile fields, however values entered by user's can potentially be overwritten on login.
Consolidate custom profile fields for OpenID Connect into their own profile field groups. This way when adding them in the community user interface, you can specify them as read-only. This is because profile fields are now managed by the OpenID Connect provider and should not be modified.

Understand the JSON

The configuration object contains three properties defined below.

{
  "claimMappings": [],
  "roleMappings":[],
  "onCreateOnly":false
}

Option	Description
claimMappings	An array of claim mappings used to define how claims can be mapped to custom profile fields or system fields.
roleMappings	An array of role mappings that defines how a user is mapped to custom and existing roles.
onCreateOnly	When true, claim AND role mappings are only applied when an account is created via OpenID Connect as opposed on creation AND login.

Claim Mappings

There are two ways to map a claim, a system field or a custom profile field. A system field is a constant field in your community, as opposed to a profile field which can be configured specifically for your community. You can map any field that is a simple value, such as a string, or an array of simple values such as a string list.

A field mapping consists of these fields:

{
    "mapsTo": {  },
    "claims": [],
    "format": ""
}

Option	Description
mapsTo	A mapping object that identifies whether you are mapping to a system field or profile field.
claims	An array of strings that defines the claim names to be used to set the value of the mapTo field. When a format is not specified and multiple claims are specified, they are concatenated together using a space, in the order defined.
format	Defines how multiple claims are joined, or adds additional data to existing claim. It is a single string where {claimName} defines the claim to be used.

Mapping a System Field

The current system fields are supported:

displayName: The display name of the community user.

When defining a system field the following JSON format is added to the mapsTo field:

"mapsTo": { "systemField": "displayName" }

The "systemField" property is all that is required and must conform to an id of pre-defined system field as defined above.

Custom Profile Fields

When not using a system field, you can specify a custom profile field. If the profile field exists, it's value will be managed by the OpenID Connect provider. If it does not exist, it will be created the first time a value is attempted to be written.

"mapsTo": {"profileField":{"key": "profilrField_key", "label": "FieldLabel","fieldType": "Plain Text","searchable": true } }

key: This value is used as a profile field key. It will map to an existing field, or create one if it does not exist.
label: The profile field label, used when creating a new field. It is how the user interface will display the field.
fieldType: The field type of the profile field. 'Palin Text; and 'Comma-separated List' are supported for array fields.
searchable: Defines whether the field will be searchable in the community platform.

Claims Property

You can specify one or more claims for a 'mapsTo' field. When more than one claim is specified, the values are concatenated by a space in the order defined into the 'mapsTo' field if a format is not specified. Claims can also be an array of strings when specified appropriately.

 "claims": [ {"name": "first_name" }, { "name": "emails, "type":"array","delimiter":"," }]

name: The name of the claim as presented in the token. It is always required.
type: If the claim value is an array of string values, specify 'array'
delimiter: Only for array types, this is the value used to concatenate the array values. By default it is a comma(',').

Simple single-valued claim.

{ "name": "first_name" }

Claim that has a string array as a value.

 { "name": "groups","type":"array", "delimiter":","}

Formatting

You can choose how the claim value(s) are presented using the format property. It is a static string with tokens formatted as {claimName} where claim name is the name as defined in the claims area. This is useful when multiple claims are specified. The value of the claim is substituted for the token as presented, with the exception of arrays which will be presented based on how the delineation is defined in the claim definition.

Single value format

"format":"My name is {first_name}"

Multiple claims

"format":"{last_name}, {first_name}"

Restricting When Fields Are Updated

You can specify an option 'onCreateOnly' property to an individual mapping object. When true, profile data will only be applied at account creation. By default this value is false, meaning they will be applied at creation and every login.

{
    "mapsTo": {  },
    "claims": [],
    "format": "",
    "onCreateOnly":true
}

Mapping Roles

You can define how a user is mapped to certain roles in the 'roleMappings', which is an array of mappings objects with the following properties

source: This is the name of the role being presented by the identity provider. When no destination is specified and the role does not exist, it will be created automatically.
destination: The name of a role in the community. When specified, a member presenting the source role will be added to the destination role in the community. If the destination does not exist, it will be created. Optional.
onCreateOnly: When true, roles will only be applied at account creation. By default this value is false, meaning they will be applied at creation and every login.

"roleMappings":[
        { "source":"CommunityMembershipAdmins","destination":"CustomRole" },
        { "source":"Group 2", "destination":null,"onCreateOnly":true }
  ]