Configuration of Cadenza for OIDC

General

The configuration of Cadenza for OIDC is done by additions and changes to the configuration. The following steps must be executed:

Mandatory: Activate the plugin AccessManager_OAuth (configuration of plugins)
Mandatory: Add a new authenticator section to the access manager configuration (configuration for the plugin AccessManager)
Optional: add a new provider for user print name suggestions (configuration for the plugin AccessManager)
Mandatory: add the mandatory configuration for AccessManager_OAuth (configuration for the plugin AccessManager_OAuth)

Authentication and group mapping can be combined from different providers. It is for example possible to use OIDC for authentication and rely on LDAP for the group mapping. In connection with OIDC you have to observe that OIDC cannot be used only for group mapping because the groups are part of the token received by Cadenza during the authentication.

OIDC servers are offering a self-description at the OpenID Connect Discovery endpoint. This endpoint must be accessible at the context URL /.well-known/openid-configuration. Depending on the implementation of the IDP the part before this URL can be slightly different.

The OAuth authenticator as well as other non-interactive authentication methods must be configured before interactive authenticators like LDAP.

The OAuth authenticator is used together with other SSO mechanisms like JWT or SPNEGO, it must be the last configured authenticator of this type.

For understanding the configuration of OIDC in Cadenza a basic understanding of the underlying workflow and the terms used is necessary.

Term	Explanation
Access Token	Defined by OAuth, this is normally a JWT but can also be an opaque token, depending on the implementation of the IDP.
Authorization Code Flow	One of the possible authentication flows defined for OIDC which is being used by Cadenza. This flow ensures that the user credentials are never sent to Cadenza.
Authorization Code	The authorization code is a string that is sent to Cadenza as the SP during the login process.
Claim	A claim is part of a JWT which contains information about the authenticated user. Examples for often used claims are the preferred username, the email address or the groups for the user. The content can be a simple string as well as a complex JSON document.
Client ID & Client Secret	These are the credentials of Cadenza at the IDP, used for authenticating itself
Identity Provider (IDP)	The IDP is the component that authenticates users and provides identity information.
ID Token	Defined by the OIDC specification, this ist always a JWT. It contains the assurance of the identity of the user and additional information about group membership or details like the print name or email address.
Redirect URL	URL to which the users’s browser is being redirected after successful authentication at the IDP
Refreshtoken	Token used for getting a new ID token or access token from the IDP. In general the ID token and access token have a short validity while the refresh token is valid for a longer time. The client application is responsible for renewing the ID token or access token with the refresh token after its lifespan has ended.
Service Provider (SP) or Relying Party (RP)	This term is used for the application providing the actual service to the user. It relies on the IDP for authentication and authorization.

Term

Explanation

Access Token

Defined by OAuth, this is normally a JWT but can also be an opaque token, depending on the implementation of the IDP.

Authorization Code Flow

One of the possible authentication flows defined for OIDC which is being used by Cadenza. This flow ensures that the user credentials are never sent to Cadenza.

Authorization Code

The authorization code is a string that is sent to Cadenza as the SP during the login process.

Claim

A claim is part of a JWT which contains information about the authenticated user. Examples for often used claims are the preferred username, the email address or the groups for the user. The content can be a simple string as well as a complex JSON document.

Client ID & Client Secret

These are the credentials of Cadenza at the IDP, used for authenticating itself

Identity Provider (IDP)

The IDP is the component that authenticates users and provides identity information.

ID Token

Defined by the OIDC specification, this ist always a JWT. It contains the assurance of the identity of the user and additional information about group membership or details like the print name or email address.

Redirect URL

URL to which the users’s browser is being redirected after successful authentication at the IDP

Refreshtoken

Token used for getting a new ID token or access token from the IDP. In general the ID token and access token have a short validity while the refresh token is valid for a longer time. The client application is responsible for renewing the ID token or access token with the refresh token after its lifespan has ended.

Service Provider (SP) or Relying Party (RP)

This term is used for the application providing the actual service to the user. It relies on the IDP for authentication and authorization.

There are multiple elements which need to be in place for the OIDC-based login to succeed:

The user must be known to the IDP
The user must be part of groups known to Cadenza
The groups must be included in the token used by Cadenza
Cadenza must be configured as a client of the IDP in order to be able to request a token
Cadenza must be able to verify the signature of the token with the public key/certificate of the IDP which is used for token signing (this is not the public key/certificate for TLS encryption)

Cadenza uses the Authorization Code Flow for authenticating users against an IDP. This flow ensures that the credentials of the user are never known to Cadenza. This flow involves the following steps:

