OpenID HCMS Client configuration
How to configure HCMS Client with OpenID integration
openid
is a property of the JSON object type (not a list!) where you should enter all your OpenID providers; each provider should have their own property, but their nested properties should be the same. The values can be obtained from the provider. Please also refer to the official third-party documentation on the meaning of certain fields and requirements to their values. We only add some notes for the most popular OpenID providers.
Overview of JSON properties
Property | Nested property | Nested property | Required | Value type | Default | Description |
---|---|---|---|---|---|---|
openid | optional | JSON object | - | See nested properties. | ||
openid | [providerId: string] | required | JSON object | - | Create an id for your provider. The property itself is a literal string. | |
openid | [providerId: string] | name | optional | string | providerId | Name of the provider. |
openid | [providerId: string] | logo | optional | string | Value of name | Link to the provider logo. Must be a valid HTTPS link, as it is directly rendered into <img src=""/> element on the login page. |
openid | [providerId: string] | issuer_url | required | string | - | Base URL of the provider. |
openid | [providerId: string] | client_id | required | string | - | Client ID. |
openid | [providerId: string] | client_secret | required | string | - | Client secret that you need to generate in the provider configuration. |
openid | [providerId: string] | scope | required | string | openid email profile | Scope, e.g., a shared protocol and role mappings. The default value should suffice for most providers. |
openid | [providerId: string] | logout_id_token_hint | optional | boolean | - | By default, HCMS Client does not remember this token and thus does not add it. |
openid | [providerId: string] | logout_redirect | optional | boolean | true | Specifies if the user should be redirected to a logout landing page which needs to be set in the openid_landing /after_logout property as explained below. |
openid | [providerId: string] | accountPairBy | optional | string | - | Automatically pair existing account assets by specified value. Only email is actually supported for now. When not set, existing accounts are used only when they have the proper openid.sub which is the most secure option. When set to email , and the user tries to log in for the first time, and their email matches with the provider database, an openid.sub will be set for them. See also this article. |
openid | [providerId: string] | autoCreate | optional | boolean | false | The property specifies if a new account representation should be created for the user if no account asset in the censhare system or entity in HCMS has been found for them, neither by openid.sub nor by the value set in the accountPairBy . I.e., it adds the value for openid.sub as a property to the account asset which in it's turn stored as a feature on the user asset. On default behaviour, the user login just fails. |
hideStandardLogin | optional | boolean | - | Specifies if the standard login page should be shown or hidden before the user is redirected to an OpenID provider. The login page is always skipped if only one OpenID provider is configured. This flag can be dynamically suppressed by the user by going to the special URL /#/login?showStandardLogin=1 which forces the login form to be shown. | ||
openid_landing | optional | JSON object | - | Landing pages where the user ends up after the OpenID login or logout. Intended only to be used for local development and debugging, please avoid in production. | ||
openid_landing | after_logout | optional | string | - | Landing page after the logout. | |
openid_landing | after_login | optional | string | - | Landing page after the successful login. | |
openid_landing | base | optional | string | - | The URL base. When used, the other paths can be relative. |
Example configuration
In the following example, four providers are available: keycloak1
, keycloak2
, okta-dev-77547913
and aws-dev
{
"portal": {
"portalDomain": "some-domain.sample",
"openid": {
"keycloak1": {
"accountPairBy": "email",
"autoCreate": true,
"name": "One of the Keycloak servers",
"logo": "https://keycloak1.org.sample/auth/resources/ji34m/welcome/keycloak/logo.png",
"client_id": "hcms-client-sso-dev",
"client_secret": "vnievipejfpiwejfpqiwjdcds",
"issuer_url": "https://keycloak1.org.sample/auth/realms/marketing"
},
"keycloak2": {
"accountPairBy": "email",
"autoCreate": true,
"name": "Another Keycloak server",
"logo": "https://keycloak2.org.sample/auth/resources/ji34m/welcome/keycloak/logo.png",
"client_id": "hcms-client-sso-dev",
"client_secret": "op[por34fevopwjif",
"issuer_url": "https://keycloak2.org.sample/auth/realms/marketing"
},
"okta-dev-77547913": {
"accountPairBy": "email",
"autoCreate": true,
"name": "Okta dev account",
"logo": "https://www.okta.com/sites/default/files/Dev_Logo-01_Large.png",
"scope": "openid email profile offline_access",
"logout_id_token_hint": true,
"client_id": "0oa6lbe9aeMQiGHka5d7",
"client_secret": "432p5o[k3gtJ1hW_-324231[]324134",
"issuer_url": "https://dev-77547913.okta.com"
},
"aws-dev": {
"accountPairBy": "email",
"autoCreate": true,
"name": "Our AWS Cognito",
"logo": "https://d0.awsstatic.com/logos/powered-by-aws.png",
"scope": "openid",
"client_id": "8lkpr34mf2o4523op5k2435",
"client_secret": "983rfoij45opi2j4f3oirj423poij55",
"issuer_url": "https://cognito-idp.eu-central-1.amazonaws.com/eu-central-1_WIottwcI"
}
}
}