OpenID Connect Authenticator

The OpenID Connect (OIDC) authenticator allows users to be authenticated by any external OIDC Provider (OP) that supports the following aspects of the standard:

  • OpenID Connect Discovery 1.0 whereby the OP publishes its configuration
  • The authorization code flow
  • Signed ID Tokens
  • Encrypted ID Tokens
  • Fetching additional claims from Userinfo endpoint of OP
  • JSON Web Key Set published at a jwks_uri

A client needs to be registered at the OP, and have a redirect URI configured as described in the next section.

The Redirect URI

The redirect URI is the URI where the OP will redirect the user to when the authentication is done. The URI that the Authentication Service uses is generated automatically based on configuration, and is the path to the authenticator with an added /callback. This last part of the path is only used in the communication between the Authentication Service and the OP, and can not be changed whereas the preceding components of the path can be.

The form is like this:

<base-url>/<authentication-endpoint>/<authenticator-id>/callback

For example, for a server running on server1.local and a protocol of https and listening on port 8443 and having an authentication endpoint configured to be /authn/authenticate and with an OIDC authenticator instance called oidc1, the redirect URI would be:

https://server1.local:8443/authn/authenticate/oidc1/callback

Configuration

The general authenticator configuration is described under Authenticator Base Configuration. This section describes the additional parameters that are available for the OIDC authenticator.

Important

Authenticator base is /profiles/profile{id type}/settings/authentication-service/authenticators/

List Entry: <authenticator_base>/authenticator/ (key id)

configuration-url: The url to the openid-configuration document at the OP

type string

mandatory

client_id: The OAuth 2 client ID that is registered at the OP

type string

mandatory

use-http-basic-authentication: When enabled, the client_id and client_secret are sent in a RFC2617 compliant header instead of the request-body

type boolean

enabled only when client_secret is used as a Client Authentication Method

Client authentication method (a choice of the following):

mandatory

client_secret: The OAuth 2 client secret that is registered at the OP
type string
asymmetrically-signed-jwt: The asymmetrically signed JWT (private_key_jwt) settings
signing-key: Signing key for the asymmetrically signed JWT (private_key_jwt)

mandatory true

type leafref: "/base:facilities/base:crypto/base:signing-keys/base:signing-key/base:id"

signature-algorithm: Signature algorithm for the asymmetrically signed JWT (private_key_jwt)

mandatory true

type enum

symmetrically-signed-jwt: The symmetrically signed JWT (client_secret_jwt) settings
signing-key: Signing key for the symmetrically signed JWT (client_secret_jwt)

mandatory true

type leafref: "/base:facilities/base:crypto/base:signing-keys/base:signing-key/base:id"

signature-algorithm: The signature algorithms to allow for JWT (client_secret_jwt)

mandatory true

type enum

Note: Both asymmetrically and symmetrically signed JWT are sent to the OP endpoint as the client_assertion parameter.

scope: The scopes to ask the OP for as a space-separated list

type string

default openid

clock_skew: The allowed clock-skew in seconds when validating the JWT from the OP

type uint32

default 60

authentication-context-class-reference: The space-separated list of authentication methods that the OP should use
type string

Example (asymmetrically-signed-jwt):

<authenticator xmlns="https://curity.se/ns/conf/profile/authentication">
    <id>oidc</id>
    <oidc xmlns="https://curity.se/ns/conf/authenticators/oidc">
        <configuration-url>https://example.com/.well-known/openid-configuration</configuration-url>
        <client-id>MyOidcClient</client-id>
        <asymmetrically-signed-jwt>
            <signing-key>oidc-signing-key</signing-key>
            <signature-algorithm>RS256</signature-algorithm>
        </asymmetrically-signed-jwt>
        <authentication-context-class-reference>example-acr</authentication-context-class-reference>
    </oidc>
</authenticator>

Example (symetrically-signed-jwt):

<authenticator xmlns="https://curity.se/ns/conf/profile/authentication">
    <id>oidc</id>
    <oidc xmlns="https://curity.se/ns/conf/authenticators/oidc">
        <configuration-url>https://example.com/.well-known/openid-configuration</configuration-url>
        <client-id>MyOidcClient</client-id>
         <symmetrically-signed-jwt>
            <signing-key>oidc-signing-key</signing-key>
            <signature-algorithm>HS256</signature-algorithm>
        </symmetrically-signed-jwt>
        <authentication-context-class-reference>example-acr</authentication-context-class-reference>
    </oidc>
</authenticator>

Example (secret):

<authenticator xmlns="https://curity.se/ns/conf/profile/authentication">
    <id>oidc</id>
    <oidc xmlns="https://curity.se/ns/conf/authenticators/oidc">
        <configuration-url>https://example.com/.well-known/openid-configuration</configuration-url>
        <client-secret>123456778912345677890012345677890</client-secret>
        <client-id>MyOidcClient</client-id>
        <authentication-context-class-reference>example-acr</authentication-context-class-reference>
    </oidc>
</authenticator>

encrypted-id-token Some providers return encrypted ID-tokens (JWE). To handle those, a decryption key needs to be configured. Additionally, two whitelists can be added.

allowed-algorithms: A whitelist for the key management algorithms. These algorithms are used to derive the actual content encryption key. Empty list means any algorithm can be used. type list

allowed-content-encryption-algorithms: A whitelist for the allowed decryption algorithms. Any of these algorithms can be used to decrypt the token. Empty list means any algorithm can be used. type list

fetch-userinfo The authenticator can be configured to fetch additional claims from the Userinfo endpoint of the OpenID provider. The format of the response can be different depending on the provider, and the expected format needs to be configured for this authenticator. Following formats are supported:

plain: The response is in plain JSON.

signed: The response is a signed JWT (JWS). The signature and expiry of the JWT will be validated. The public key will be collected from the metadata.

encrypted: The response is an encrypted JWT (JWE). The JWT will be decrypted using the configured key, and the expiry will be validated.

Decryption key is mandatory

The payload of the decrypted JWT can be be of two formats.

  • Signed JWT. The signature and expiry of the JWT will be validated. They public key will be collected from the metadata.
  • Plain JSON.

For encrypted userinfo, it’s also possible to configure allowed-content-encryption-algorithms and allowed-algorithms

Important

If the response is of any other format than the configured one, the authentication will abort.

The result of the authentication will be the Userinfo claims, merged with the claims from the ID token.