How Do I Setup and Configure SSO Using OpenID Connect?
While this functionality may work with other OpenID connect certified platforms, at this time it is only certified to work with the following:
*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.
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 site. Only the providers listed here are fully supported, though others may work.
How Do I Configure Okta for OpenID Connect and SCIM Provisioning
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://{yourSiteURL}/sso/login | This is the URL that is called back to with an authorization code after a user is authenticated. |
| Logout Uri | https://{yourSiteURL}/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. |
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 site's authentication process will be immediately replaced and you might have to utilize the emergency administration login to further configure the plugin.
| 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. |
| Option | Required | Default | Description |
| Automatically Create User Accounts | No | Yes(Checked) | When checked, when a user successfully authenticates through OpenID Connect, if a matching site 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. |
| 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 | This claim is the user's email address. This will be used as the site account's private email address and is the primary lookup method for site accounts. It must be unique when presented to the site. | |
| Username Claim | Yes | preferred_user_name | This is the claim that is used to assign a user's site username. It must be unique when presented the site, 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 site sees them roles. This is required for mapping role memberships in the site. 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 site using JSON. See Advanced Profile and Role Mapping for more information. |
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.
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. |
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 site, as opposed to a profile field which can be configured specifically for your site. 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. |
The current system fields are supported:
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.
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 } }
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":"," }]
Simple single-valued claim.
{ "name": "first_name" }
Claim that has a string array as a value.
{ "name": "groups","type":"array", "delimiter":","}
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}"
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
}
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
"roleMappings":[
{ "source":"siteMembershipAdmins","destination":"CustomRole" },
{ "source":"Group 2", "destination":null,"onCreateOnly":true }
]