# rauthy

> OpenID Connect Single Sign-On Identity & Access Management

<!-- metadata -->

* **Maintainer**: [@3wc](https://git.coopcloud.tech/3wordchant), [@decentral1se](https://git.coopcloud.tech/decentral1se)
* **Category**: Apps
* **Status**: 0
* **Image**: [`rauthy`](https://ghcr.io/sebadob/rauthy), 4, upstream
* **Healthcheck**: No
* **Backups**: No
* **Email**: No
* **Tests**: No
* **SSO**: No

<!-- endmetadata -->

## 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`](https://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](https://sebadob.github.io/rauthy/config/bootstrap.html#api-key) 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](https://git.coopcloud.tech/coop-cloud/nextcloud#how-do-i-enable-openid-connect-oidc-providers)) 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](https://sebadob.github.io/rauthy/config/encryption.html). 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)"`
2. Change `ENC_KEY_ACTIVE="a1"` to `b2` (this tells rauthy to encrypt new secrets with the new key while still having access to `a1`)
3. `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.