The OpenID Connect (OIDC) authenticator allows users to be authenticated by any external OIDC Provider (OP) that supports the following aspects of the standard:
A client needs to be registered at the OP, and have a redirect URI configured as described in the next section.
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
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.
redirect-uri-override
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.
/jwks
my-oidc-authenticator
/authenticate/anonymous
/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.
fid
default
test-federation-id
my-oidc-dynamic-authenticator
/authenticate/anonymous/my-oidc-dynamic-authenticator/jwks?fid=test-federation-id
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 depends on if the OP returns them.
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.
oidc
Note
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.
use-value-from-request
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)
type string
mandatory
type boolean
enabled only when client_secret is used as a Client Authentication Method
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
mandatory true
type leafref: "/base:facilities/base:crypto/base:signing-keys/base:signing-key/base:id"
"/base:facilities/base:crypto/base:signing-keys/base:signing-key/base:id"
type enum
Note: Both asymmetrically and symmetrically signed JWT are sent to the OP endpoint as the client_assertion parameter.
client_assertion
default openid
type uint32
default 60
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
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. The 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
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
Decryption key is mandatory
The payload of the decrypted JWT can be be of two formats.
For encrypted userinfo, it’s also possible to configure allowed-content-encryption-algorithms and allowed-algorithms
If the response is of any other format than the configured one, the authentication will abort.
When a signed JWT is used in the UserInfo response, it must, by default, include the issuer (iss) and audience (aud) claims. If a misbehaving OpenID provider is used, it’s possible to allow those claims to be missing by setting strict-validation-when-signed to false. It’s recommended to not use this setting and try to correct the provider.
iss
aud
strict-validation-when-signed
false
The result of the authentication will be the Userinfo claims, merged with the claims from the ID token. When a claim with the same name exists on both sets of claims, the resulting value is determined as follows:
type list
Example (parameter-mappings):
<authenticator> <id>oidc</id> <oidc xmlns="https://curity.se/ns/conf/authenticators/oidc"> <parameter-mappings> <parameter-mapping> <parameter-name>queryParameter1</parameter-name> <static-value>abcdefg</static-value> </parameter-mapping> <parameter-mapping> <parameter-name>queryParameter2</parameter-name> <use-value-from-request>state</use-value-from-request> </parameter-mapping> </parameter-mappings> </oidc> </authenticator>