rauthy

OpenID Connect Single Sign-On Identity & Access Management

• Maintainer: @3wc, @decentral1se
• Category: Apps
• Status: 0
• Image: rauthy, 4, upstream
• Healthcheck: No
• Backups: No
• Email: No
• Tests: No
• SSO: No

Quick start

1. abra app new rauthy
2. abra app cmd --local <app> generate_enc_keys
3. abra app secret generate <app> --all
4. abra app deploy <app>
5. abra app logs <app>
   • You'll see the automatically generated admin password in the initial logs. Ensure that you reset this password after you log in. The ADMIN_EMAIL env var controls the value of the admin login username.

For more, see docs.coopcloud.tech.

Host mode networking

You'll want to enable this in your Traefik configuration to avoid getting mistakenly rate limited based on internal ipv4 addresses (e.g. 10.0.0.6).

COMPOSE_FILE="$COMPOSE_FILE:compose.host.yml"

Bootstrap admin password

By default, rauthy generates a random admin password and prints it to the logs on first deploy. If you want to set a known password upfront, you can bootstrap it before the first deploy.

Requires argon2 on your local machine.

1. With abra app config <app>, configure the following envs:

   COMPOSE_FILE="$COMPOSE_FILE:compose.bootstrapadmin.yml"
   SECRET_ADMIN_PWHASH_VERSION=v1
   

2. Generate and insert the admin password hash:

   abra app cmd --local <app> generate_bootstrap_admin_password
   

3. Deploy: abra app deploy <app>

Rauthy will use the bootstrapped hash instead of generating a password.

API key

The API key allows access to the Rauthy API, used for creating OIDC clients, groups, and roles.

Setup

1. With abra app config <app>, configure the following envs:

   COMPOSE_FILE="$COMPOSE_FILE:compose.api.yml"
   SECRET_API_SECRET_VERSION=v1
   

2. Generate the secret:

   abra app secret generate <app> api_secret v1
   

3. When API_KEY and api_secret are set before first deployment, Rauthy will bootstrap an API key with the access rights as configured in API_KEY. The default value in .env.sample grants read and create rights on Clients, Roles, and Groups. See the rauthy bootstrap docs for the JSON schema. If API_KEY is empty or set after first deployment, no API key is bootstrapped and you'll need to create one manually in the admin UI with secret api_secret to be used by the abra.sh functions.

Available commands

All commands require the API key to be set up and the app to be running.

create_client <client_id> [insertsecret] — Creates a confidential OIDC client. Reads configuration from env vars prefixed with the uppercased client ID:

Variable	Required	Default
<ID>_CLIENT_NAME	yes	—
<ID>_REDIRECT_URI	yes	—
<ID>_ALLOWED_SCOPES	no	email openid profile groups

Without insertsecret, prints the generated client secret. With insertsecret, it inserts Rauthy's client secret in the app secret <ID>_sec (undeploying and redeploying the app automatically).

create_groups <group> [<group> ...] — Creates one or more groups.

create_roles <role> [<role> ...] — Creates one or more roles.

Example: Nextcloud OIDC integration

This sets up rauthy as an OIDC provider for a Nextcloud app. Requires the API key to be set up first.

1. With abra app config <app>, configure the following envs:

   COMPOSE_FILE="$COMPOSE_FILE:compose.nextcloud.yml"
   SECRET_NEXTCLOUD_SEC_VERSION=v1
   NEXTCLOUD_CLIENT_NAME="Nextcloud"
   NEXTCLOUD_REDIRECT_URI="https://nextcloud.example.com/apps/user_oidc/code"
   

2. Generate a placeholder secret (required before deploy; it will be replaced after client creation):

   abra app secret generate <app> nextcloud_sec v1
   

3. Deploy: abra app deploy <app>
4. Create the OIDC client in rauthy and insert the generated client secret:

   abra app cmd <app> create_client nextcloud insertsecret
   

   This undeploys the app, replaces the nextcloud_sec Docker secret with the real client secret, and redeploys.
5. Configure Nextcloud's OIDC provider (via the user_oidc app, see Nextcloud user_oidc docs) with:
   • Discovery endpoint: https://<rauthy-domain>/.well-known/openid-configuration
   • Client ID: nextcloud
   • Client secret: the value inserted above (can also be view in Rauthy Admin UI)

Encryption key rotation

This recipe supports encryption key rotation as described in the docs. To rotate keys the first time:

1. Increment the version of SECRET_ENC_KEYS_B_VERSION=b1 to b2
2. abra app secret insert <app> enc_keys_b b2 "$(openssl rand -base64 32)"
3. Change ENC_KEY_ACTIVE="a1" to b2 (this tells rauthy to encrypt new secrets with the new key while still having access to a1)
4. abra app deploy <app>

To rotate keys any future time, follow the same pattern of incrementing the non-active secret version and changing the active secret to that newly generated secret.