The browser requests the URL used by Cadenza
Cadenza detects that this user has not yet a session and sends a redirect response to the browser which includes a Redirect URL
The user authenticates against the IDP
After a successful authentication the user receives a redirect to the URL which was previously sent by Cadenza. This redirect includes an authorization code
Cadenza receives the authorization code and sends it to the IDP together with its own client id and client secret.
The IDP creates (depending on the request) an ID token or an access token and sends it back to Cadenza
Cadenza parses the token, validates its signature and extracts details like the print name, the mail address and the group memberships
The user is logged in and can use Cadenza

The Cadenza configuration uses the public key of the IDP, not its certificate. If your IDP does not provide the public key directly you can extract it from the certificate with OpenSSL with the command openssl x509 -in cert.pem -pubkey -noout, assuming that your certificate is stored in PEM format in the file cert.pem

Additional Configuration Options

Some features like impersonation and user suggestion are only available if you are using a supported version of Keycloak with access to the admin API. See Configuration of Keycloak for use with Cadenza for instructions how to configure those features.

PKCE: This is a feature which adds an additional layer of security to the exchange of information during the authorization code flow. It is enabled per default and can be switched off if the IDP does not provide it.
Relying Party Initiated Logout: This enables Cadenza to terminate the user session at the IDP upon logging out of Cadenza. The use of this feature is only possible if token passthrough is allowed.

Configuration to Use Access Tokens for WFS (Token Passthrough)

The option Login with WFS token authentication can be used for WFS data sources in the management center.

If a WFS datasource with activated access token authentication is being used, then the access token will be sent to the WFS server in the background. This will only work when the authenticator OAuth is being used for the specific user.

If allowTokenPassthrough is disabled, or the user is authenticated through another authenticator (not OpenID Connect), then views based on this data source will not be working.

Front-channel logout

This is an optional part of the OIDC specification that deals with the logout operation being triggered centrally by the user directly from a page in the IDP website (e.g. Keycloak), not from the RP (Cadenza), and ensures that the token is not just invalidated in the IDP but all the RPs are also notified about it immediately in order to perform the logout procedure for their HTTP sessions associated with the user.

This logout mechanism uses the user’s browser for the specific requests.

When registering the RP with the OP (IDP), we need to additionally provide the logout URL in order to be able to use front-channel logout. Cadenza provides an endpoint for this: /OAuth/logout

A concrete example of a complete front-channel logout url is: https://localhost:8000/trunk/OAuth/logout

To enable front-channel logout in your setup, log into the Keycloak admin ui and select the realm used by Cadenza, then navigate to Clients and select the client used by Cadenza, then jump to the Logout settings section and enable the Front-channel logout switch and fill the Front-channel logout URL.

Flow

The user navigates to Keycloak’s logout URL (for example http://localhost:8080/realms/disy/protocol/openid-connect/logout or https://idp-dev.disy.net/auth/realms/disy/protocol/openid-connect/logout) and presses the Logout button to confirm the operation.
In response the user’s browser loads an IDP rendered page that triggers a logout from all the applications (RPs), so e.g. Cadenza, by loading each application’s registered frontchannel logout URL in a separate iframe.
The RP processes the request to the logout endpoint by performing session invalidation and any necessary actions that are normally performed on logout.

Since the logout page of the IDP server will attempt to load the OpenID Connect front-channel logout url of Cadenza in an iframe we must be careful to ensure Cadenza is properly configured to specifically allow embedding in the IDP page. For this the Content Security Policy (CSP) has to be configured to allow this. This can be done by adding the URL of the IDP as an allowed 'source' in the csp/frame-ancestors element in the basicweb config, similar to this:

Setting the csp for the logout page of the IDP (basicweb-config.xml)

<csp>
  <frame-ancestors enabled="true">
    <!-- Specify the OIDC server URL here -->
    <source>https://idp-dev.disy.net</source>
  </frame-ancestors>
</csp>

Relying Party initiated Logout

With the configuration options relyingPartyInitiatedLogout and logoutUrl the Relying Party initiated logout URL can be enabled. For details see accessmanageroauth config.

Flow

If this feature is enabled then on Cadenza logout, Cadenza as the relying party (RP) calls the OIDC logout endpoint (IDP) including the (refreshed) id token of the user. After this the IDP logs out the user for the Cadenza session in the IDP and also from every application the user is authenticated since the last IDP login. Finally the user is redirected to the regular Cadenza logout page.

If the user clicks on Login via Single Sign-On (SSO) again in Cadenza, then he/she has to authenticate again at the IDP before getting a new session in Cadenza.

Configuration in the IDP

For this to work, the IDP needs to know the valid post logout URI of Cadenza.

The URL has the format http(s)://<webapp.context>:<webapp.port>/<instalation name>/login?loginStatus=loggedOut (e.g. https://example.org/cadenza/login?loginStatus=loggedOut)