Skip to main content

Setup OIDC Guide for Beginners

 Authelia.png   GitHub-logo.png   logo (1).png

 

 

 

Overview

copyPlease take a look at how OIDC works here if you haven’t already: What is OIDC? 
This little Wiki Article will guide you through how to get OIDC running. In this example, we will set up OIDC with the service Linkwarden.

Requirements

Make sure you have the following set up:

  • Traefik as a Reverse Proxy to get certificates and provide access to your Website/Subdomains: Traefik Reverse Proxy.
  • Authelia as a Middleware/Addon for Traefik, already configured with a “Whoamisecure” test to ensure your Authelia is working before adding OIDC: Getting Started.

Step 1

Open your Authelia configuration file and edit it (in this example, we store it on a GlusterFS mount at /mnt/glustermount/data/authelia_data/config/configuration.yml):

nano /mnt/glustermount/data/authelia_data/config/configuration.yml

Step 2

Scroll to the bottom of your config file and add the following code:

identity_providers:
  oidc:
    hmac_secret: 'this_is_a_secret_abc123abc123abc'
    jwks:
     -  key_id: 'example'H5xqbY6Ji0lEZTU'
        algorithm: 'RS256'
        use: 'sig'
        key: |{{ -----BEGINsecret RSA PRIVATE KEY-----
          ...
          -----END RSA PRIVATE KEY-----          
        certificate_chain:"/secrets/rsa_2048_private.txt" | -----BEGINmindent CERTIFICATE-----10 ..."|" -----END| CERTIFICATE-----msquote -----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'1 hour'
      authorize_code: '1m'1 minute'
      id_token: '1h'1 hour'
      refresh_token: '90m'90 cors:minutes'
    endpoints:
        - 'authorization'
        - 'token'
        - 'revocation'
        - 'introspection'
      allowed_origins:
        - 'https://aeoneros.com'
      allowed_origins_from_client_redirect_uris:enable_client_debug_messages: false

Step 3

AdjustBy adding the identity_providers section, you enable OIDC in Authelia. All settings in that block belong to OIDC. Please note this is only the minimum required configuration for our setup. You can find more details here: Authelia OIDC Introduction.

HMAC:
HMAC_Secret

The HMAC Secret is a random string known only to Authelia. Do not make this public.

The HMAC secret is used to sign the JWT’s.. The providedThis string is hashed to a SHA256 (RFC6234) byte string for the purpose of meeting the required format.string.

It’s strongly recommended thisyou isuse a Randomrandom Alphanumericalphanumeric Stringstring with 64 or more characters.

Generate thea Keykey in Docker CLI:

docker run --rm authelia/authelia:latest authelia crypto rand --length 64 --charset alphanumeric

For Example:example: "rzUPr41040tMvw4tg95Ud2HdcvdDMVZPQQPpHAist386QajGftF4IlFSw0yi2gtD"

copy
Copy it to: hmac_secret: hmac_secret: 'this_is_a_secret_abc123abc123abc'

JWKs: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. CanYou also be used tocan configure manymultiple typeskeys ofor 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.algorithms. The first key for each algorithm is considered the default if a client is notisn’t configured to use a specific key id. For example if a client has id_token_signed_response_alg ES256key_id and id_token_signed_response_key_id is not specified then the first ES256 key in this list is used..

The followingBelow is a contextual example (see below for information regarding each option):example:

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

RFC Internet Standard:
RFC (Request for Comments) documents define internet standards, protocols, and best practices. For example, RFC7519 outlines how JSON Web Tokens should be structured and validated, ensuring a standard approach to token-based authentication.

KeyID:KeyID

CompletelyThis optional,is andcompletely generally discouragedoptional unless there isthere’s a collision between the automatically generated key id’s.IDs. If providedprovided, it must be a unique string with fewer than 100 or fewer characters, with a recommendation to use a length less than 15. In addition, it must meet the following rules:

  • Matchmatching 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 encodedin into hexadecimal,hex, followed by a hyphen, then followed by the lowercase algorithm value.

docker run --rm authelia/authelia:latest authelia crypto rand --length 15 --charset alphanumeric

For Example:example: "H5xqbY6Ji0lEZTU"

Use:Use

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

algorithm:Algorithm

The algorithm for this key. ThisTypically value typically optionaloptional, as it can be automatically detected based on the type of keykey. 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 RSA256RS256 key must be provided.

key:Key

The Authelia docker container or CLI binaryYou can be used to generate an RSA keypair.keypair using the Authelia Docker container:

docker run --rm -u "$(id -u):$(id -g)" -v "$(pwd)":/keys authelia/authelia:latest authelia crypto pair rsa generate --directory /keys

assumingAssuming your working directory wouldis be "/mnt/glustermount/data/authelia_data/config", you’ll end up with private.pem and public.pem.

nowThen, youplace wantprivate.pem yoursomewhere keypairlike: to be saved at: "/mnt/glustermount/data/authelia_data/config/secrets/oidc/jwks/rsa.2048.keyrsa_2048_private.txt"

Create folders forif the files:necessary:

mkdir /mnt/glustermount/data/authelia_data/config/secrets
mkdir

Open private.pem, copy the content:

-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----

And paste it into a new file:

nano /mnt/glustermount/data/authelia_data/config/secrets/oidc
mkdir /mnt/glustermount/data/authelia_data/config/secrets/oidc/jwks

rsa_2048_private.txt

ChangeSave directorywith to: "/mnt/glustermount/data/authelia_data/config/secrets/oidc/jwks"CTRL+O and exectureexit with CTRL+X.

Step 4

Add Clients/Services to OIDC. Here is an example on how to add Linkwarden: Setup OIDC for Linkwarden.

Conclusion

With the dockerabove runconfiguration, commandAuthelia providedcan abovefunction as an OIDC provider, signing JWT tokens for your clients or services (like Linkwarden). Make sure to createcorrectly configure your OIDC clients with the RSAsame keypair.

settings

(client IDs, secrets, scopes) to ensure smooth authentication. Once you’ve confirmed it’s working with a test service, you nowcan gotreuse private.pemthese public.pemsteps for additional applications that support OIDC.

Back to top