Skip to main content
Skip table of contents

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
openidoptionalJSON object-See nested properties.
openid[providerId: string]requiredJSON object-Create an id for your provider. The property itself is a literal string.
openid[providerId: string]nameoptionalstringproviderIdName of the provider.
openid[providerId: string]logooptionalstringValue of nameLink 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_urlrequiredstring-Base URL of the provider.
openid[providerId: string]client_idrequiredstring-Client ID.
openid[providerId: string]client_secretrequiredstring-Client secret that you need to generate in the provider configuration.
openid[providerId: string]scoperequiredstringopenid email profileScope, e.g., a shared protocol and role mappings. The default value should suffice for most providers.
openid[providerId: string]logout_id_token_hintoptionalboolean-By default, HCMS Client does not remember this token and thus does not add it.
openid[providerId: string]logout_redirectoptionalbooleantrueSpecifies 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]accountPairByoptionalstring-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]autoCreateoptionalbooleanfalseThe 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.
hideStandardLoginoptionalboolean-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_landingoptionalJSON 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_landingafter_logoutoptionalstring-Landing page after the logout.
openid_landingafter_loginoptionalstring-Landing page after the successful login.
openid_landingbaseoptionalstring-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

JSON5
{
  "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"
      }
  }
}
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.