Docs Developer Site
OIDC IDprovider
arrow-down

Open ID Connect ID Provider

Contents

​

Authenticate your users using Open ID Connect.

This ID Provider application, acting as a OIDC Relying Party, will verify the identity of End-Users based on the authentication performed by your OIDC Authorization Server. It will redirect unauthenticated users to the Authentication Server and obtain basic information in order to create a user within Enonic XP. This ID Provider application follows the Authorization Code Flow and uses one of the client_secret_post, client_secret_basic or client_secret_jwt auth methods.

​
​

Configuration

​

Authorization Server

The configuration depends on the Authorization Server selected and is not covered by this documentation. It will typically require the creation and configuration of a Client/Application. The following information is needed:

​

Redirection/Callback URI

Once authenticated by the Authorization Server, the End-User will be redirected to Enonic XP. During the configuration of your Client/Application, you will have to register this callback URL. The callback URL depends on the VHost mapping and the name of the ID Provider. It has the following format: [VHost source]/_/idprovider/[ID Provider name]. Make sure the ID provider name exactly matches the name of the ID provider (or "userstore") in the User Admin app.

​

Example for a site: https://www.example.com/_/idprovider/myoidcprovider

Example for admin: https://www.example.com/admin/tool/_/idprovider/myoidcprovider

​

Information required for the ID Provider Config

You will need to gather the following information from the Authorization Server setup, for the ID Provider configuration

  1. The Client ID

  2. The Client secret

  3. The Issuer Identifier (URL)

  4. The Authorization endpoint URL

  5. The Token endpoint URL

You might have been given only the Issuer URL instead of the list of endpoint URLs. In that case the endpoint URLs are accessible under: [Issuer URL]/.well-known/openid-configuration The JSON result will contain the required information: issuer, authorization_endpoint and token_endpoint.

​

Example: Auth0

  • OpenID Provider Configuration URL: [Domain URL]/.well-known/openid-configuration

  • Issuer Identifier: [Domain URL]/

  • Authorization endpoint URL: [Domain URL]/authorize

  • Token endpoint URL: [Domain URL]/oauth/token

​

Example: Google

​
Example: Azure AD

​

Example: Difi/ID-porten/VER1

​
​

Enonic XP

Application Installation

  1. In the admin tool "Applications", click on "Install".

  2. Select the tab "Enonic Market", find "OIDC ID Provider", and click on the link "Install".

​

ID Provider creation

  1. In the admin tool "Users", click on "New" and select "Id Provider".

  2. Fill in the displayName field, which pre-fills the ID provider name just below. The ID provider name must match the name set in the Authorization server:

    ID provider name:

    idprovider name

    The ID provider name can be edited before saving, but not changed later.

  3. For the field "Application", select the "OIDC ID Provider" application.

​

Virtual Host Mapping configuration

Edit the configuration file com.enonic.xp.web.vhost.cfg, and set the new user store to your virtual host. (See Virtual Host Configuration for more information).

mapping.example.host = example.com
mapping.example.source = /
mapping.example.target = /portal/master/mysite
mapping.example.idProvider.myoidcprovider = default

Here as well, the ID provider name must match: see the last line.

​

ID Provider

As of v2.0.0, the config form in the users app (idprovider.xml) has been removed. The settings to configure the id provider must instead be entered in a .CFG file: com.enonic.app.oidcidprovider.cfg.

This config file should contain config fields for all OpenID providers in the format idprovider.[idprovidername].[configkey] = [value], where idprovidername should exactly match ID provider name from the Users app. For example, setting the forceEmailVerification rule config field with a value of true for an ID provider named myoidcprovider, will look like this: idprovider.myoidcprovider.rules.forceEmailVerification=true

The ID Provider must be configured, many of the fields are the information gathered from authorization server configuration (optionally available at the WellKnown endpoint of your Authorization server, /.well-known/openid-configuration).

​

Overview

The following settings are allowed to be used in com.enonic.app.oidcidprovider.cfg (field descriptions follow below):

autoinit=  (true | false, optional)

idprovider.<idprovidername>.issuer=  (string, required)
idprovider.<idprovidername>.authorizationUrl=  (string, required)
idprovider.<idprovidername>.tokenUrl=  (string, required)
idprovider.<idprovidername>.userinfoUrl=  (string, optional)
idprovider.<idprovidername>.method=  ((basic|port|jwt), optional, default to "post")
idprovider.<idprovidername>.scopes=  (space separated strings, optional, default to "profile email")

# Optional 'additionalEndpoints' namespace
# Is an array, that uses index (integer, starts from 0) to set items with 'name' and 'url' fields
idprovider.<idprovidername>.additionalEndpoints.0.name=  (string, required)
idprovider.<idprovidername>.additionalEndpoints.0.url=  (string, required)

# Optional 'endSession' namespace
idprovider.<idprovidername>.endSession.url=  (string, required)
idprovider.<idprovidername>.endSession.idTokenHintKey=  (string, optional)
idprovider.<idprovidername>.endSession.postLogoutRedirectUriKey=  (string, optional)

# Optional 'additionalParameters' namespace
# Is an array, that uses index (integer, starts from 0) to set items with 'key' and 'value' fields
idprovider.<idprovidername>.endSession.additionalParameters.0.key=  (string, required)
idprovider.<idprovidername>.endSession.additionalParameters.0.value=  (string, required)

idprovider.<idprovidername>.clientId=  (string, required)
idprovider.<idprovidername>.clientSecret=  (string, required)

