Skip to main content

Authelia OIDC Setup

This guide configures Authelia as an OpenID Connect provider for GeoPulse.

It uses these example values:

SettingExample value
GeoPulse URLhttps://geopulse.example.com
Authelia URLhttps://auth.example.com
Client IDgeopulse
GeoPulse callback URLhttps://geopulse.example.com/oidc/callback

Replace these values with your own domains before applying the configuration.

Prerequisites​

  • GeoPulse is reachable from the browser at its final public HTTPS URL.
  • Authelia is reachable at its final public HTTPS URL.
  • Authelia's OpenID Connect provider is enabled and configured.
  • GeoPulse can reach Authelia's discovery endpoint from the backend container: https://auth.example.com/.well-known/openid-configuration.

If you already have Authelia OIDC configured for other apps, do not replace your existing hmac_secret or jwks unless you intend to rotate them. Add the GeoPulse client and claims policy to the existing identity_providers.oidc section instead.

1. Generate Authelia Secrets​

Run these commands on the machine where you manage Authelia. The Docker examples use the official Authelia image so they also work before Authelia is running. If Authelia is installed directly on the host, remove the docker run --rm authelia/authelia:latest prefix.

If you already have a Docker Compose service named authelia, you can run the same Authelia commands with docker compose exec authelia authelia ... instead.

Generate the HMAC Secret​

Authelia uses hmac_secret to sign some OIDC values:

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

Copy the output into identity_providers.oidc.hmac_secret.

Generate the Client Secret Hash​

GeoPulse must store the plaintext client secret. Authelia should store the generated hash.

docker run --rm authelia/authelia:latest authelia crypto hash generate pbkdf2 \
--variant sha512 \
--random \
--random.length 72 \
--random.charset rfc3986

The command prints a random plaintext password and a PBKDF2 hash:

  • Copy the plaintext password into GeoPulse as the client secret.
  • Copy the $pbkdf2-sha512$... hash into Authelia as client_secret.
warning

Do not put the hashed value in GeoPulse. GeoPulse sends the plaintext secret to Authelia during the token exchange.

Generate the JWKS Private Key​

Authelia needs at least one signing key for OIDC tokens. This command writes private.pem and public.pem to a local folder:

mkdir -p authelia-oidc-keys
docker run --rm \
-u "$(id -u):$(id -g)" \
-v "$PWD/authelia-oidc-keys:/keys" \
authelia/authelia:latest authelia crypto pair rsa generate --directory /keys

Open authelia-oidc-keys/private.pem and copy the full private key into the Authelia jwks[].key field. Use the private key, not public.pem.

cat authelia-oidc-keys/private.pem

2. Configure Authelia​

Add or merge this into configuration.yml. Keep the indentation under your existing identity_providers.oidc section.

identity_providers:
oidc:
hmac_secret: "paste-the-generated-hmac-secret-here"

jwks:
- key_id: geopulse
algorithm: RS256
use: sig
key: |
-----BEGIN PRIVATE KEY-----
paste the full generated private.pem content here
-----END PRIVATE KEY-----

claims_policies:
geopulse:
id_token:
- email
- email_verified
- name
- preferred_username

clients:
- client_id: geopulse
client_name: GeoPulse
client_secret: "$pbkdf2-sha512$310000$replace-with-generated-hash"
public: false
authorization_policy: one_factor

redirect_uris:
- https://geopulse.example.com/oidc/callback

scopes:
- openid
- profile
- email

grant_types:
- authorization_code
response_types:
- code
response_modes:
- query

token_endpoint_auth_method: client_secret_post
claims_policy: geopulse
require_pkce: false

Replace these values in the example:

