rauthy

OpenID Connect Single Sign-On Identity & Access Management

• Maintainer: @3wc, @dannygroenewegen
• 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>, uncomment the following envs:

   COMPOSE_FILE="$COMPOSE_FILE:compose.api.yml"
   SECRET_API_SECRET_VERSION=v1
   API_BASE64_ACCESS_RIGHTS=...
   API_KEY_NAME=bootstrap
   

2. Generate the secret:

   abra app secret generate <app> api_secret v1
   

3. When API_BASE64_ACCESS_RIGHTS and api_secret are set before first deployment, Rauthy will bootstrap an API key with the access rights as configured in API_BASE64_ACCESS_RIGHTS. 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_BASE64_ACCESS_RIGHTS 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> — Creates (or updates) a confidential OIDC client. The client body (per Rauthy's NewClientRequest/UpdateClientRequest) is read from the env var <CLIENT_ID>_CLIENTJSON (client ID uppercased, non-alphanumerics replaced by _), e.g.:

MYAPP_CLIENTJSON='{"name":"My App","confidential":true,"redirect_uris":["https://myapp.example.com/callback"]}' abra app cmd --local <app> create_client myapp

The JSON is passed as an env var, not an argument, because abra app cmd --local re-parses arguments through a shell, which corrupts JSON.

get_client_secret <client_id> — Prints an existing client's secret.

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

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

check_api — Readiness check: exits 0 once rauthy's authenticated admin API responds, 1 otherwise. Useful as an external readiness/health check for automated deployment tooling.

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. Create the OIDC client in rauthy, either:
   • a) via the Rauthy Admin WebUI, and get the client secret from there, or
   • b) via abra.sh:

     NEXTCLOUD_CLIENTJSON='{"name":"Nextcloud","confidential":true,"redirect_uris":["https://nextcloud.example.com/apps/user_oidc/code"],"flows_enabled":["authorization_code","refresh_token"]}' abra app cmd --local <app> create_client nextcloud
     abra app cmd --local <app> get_client_secret nextcloud
     

2. Store that value as Nextcloud's user_oidc client secret (e.g. abra app secret insert <nextcloud-app> user_oidc_secret v1, then deploy Nextcloud) and 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 from step 1

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.