# Utils

Helper scripts for configuring SSO and other integrations across Co-op Cloud recipes.

All scripts use stdlib only (no pip dependencies) and share `authentik_client.py` for Authentik API interactions.

## Getting an Authentik API Token

All SSO setup scripts require an `--authentik-token`. You can create one from your `akadmin` password in several ways:

**Via curl:**

```bash
curl -s -X POST https://<authentik-domain>/api/v3/core/tokens/ \
  -H "Content-Type: application/json" \
  -u "akadmin:<your-akadmin-password>" \
  -d '{"identifier": "sso-setup", "intent": "api", "description": "Token for SSO setup scripts"}'
```

The response JSON contains a `key` field — that's your token.

To retrieve an existing token's key:

```bash
curl -s https://<authentik-domain>/api/v3/core/tokens/sso-setup/view_key/ \
  -u "akadmin:<your-akadmin-password>"
```

**Via the Authentik admin UI:**

Go to **Directory > Tokens and App passwords > Create**, set intent to "API Token", then copy the token value.

## Prerequisites

The target abra apps (CryptPad, Immich, etc.) **must already be deployed** before running the SSO setup scripts. The scripts will fail with a clear error if the app is not found. Authentik resources (OAuth2 providers, applications) are created automatically if they don't exist.

## Scripts

### setup_cryptpad_sso.py

Configures Authentik as the OIDC provider for CryptPad SSO. Ensures the OAuth2 provider/application exist in Authentik, updates the CryptPad abra `.env` file, and inserts the client secret as a Docker secret. Requires the CryptPad abra app to already exist.

```bash
python3 utils/setup_cryptpad_sso.py \
  --authentik-domain auth.example.com \
  --authentik-token <admin-api-token> \
  --cryptpad-domain pad.example.com
```

Optional flags: `--client-id`, `--app-slug`, `--test-user`, `--test-pass`, `--test-email`, `--no-test-user`.

### setup_immich_sso.py

Configures Authentik as the OIDC provider for Immich OAuth. Ensures the OAuth2 provider/application exist in Authentik, then configures Immich OAuth settings via its REST API. Requires Immich to already be deployed and reachable.

```bash
python3 utils/setup_immich_sso.py \
  --authentik-domain auth.example.com \
  --authentik-token <admin-api-token> \
  --immich-domain photos.example.com \
  --immich-admin-email admin@example.com \
  --immich-admin-pass <password>
```