ValueReplace with
paste-the-generated-hmac-secret-hereThe hmac_secret value generated in step 1
The sample jwks[].key private key blockThe full contents of authelia-oidc-keys/private.pem, including the BEGIN PRIVATE KEY and END PRIVATE KEY lines
$pbkdf2-sha512$310000$replace-with-generated-hashThe PBKDF2 hash printed by the client secret command
https://geopulse.example.com/oidc/callbackYour exact GeoPulse callback URL
client_id: geopulseYour chosen client ID, if you do not use the example client ID. The GeoPulse Client ID must match.
one_factorYour preferred Authelia authorization policy, for example two_factor to require MFA

Use two_factor instead of one_factor if you want Authelia to require MFA for GeoPulse logins.

GeoPulse requires the email claim in the ID token. The claims_policy entry is important because scopes alone may not include all claims GeoPulse expects in the ID token.

require_pkce must be false because GeoPulse does not send a PKCE code_challenge or code_verifier in the OIDC authorization code flow.

Validate the Authelia configuration before restarting:

docker run --rm \
-v "$PWD/authelia:/config" \
authelia/authelia:latest authelia config validate --config /config/configuration.yml

For an existing Docker Compose deployment, you can usually run the same validation inside the Authelia service:

docker compose exec authelia authelia config validate --config /config/configuration.yml

Restart Authelia after validation succeeds.

3. Configure GeoPulse​

Configure GeoPulse with the Authelia discovery URL and the plaintext client secret generated in step 1.

Environment Variables​

GEOPULSE_OIDC_ENABLED=true
GEOPULSE_OIDC_CALLBACK_BASE_URL=https://geopulse.example.com

GEOPULSE_OIDC_PROVIDER_AUTHELIA_ENABLED=true
GEOPULSE_OIDC_PROVIDER_AUTHELIA_NAME=Authelia
GEOPULSE_OIDC_PROVIDER_AUTHELIA_CLIENT_ID=geopulse
GEOPULSE_OIDC_PROVIDER_AUTHELIA_CLIENT_SECRET=the-generated-plaintext-secret
GEOPULSE_OIDC_PROVIDER_AUTHELIA_DISCOVERY_URL=https://auth.example.com/.well-known/openid-configuration
GEOPULSE_OIDC_PROVIDER_AUTHELIA_ICON=https://cdn.jsdelivr.net/gh/selfhst/icons@main/svg/authelia-light.svg

Restart GeoPulse after changing environment variables.

Admin UI​

You can also configure Authelia in the GeoPulse Admin UI:

  1. Go to Admin Dashboard > OIDC Providers.
  2. Add a provider named authelia.
  3. Set the display name to Authelia.
  4. Set the client ID to geopulse.
  5. Set the client secret to the generated plaintext secret.
  6. Set the discovery URL to https://auth.example.com/.well-known/openid-configuration.
  7. Optionally set the icon URL to https://cdn.jsdelivr.net/gh/selfhst/icons@main/svg/authelia-light.svg.
  8. Use Test Connection, save the provider, and try logging in.

Troubleshooting​

Authelia returns invalid_client​

Make sure GeoPulse uses the plaintext client secret and Authelia uses the generated hash. Also confirm the Authelia client uses:

token_endpoint_auth_method: client_secret_post

If the secret contains characters that are being modified by your shell, environment file, or deployment tooling, regenerate it with a stricter charset:

docker run --rm authelia/authelia:latest authelia crypto hash generate pbkdf2 \
--variant sha512 \
--random \
--random.length 72 \
--random.charset alphanumeric

GeoPulse reports a callback error​

Check that the redirect URI in Authelia exactly matches the callback URL generated by GeoPulse:

https://geopulse.example.com/oidc/callback

For stable callbacks, set GEOPULSE_OIDC_CALLBACK_BASE_URL explicitly to the public GeoPulse URL without a trailing slash.

GeoPulse reports a missing email claim​

Confirm the Authelia client has claims_policy: geopulse and that the matching claims_policies.geopulse.id_token list includes email.

The Authelia icon does not appear​

The icon URL is optional:

https://cdn.jsdelivr.net/gh/selfhst/icons@main/svg/authelia-light.svg

If the browser cannot load the external SVG, GeoPulse falls back to the default sign-in icon.