OpenID HCMS Client configuration | Censhare Documentation

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"
      }
  }
}