RPJosh
/
authelia
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
authelia/docs/content/en/configuration/identity-providers/openid-connect/provider.md

18 KiB
Raw Blame History

title description lead date draft images menu weight toc aliases
OpenID Connect 1.0 Provider OpenID Connect 1.0 Provider Configuration Authelia can operate as an OpenID Connect 1.0 Provider. This section describes how to configure this. 2023-05-15T10:32:10+10:00 false
configuration
parent
openid-connect
190200 true
/c/oidc
/docs/configuration/identity-providers/oidc.html

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

The following snippet provides a configuration example for the OpenID Connect 1.0 Provider. This is not intended for production use it's used to provide context and an indentation example.

identity_providers:
  oidc:
    hmac_secret: this_is_a_secret_abc123abc123abc
    issuer_private_keys:
      - key_id: example
        algorithm: RS256
        use: sig
        key: |
          -----BEGIN RSA PUBLIC KEY-----
          MEgCQQDAwV26ZA1lodtOQxNrJ491gWT+VzFum9IeZ+WTmMypYWyW1CzXKwsvTHDz
          9ec+jserR3EMQ0Rr24lj13FL1ib5AgMBAAE=
          -----END RSA PUBLIC KEY----          
        certificate_chain: |
          -----BEGIN CERTIFICATE-----
          MIIBWzCCAQWgAwIBAgIQYAKsXhJOXKfyySlmpKicTzANBgkqhkiG9w0BAQsFADAT
          MREwDwYDVQQKEwhBdXRoZWxpYTAeFw0yMzA0MjEwMDA3NDRaFw0yNDA0MjAwMDA3
          NDRaMBMxETAPBgNVBAoTCEF1dGhlbGlhMFwwDQYJKoZIhvcNAQEBBQADSwAwSAJB
          AK2i7RlJEYo/Xa6mQmv9zmT0XUj3DcEhRJGPVw2qMyadUFxNg/ZFp7aTcToHMf00
          z6T3b7mwdBkCFQOL3Kb7WRcCAwEAAaM1MDMwDgYDVR0PAQH/BAQDAgWgMBMGA1Ud
          JQQMMAoGCCsGAQUFBwMBMAwGA1UdEwEB/wQCMAAwDQYJKoZIhvcNAQELBQADQQB8
          Of2iM7fPadmtChCMna8lYWH+lEplj6BxOJlRuGRawxszLwi78bnq0sCR33LU6xMx
          1oAPwIHNaJJwC4z6oG9E_DO_NOT_USE=
          -----END CERTIFICATE-----
          -----BEGIN CERTIFICATE-----
          MIIBWzCCAQWgAwIBAgIQYAKsXhJOXKfyySlmpKicTzANBgkqhkiG9w0BAQsFADAT
          MREwDwYDVQQKEwhBdXRoZWxpYTAeFw0yMzA0MjEwMDA3NDRaFw0yNDA0MjAwMDA3
          NDRaMBMxETAPBgNVBAoTCEF1dGhlbGlhMFwwDQYJKoZIhvcNAQEBBQADSwAwSAJB
          AK2i7RlJEYo/Xa6mQmv9zmT0XUj3DcEhRJGPVw2qMyadUFxNg/ZFp7aTcToHMf00
          z6T3b7mwdBkCFQOL3Kb7WRcCAwEAAaM1MDMwDgYDVR0PAQH/BAQDAgWgMBMGA1Ud
          JQQMMAoGCCsGAQUFBwMBMAwGA1UdEwEB/wQCMAAwDQYJKoZIhvcNAQELBQADQQB8
          Of2iM7fPadmtChCMna8lYWH+lEplj6BxOJlRuGRawxszLwi78bnq0sCR33LU6xMx
          1oAPwIHNaJJwC4z6oG9E_DO_NOT_USE=
          -----END CERTIFICATE-----          
    issuer_private_key: |
      -----BEGIN RSA PUBLIC KEY-----
      MEgCQQDAwV26ZA1lodtOQxNrJ491gWT+VzFum9IeZ+WTmMypYWyW1CzXKwsvTHDz
      9ec+jserR3EMQ0Rr24lj13FL1ib5AgMBAAE=
      -----END RSA PUBLIC KEY----      
    issuer_certificate_chain: |
      -----BEGIN CERTIFICATE-----
      MIIBWzCCAQWgAwIBAgIQYAKsXhJOXKfyySlmpKicTzANBgkqhkiG9w0BAQsFADAT
      MREwDwYDVQQKEwhBdXRoZWxpYTAeFw0yMzA0MjEwMDA3NDRaFw0yNDA0MjAwMDA3
      NDRaMBMxETAPBgNVBAoTCEF1dGhlbGlhMFwwDQYJKoZIhvcNAQEBBQADSwAwSAJB
      AK2i7RlJEYo/Xa6mQmv9zmT0XUj3DcEhRJGPVw2qMyadUFxNg/ZFp7aTcToHMf00
      z6T3b7mwdBkCFQOL3Kb7WRcCAwEAAaM1MDMwDgYDVR0PAQH/BAQDAgWgMBMGA1Ud
      JQQMMAoGCCsGAQUFBwMBMAwGA1UdEwEB/wQCMAAwDQYJKoZIhvcNAQELBQADQQB8
      Of2iM7fPadmtChCMna8lYWH+lEplj6BxOJlRuGRawxszLwi78bnq0sCR33LU6xMx
      1oAPwIHNaJJwC4z6oG9E_DO_NOT_USE=
      -----END CERTIFICATE-----
      -----BEGIN CERTIFICATE-----
      MIIBWzCCAQWgAwIBAgIQYAKsXhJOXKfyySlmpKicTzANBgkqhkiG9w0BAQsFADAT
      MREwDwYDVQQKEwhBdXRoZWxpYTAeFw0yMzA0MjEwMDA3NDRaFw0yNDA0MjAwMDA3
      NDRaMBMxETAPBgNVBAoTCEF1dGhlbGlhMFwwDQYJKoZIhvcNAQEBBQADSwAwSAJB
      AK2i7RlJEYo/Xa6mQmv9zmT0XUj3DcEhRJGPVw2qMyadUFxNg/ZFp7aTcToHMf00
      z6T3b7mwdBkCFQOL3Kb7WRcCAwEAAaM1MDMwDgYDVR0PAQH/BAQDAgWgMBMGA1Ud
      JQQMMAoGCCsGAQUFBwMBMAwGA1UdEwEB/wQCMAAwDQYJKoZIhvcNAQELBQADQQB8
      Of2iM7fPadmtChCMna8lYWH+lEplj6BxOJlRuGRawxszLwi78bnq0sCR33LU6xMx
      1oAPwIHNaJJwC4z6oG9E_DO_NOT_USE=
      -----END CERTIFICATE-----      
    access_token_lifespan: 1h
    authorize_code_lifespan: 1m
    id_token_lifespan: 1h
    refresh_token_lifespan: 90m
    enable_client_debug_messages: false
    minimum_parameter_entropy: 8
    enforce_pkce: public_clients_only
    enable_pkce_plain_challenge: false
    pushed_authorizations:
      enforce: false
      context_lifespan: 5m
    cors:
      endpoints:
        - authorization
        - token
        - revocation
        - introspection
      allowed_origins:
        - https://example.com
      allowed_origins_from_client_redirect_uris: false

