OpenID Connect 1.0 Provider

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.

Variables#

Some of the values within this page can automatically be replaced with documentation variables.

Set Documentation Variables

Configuration#

identity_providers:
  oidc:
    hmac_secret: 'this_is_a_secret_abc123abc123abc'
    jwks:
      - key_id: 'example'
        algorithm: 'RS256'
        use: 'sig'
        key: |
          -----BEGIN RSA PRIVATE KEY-----
          ...
          -----END RSA PRIVATE KEY-----          
        certificate_chain: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----          
    enable_client_debug_messages: false
    minimum_parameter_entropy: 8
    enforce_pkce: 'public_clients_only'
    enable_pkce_plain_challenge: false
    enable_jwt_access_token_stateless_introspection: false
    discovery_signed_response_alg: 'none'
    discovery_signed_response_key_id: ''
    require_pushed_authorization_requests: false
    authorization_policies:
      policy_name:
        default_policy: 'two_factor'
        rules:
          - policy: 'deny'
            subject: 'group:services'
    lifespans:
      access_token: '1h'
      authorize_code: '1m'
      id_token: '1h'
      refresh_token: '90m'
    cors:
      endpoints:
        - 'authorization'
        - 'token'
        - 'revocation'
        - 'introspection'
      allowed_origins:
        - 'https://example.com'
      allowed_origins_from_client_redirect_uris: false

Options#

hmac_secret#

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):

identity_providers:
  oidc:
    jwks:
      - key_id: 'example'
        algorithm: 'RS256'
        use: 'sig'
        key: |
          -----BEGIN RSA PRIVATE KEY-----
          ...
          -----END RSA PRIVATE KEY-----          
        certificate_chain: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----          

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 used to sign or encrypt the OpenID Connect 1.0 issued JWT’s when using this JWK. 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:
  • An RSA private key:
    • Encoded in conformance to the PKCS#8 or PKCS#1 specifications.
    • Have a key size of at least 2048 bits.
  • An ECDSA private key:
    • Encoded in conformance to the PKCS#8 or SECG1 specifications.
    • Use one of the following elliptical curves:
      • P-256.
      • P-384.
      • P-512.
• Include matching public key data if the certificate_chain is provided for the first certificate in the chain.

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:

identity_providers:
  oidc:
    jwks:
      - key: {{ secret "/config/secrets/oidc/jwks/rsa.2048.key" | mindent 10 "|" | msquote }}

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 Web Key’s in the JSON Web Key Set Discoverable Endpoint as per RFC7517.

The certificate chain MUST:

• Include matching public key data for the key.
• Include only certificates valid for the current date.
• Contain only generally valid certificates.
• Include only sequentially signed certificates i.e. the first certificate must be signed by the second certificate (if provided) and the second certificate must be signed by the third (if provided), and so on.

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. Setting this value to -1 completely disables this validation.

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.

enable_pkce_plain_challenge#

Allows PKCE plain challenges when set to true.

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#

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#

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.

identity_providers:
  oidc:
    authorization_policies:
      policy_name:
        default_policy: 'two_factor'
        rules:
          - policy: 'deny'
            subject: 'group:services'
    clients:
      - client_id: 'client_with_policy_name'
        authorization_policy: 'policy_name'

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:

1. Custom by token type and by grant.
2. Custom by token type.
3. 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.

identity_providers:
  oidc:
    lifespans:
      access_token: '1h'
      authorize_code: '1m'
      id_token: '1h'
      refresh_token: '90m'
      custom:
        lifespan_name:
          access_token: '1h'
          authorize_code: '1m'
          id_token: '1h'
          refresh_token: '90m'
          grants:
            authorize_code:
              access_token: '1h'
              authorize_code: '1m'
              id_token: '1h'
              refresh_token: '90m'
            implicit:
              access_token: '1h'
              authorize_code: '1m'
              id_token: '1h'
              refresh_token: '90m'
            client_credentials:
              access_token: '1h'
              authorize_code: '1m'
              id_token: '1h'
              refresh_token: '90m'
            refresh_token:
              access_token: '1h'
              authorize_code: '1m'
              id_token: '1h'
              refresh_token: '90m'
            jwt_bearer:
              access_token: '1h'
              authorize_code: '1m'
              id_token: '1h'
              refresh_token: '90m'

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:

identity_providers:
  oidc:
    cors:
      allowed_origins: "*"

identity_providers:
  oidc:
    cors:
      allowed_origins:
        - "*"

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.