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

Redirect URI Override#

The redirect URI that will be used in authorization (and token) requests can be overridden by setting the redirect-uri-override configuration value. Note that the real redirect URI of the OIDC authenticator will not be changed. This means that there has to be a component that relays the authorization response to the real redirect URI of the OIDC authenticator. Overriding the redirect URI may be useful when migrating to the OIDC authenticator so that existing clients don’t have to change the redirect URI immediately.

JWKS Endpoint#

The OIDC authenticator publishes its JSON Web Key Set on the anonymous endpoint of the authenticator, under the /jwks subpath. For example, if an authenticator with ID my-oidc-authenticator is configured on an authentication profile that has the Anonymous Endpoint mapped on /authenticate/anonymous, then the metadata is published on the path /authenticate/anonymous/my-oidc-authenticator/jwks.

When used as a dynamic authenticator the metadata endpoint expects the federation id to be passed in the query parameter (fid). When the federation id is not provided the default value is used. For example, the request for JWKS with federation ID test-federation-id and dynamic authenticator ID my-oidc-dynamic-authenticator (configured on an authentication profile that has the Anonymous Endpoint mapped on /authenticate/anonymous) will be the following /authenticate/anonymous/my-oidc-dynamic-authenticator/jwks?fid=test-federation-id.

Returned attributes#

The claims from the returned ID Token describing the user will be returned in the Subject Attributes, as well as the attributes returned from the Userinfo endpoint if configured. Additional attributes will be added to the context attributes, described in the table below. All values are optional and depend on if the OP returns them.

Context Attribute Name	OP Attribute Name	Value From
iss	iss	ID Token
aud	aud	ID Token
exp	exp	ID Token
iat	iat	ID Token
auth_time	auth_time	ID Token
amr	amr	ID Token
op_acr	acr	ID Token
op_access_token	access_token	Token Response
op_refresh_token	refresh_token	Token Response

Parameter Mappings#

Since version 9.4, the oidc authenticator supports adding custom query parameters in the authorization request. Those parameters can take their value either from a query parameter of the original request to The Curity Identity Server or have a static value from configuration.

If use-value-from-request is used, the authorization request to the OpenID Provider will include the custom query parameter only if the original request to The Curity Identity Server contains the configured query parameter.

Configuration#

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

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

redirect-uri-override: An optional override of the redirect URI that will be used in the authorization requests. The OP will redirect to this URI, however the actual redirect URI of this authenticator will remain unchanged. This means that the authorization response has to be relayed to the actual redirect URI of this authenticator. type inet:uri

Examples#

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>

Symmetrically 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>

Administration

System and Operation

Facilities

Profiles

Developer Guide

Configuration Reference