OpenID Connect 1.0 Provider
On this page
- Configuration
- Options
- hmac_secret
- jwks
- enable_client_debug_messages
- minimum_parameter_entropy
- enforce_pkce
- enable_pkce_plain_challenge
- enable_jwt_access_token_stateless_introspection
- discovery_signed_response_alg
- discovery_signed_response_key_id
- require_pushed_authorization_requests
- authorization_policies
- lifespans
- cors
- clients
- Integration
Authelia currently supports the OpenID Connect 1.0 Provider role as an open beta feature. We currently do not support the OpenID Connect 1.0 Relying Party role. This means other applications that implement the OpenID Connect 1.0 Relying Party role can use Authelia as an OpenID Connect 1.0 Provider similar to how you may use social media or development platforms for login.
The OpenID Connect 1.0 Relying Party role is the role which allows an application to use GitHub, Google, or other OpenID Connect 1.0 Providers for authentication and authorization. We do not intend to support this functionality at this moment in time.
This section covers the OpenID Connect 1.0 Provider configuration. For information on configuring individual registered clients see the OpenID Connect 1.0 Clients documentation.
More information about the beta can be found in the roadmap and in the integration documentation.
Configuration
Options
hmac_secret
Important Note: This can also be defined using a secret which is strongly recommended especially for containerized deployments.
The HMAC secret used to sign the JWT’s. The provided string is hashed to a SHA256 (RFC6234) byte string for the purpose of meeting the required format.
It’s strongly recommended this is a Random Alphanumeric String with 64 or more characters.
jwks
The list of issuer JSON Web Keys. At least one of these must be an RSA Private key and be configured with the RS256 algorithm. Can also be used to configure many types of JSON Web Keys for the issuer such as the other RSA based JSON Web Key formats and ECDSA JSON Web Key formats.
The default key for each algorithm is decided based on the order of this list. The first key for each algorithm is
considered the default if a client is not configured to use a specific key id. For example if a client has
id_token_signed_response_alg ES256
and
id_token_signed_response_key_id is not specified then the first ES256
key in this list is used.
The following is a contextual example (see below for information regarding each option):
key_id
Completely optional, and generally discouraged unless there is a collision between the automatically generated key id’s. If provided must be a unique string with 100 or fewer characters, with a recommendation to use a length less than 15. In addition, it must meet the following rules:
- Match the regular expression
^[a-zA-Z0-9](([a-zA-Z0-9._~-]*)([a-zA-Z0-9]))?$
which should enforce the following rules:- Start with an alphanumeric character.
- End with an alphanumeric character.
- Only contain the RFC3986 Unreserved Characters.
The default if this value is omitted is the first 7 characters of the public key SHA256 thumbprint encoded into hexadecimal, followed by a hyphen, then followed by the lowercase algorithm value.
use
The key usage. Defaults to sig
which is the only available option at this time.
algorithm
The algorithm for this key. This value typically optional as it can be automatically detected based on the type of key in some situations.
See the response object table in the integration guide
for more information. The Algorithm
column lists supported values, the Key
column references the required
key type constraints that exist for the algorithm, and the JWK Default Conditions
column briefly explains the
conditions under which it’s the default algorithm.
At least one RSA256
key must be provided.
key
The private key associated with this key entry.
It is recommended that you use a file to specify this particular option. In particular we recommend enabling the
template
file filter and using the following example to assuming the path to
the file is /config/secrets/oidc/jwks/rsa.2048.key
:
The private key used to sign/encrypt the OpenID Connect 1.0 issued JWT’s. The key must be generated by the administrator and can be done by following the Generating an RSA Keypair guide.
The key MUST:
- Be a PEM block encoded in the DER base64 format (RFC4648).
- Be either:
If the certificate_chain is provided the private key must include matching public key data for the first certificate in the chain.
certificate_chain
The certificate chain/bundle to be used with the key DER base64 (RFC4648) encoded PEM format used to sign/encrypt the OpenID Connect 1.0 JWT’s. When configured it enables the x5c and x5t JSON key’s in the JWKs Discoverable Endpoint as per RFC7517.
The first certificate in the chain must have the public key for the key, each certificate in the chain must be valid for the current date, and each certificate in the chain should be signed by the certificate immediately following it if present.
enable_client_debug_messages
Allows additional debug messages to be sent to the clients.
minimum_parameter_entropy
This controls the minimum length of the nonce
and state
parameters.
Security Notice: Changing this value is generally discouraged, reducing it from the default can theoretically make certain scenarios less secure. It is highly encouraged that if your OpenID Connect 1.0 Relying Party does not send these parameters or sends parameters with a lower length than the default that they implement a change rather than changing this value.
This restriction can also be disabled entirely when set to -1
.
enforce_pkce
Proof Key for Code Exchange enforcement policy: if specified, must be
either never
, public_clients_only
or always
.
If set to public_clients_only
(default), PKCE will be required for public clients using the
Authorization Code Flow.
When set to always
, PKCE will be required for all clients using the Authorization Code flow.
Security Notice: Changing this value to never
is generally discouraged, reducing it from the default can
theoretically make certain client-side applications (mobile applications, SPA) vulnerable to CSRF and authorization code
interception attacks.
enable_pkce_plain_challenge
Allows PKCE plain
challenges when set to true
.
Security Notice: Changing this value is generally discouraged. Applications should use the S256
PKCE challenge
method instead.
enable_jwt_access_token_stateless_introspection
Allows JWT Access Tokens to be introspected using a stateless model where the JWT claims have all of the required introspection information, and assumes that they have not been revoked. This is strongly discouraged unless you have a very specific use case.
A client with an access_token_signed_response_alg or access_token_signed_response_key_id must be configured for this option to be enabled.
discovery_signed_response_alg
Important Note: Many clients do not support this option and it has a performance cost. It’s therefore recommended unless you have a specific need that you do not enable this option.
Note: This value is completely ignored if the discovery_signed_response_key_id is defined.
The algorithm used to sign the OAuth 2.0 Authorization Server Metadata and OpenID Connect Discovery 1.0 responses.
Per the specifications this Signed JSON Web Token is stored in the signed_metadata
value using the compact encoding.
See the response object section of the integration guide for more information including the algorithm column for supported values.
With the exclusion of none
which excludes the signed_metadata
value, the algorithm chosen must have a key
configured in the jwks section to be considered valid.
See the response object section of the integration guide for more information including the algorithm column for supported values.
discovery_signed_response_key_id
Important Note: Many clients do not support this option and it has a performance cost. It’s therefore recommended unless you have a specific need that you do not enable this option.
Note: This value automatically configures the discovery_signed_response_alg value with the algorithm of the specified key.
The algorithm used to sign the OAuth 2.0 Authorization Server Metadata and OpenID Connect Discovery 1.0 responses.
The value of this must one of those provided or calculated in the jwks. Per the specifications this Signed JSON
Web Token is stored in the signed_metadata
value using the compact encoding.
require_pushed_authorization_requests
When enabled all authorization requests must use the Pushed Authorization Requests flow.
authorization_policies
The authorization policies section allows creating custom authorization policies which can be applied to clients. This is useful if you wish to only allow specific users to access specific clients i.e. RBAC. It’s generally recommended however that users rely on the OpenID Connect 1.0 relying party to provide RBAC controls based on the available claims.
Each policy applies one of the effective policies which can be either one_factor
or two_factor
as per the standard
policies, or also the deny
policy which is exclusively available via these configuration options.
Each rule within a policy is matched in order where the first fully matching rule is the applied policy. If the deny
rule is matched the user is not asked for consent and it is considered a rejected consent and returns an
OpenID Connect 1.0 access_denied
error.
The key for the policy itself is the name of the policy, which is used when configuring the client
authorization_policy option. In the example we name the policy policy_name
.
The follow example shows a policy named policy_name
which will deny
access to users in the services
group, with
a default policy of two_factor
for everyone else. This policy is applied to the client with id
client_with_policy_name
. You should refer to the below headings which describe each configuration key in more detail.
default_policy
The default effective policy of none of the rules are able to determine the effective policy.
rules
The list of rules which this policy should consider when choosing the effective policy. This must be included for the policy to be considered valid.
policy
The policy which is applied if this rule matches. Valid values are one_factor
, two_factor
, and deny
.
subject
The subjects criteria as per the Access Control Configuration. This must be included for the rule to be considered valid.
lifespans
Token lifespans configuration. It’s generally recommended keeping these values similar to the default values and to utilize refresh tokens. For more information read this documentation about the token lifespan.
access_token
The default maximum lifetime of an access token.
authorize_code
The default maximum lifetime of an authorize code.
id_token
The default maximum lifetime of an ID token.
refresh_token
The default maximum lifetime of a refresh token. The refresh token can be used to obtain new refresh tokens as well as access tokens or id tokens with an up-to-date expiration.
A good starting point is 50% more or 30 minutes more (which ever is less) time than the highest lifespan out of the access token lifespan and the id token lifespan. For instance the default for all of these is 60 minutes, so the default refresh token lifespan is 90 minutes.
custom
The custom lifespan configuration allows customizing the lifespans per-client. The custom lifespans must be utilized with the client lifespan option which applies those settings to that client. Custom lifespans can be configured in a very granular way, either solely by the token type, or by the token type for each grant type. If a value is omitted it automatically uses the next value in the precedence tree. The tree is as follows:
- Custom by token type and by grant.
- Custom by token type.
- Global default value.
The key for the custom lifespan itself is the name of the lifespan, which is used when configuring the client
lifespan option. In the example we name the lifespan lifespan_name
.
Example
The following is an exhaustive example of all of the options available. Each of these options must follow all of the same rules as the access_token, authorize_code, id_token, and refresh_token global default options. The global lifespan options are included for reference purposes.
cors
Some OpenID Connect 1.0 Endpoints need to allow cross-origin resource sharing; however, some are optional. This section allows you to configure the optional parts. We reply with CORS headers when the request includes the Origin header.
endpoints
A list of endpoints to configure with cross-origin resource sharing headers. It is recommended that the userinfo
option is at least in this list. The potential endpoints which this can be enabled on are as follows:
- authorization
- pushed-authorization-request
- token
- revocation
- introspection
- userinfo
allowed_origins
A list of permitted origins.
Any origin with https is permitted unless this option is configured or the allowed_origins_from_client_redirect_uris option is enabled. This means you must configure this option manually if you want http endpoints to be permitted to make cross-origin requests to the OpenID Connect 1.0 endpoints, however this is not recommended.
Origins must only have the scheme, hostname and port, they may not have a trailing slash or path.
In addition to an Origin URI, you may specify the wildcard origin in the allowed_origins. It MUST be specified by itself
and the allowed_origins_from_client_redirect_uris MUST NOT be enabled. The
wildcard origin is denoted as *
. Examples:
allowed_origins_from_client_redirect_uris
Automatically adds the origin portion of all redirect URI’s on all clients to the list of allowed_origins, provided they have the scheme http or https and do not have the hostname of localhost.
clients
See the OpenID Connect 1.0 Registered Clients documentation for configuring clients.
Integration
To integrate Authelia’s OpenID Connect 1.0 implementation with a relying party please see the integration docs.