idprovider.<idprovidername>.mappings.displayName=  (string, required)
idprovider.<idprovidername>.mappings.email=  (string, required)
idprovider.<idprovidername>.mappings.defaultGroups=  (space separated group keys, optional)

idprovider.<idprovidername>.rules.forceEmailVerification=  (true | false, required)

​

Fields in the config

  • autoinit: Automatic initialization. If the config file contains autoinit=true, then during startup this app will automatically create ID providers for all settings declared in the file, if they don’t already exist. For example, idprovider.myfirstidp.someKey=someValue and idprovider.anotheridp.anotherKey=anotherValue will declare two idproviders named myfirstidp and anotheridp.

Authorization Server

  • issuer: Issuer identifier. Value of issuer in your OpenID Provider configuration.

  • authorizationUrl: Authorization endpoint URL. Value of authorization_endpoint in your OpenID Provider configuration.

  • tokenUrl: Token endpoint URL. Value of token_endpoint in your OpenID Provider configuration.

  • method: Client authentication method. The value is a string, either post, basic, or jwt.

  • scopes: Scope/Claims to retrieve in addition to the mandatory "openid" scope. We recommend setting the two standard scopes: profile and email. The value is a space-separated list of scopes, eg. profile email.

Additional OAuth2 endpoints

  • additionalEndpoints…​ (idprovider.<idprovidername>.additionalEndpoints…​ namespace): Additional OAuth2 endpoints used to retrieve additional user information using the access token. This additionalEndpoints namespace requires an array immediately below it, with two required fields below each item in the array. Array starts counting on 0, so for example, idprovider.<idprovidername>.additionalEndpoints.0.name sets the name for the first item, while idprovider.<idprovidername>.additionalEndpoints.1.url sets url for the second one, etc.

    • name: Value used to store these claims under a same scope in the user profile.

    • url: Endpoint URL.

End session

  • endSession…​ (idprovider.<idprovidername>.endSession…​ namespace): OIDC Front-Channel Logout configuration parameters. See End Session for more information.

    • url: End session URL. Value of end_session_endpoint in your OpenID Provider configuration.

    • idTokenHintKey: ID Token Hint parameter name. Value of id_token_hint in your OpenID Provider configuration.

    • postLogoutRedirectUriKey: Post logout redirect URI parameter name. Value of post_logout_redirect_uri in your OpenID Provider configuration.

    • additionalParameters…​ (idprovider.<idprovidername>.endSession.additionalParameters…​ namespace): Additional OIDC Front-Channel Logout. This additionalParameters namespace requires an array immediately below it, with two required fields below each item in the array. Array starts counting on 0, so for example, idprovider.<idprovidername>.endSession.additionalParameters.0.key sets the key for the first item, while idprovider.<idprovidername>.endSession.additionalParameters.1.value sets value for the second one, etc.

      • key

      • value

Client

  • clientId: Client identifier, received or generated during creation of your Client/Application (this application uses the authentication method "client_secret_post" for token retrieval).

  • clientSecret: Client secret, received or generated during creation of your Client/Application (this application uses the authentication method "client_secret_post" for token retrieval).

User creation

  • mappings…​ (idprovider.<idprovidername>.mappings…​ namespace): You may configure the rules containing placeholders used to create users inside Enonic: values will be replaced with information provided by the placeholder expression.

    • displayName: Template for the display name in format of @@{expression}, e.g. @@{userinfo.preferred_username}.

    • email: Template for the email in format of @@{expression}, e.g. @@{userinfo.email}.

    • defaultGroups: Groups to assign to this user on creation. A list of space-separated group keys. The key must be in the format group:[idprovidername]:[groupname], e.g. group:myoidcprovider:authors.

Rules

  • rules…​ (idprovider.<idprovidername>.rules…​ namespace): Additional rules enforced on login.

    • forceEmailVerification: Enforce email verification. Check the claim email_verified (returned with the scope email)..

​

End Session

OIDC Front-Channel Logout specifications are still in draft. This might not be supported by your authentication server. You can check if the endpoint is available in the Open ID Configuration (.well-known/openid-configuration) under the field end_session_endpoint There might also be another custom endpoint available that achieves the same purpose. The ID Provider Configuration schema tries to be dynamic enough to handle all cases.

​

Example: Auth0

  • End Session URL: [Domain URL]/v2/logout

  • Post Logout Redirect URI parameter name: returnTo

  • Additional Parameters:

    • clientId = [Client ID]

​

Example: Google

Not available

​

Example: Azure AD

​

Example: Difi/ID-porten/VER1

​

Upgrade Notes

Version 2.0 of this app introduces a breaking change: ID Providers can only be configured via the config file (com.enonic.app.oidcidprovider.cfg) instead of editing the ID Provider form in the Users app UI. So, no configuration will be stored in / read from the data layer anymore.

The following upgrade notes assume you currently have an earlier (1.x) version of OIDC ID provider app installed:

idprovider migration

When editing an ID provider in the Users app, the ID provider name (1) is found (or edited) directly below the displayName field, and in previous versions of this app the configuration form was opened by clicking the pencil (2) icon on the ID provider application.

Migrate the configuration

Create com.enonic.app.oidcidprovider.cfg in your XP instance’s config folder. Then in the XP backoffice, open the Users app and edit the ID provider. Note the ID provider name (without the leading slash), and click the edit-form icon to view the configuration entered in the old app. Transfer the values into the .cfg file, the way it’s specified above (the order may vary).

For mapping config (idprovider.<idprovidername>.mappings.displayName and idprovider.<idprovidername>.mappings.email), remember the @@` syntax for the placeholders. Replace any ${ in the values with @@{!

Contents