Options

hmac_secret

{{< confkey type="string" required="yes" >}}

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.

issuer_private_keys

{{< confkey type="list(object" required="no" >}}

The list of JWKS instead of or in addition to the issuer_private_key and issuer_certificate_chain. Can also accept ECDSA Private Key's and Certificates.

The default key for each algorithm is 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_signing_alg ES256 and id_token_signing_key_id is not specified then the first ES256 key in this list is used.

key_id

{{< confkey type="string" default="" required="no" >}}

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 less characters, with a recommendation to use a length less than 10. 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:

The default if this value is omitted is the first 7 characters of the public key SHA256 thumbprint encoded into hexadecimal.

algorithm

{{< confkey type="string" default="RS256" required="no" >}}

The algorithm for this key. This value is automatically detected based on the type of key.

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.

use

{{< confkey type="string" default="sig" required="no" >}}

The key usage. Defaults to sig which is the only available option at this time.

key

{{< confkey type="string" required="yes" >}}

The private key associated with this key entry.

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 private key MUST:

  • Be a PEM block encoded in the DER base64 format (RFC4648).
  • Be one of:
    • An RSA key with a key size of at least 2048 bits.
    • An ECDSA private key with one of the P-256, P-384, or P-521 elliptical curves.

If the certificate_chain is provided the private key must include matching public key data for the first certificate in the chain.

certificate_chain

{{< confkey type="string" required="no" >}}

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.

issuer_private_key

{{< confkey type="string" required="yes" >}}

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.

This private key is automatically appended to the issuer_private_keys and assumed to be for the RS256 algorithm. If provided it is always the first key in this list. As such this key is assumed to be the default for RS256 if provided.

The issuer private key MUST:

  • Be a PEM block encoded in the DER base64 format (RFC4648).
  • Be an RSA private key:
    • With a key size of at least 2048 bits.

If the issuer_certificate_chain is provided the private key must include matching public key data for the first certificate in the chain.

issuer_certificate_chain

{{< confkey type="string" required="no" >}}

The certificate chain/bundle to be used with the issuer_private_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 issuer_private_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.

access_token_lifespan

{{< confkey type="duration" default="1h" required="no" >}}

The maximum lifetime of an access token. It's generally recommended keeping this short similar to the default. For more information read these docs about token lifespan.

authorize_code_lifespan

{{< confkey type="duration" default="1m" required="no" >}}

The maximum lifetime of an authorize code. This can be rather short, as the authorize code should only be needed to obtain the other token types. For more information read these docs about token lifespan.

id_token_lifespan

{{< confkey type="duration" default="1h" required="no" >}}

The maximum lifetime of an ID token. For more information read these docs about token lifespan.

refresh_token_lifespan

{{< confkey type="string" default="90m" required="no" >}}

The 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. For more information read these docs about token lifespan.

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, the authorize code 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.

enable_client_debug_messages

{{< confkey type="boolean" default="false" required="no" >}}

Allows additional debug messages to be sent to the clients.

minimum_parameter_entropy

{{< confkey type="integer" default="8" required="no" >}}

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.

enforce_pkce

{{< confkey type="string" default="public_clients_only" required="no" >}}

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

{{< confkey type="boolean" default="false" required="no" >}}

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.

pushed_authorizations

Controls the behaviour of Pushed Authorization Requests.

enforce

{{< confkey type="boolean" default="false" required="no" >}}

When enabled all authorization requests must use the Pushed Authorization Requests flow.

context_lifespan

{{< confkey type="duration" default="5m" required="no" >}}

The maximum amount of time between the Pushed Authorization Requests flow being initiated and the generated request_uri being utilized by a client.

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

{{< confkey type="list(string)" required="no" >}}

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

{{< confkey type="list(string)" required="no" >}}

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

{{< confkey type="boolean" default="false" required="no" >}}

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.