### Authorization Header Example

Source: https://sebadob.github.io/rauthy/config/logging.html

An example of how to format the Authorization header when accessing the events stream.

```http
Authorization: API-Key events$SUcpBxcPmfwH9z1Kb4ExOUYDSXpxOj9mFLadjuQ1049XaWzdWB328aa97k2nj21E
```

--------------------------------

### Rauthy Encryption Keys Configuration Example

Source: https://sebadob.github.io/rauthy/config/encryption.html

Example of how to structure the `encryption.keys` in your configuration file, including multiple keys.

```ini
[encryption]
key = [
  "Wx1zrbLF/5vTaB7LdUSg1aTecmqHJOu2+RnU6zgTwNkDQU52Y3JM=",
  "6uf5QebA/9DsKMoq8A+Gn2WQrTcSpz5sg751yYs3IJlkw3dn0rII=",
]

```

--------------------------------

### Example Encryption Configuration

Source: https://sebadob.github.io/rauthy/getting_started/k8s.html

Illustrates how to structure the encryption keys in the configuration file. 'key_active' should be the first part of the generated key string before the '/'.

```ini
[encryption]
keys = ["XLCcaQ/f2xmq/nxVFgJN0CN311miyvVlBxXOQISyw1nPEPOqiI="]
key_active = "XLCcaQ"
```

--------------------------------

### Bootstrap API Key Example

Source: https://sebadob.github.io/rauthy/config/config.html

Example JSON structure for creating a bootstrap API key. This key is used for initial database setup and requires specific fields like name, expiration, and access rights.

```json
{
    "name": "bootstrap",
    "exp": 1735599600,
    "access": [
        {
            "group": "Clients",
            "access_rights": [
                "read",
                "create",
                "update",
                "delete"
            ]
        },
        {
            "group": "Roles",
            "access_rights": [
                "read",
                "create",
                "update",
                "delete"
            ]
        },
        {
            "group": "Groups",
            "access_rights": [
                "read",
                "create",
                "update",
                "delete"
            ]
        }
    ]
}
```

--------------------------------

### Example Ephemeral Client JSON

Source: https://sebadob.github.io/rauthy/work/ephemeral_clients.html

A complete JSON example demonstrating all possible fields for an ephemeral client document. This format is used by Rauthy when fetching client configurations.

```json
{
  "client_id": "https://example.com/my_ephemeral_client.json",
  "client_name": "My Ephemeral Client",
  "client_uri": "https://this.is.where",
  "contacts": [
    "mail@ephemeral.info"
  ],
  "redirect_uris": [
    "https://this.is.where/my/website/is"
  ],
  "post_logout_redirect_uris": [
    "https://this.is.where"
  ],
  "default_max_age": 300,
  "scope": "openid email custom",
  "require_auth_time": true,
  "access_token_signed_response_alg": "RS256",
  "id_token_signed_response_alg": "RS256"
}
```

--------------------------------

### Serve Rauthy with Generated Configuration

Source: https://sebadob.github.io/rauthy/getting_started/docker.html

Starts the Rauthy server using the generated configuration file. Ensure any custom TLS certificates are in place if configured.

```bash
rauthy serve -c data/config-generated.toml
```

--------------------------------

### Example Rauthy Encryption Configuration

Source: https://sebadob.github.io/rauthy/config/encryption.html

Example configuration for Rauthy's encryption settings. It includes a list of encryption keys and specifies the currently active key.

```ini
[encryption]
keys = ["90eb6d69/U9wZG4GS/94pVh6iTH1ijf+kj+tXJHKkQNsp5eImMQI="]
key_active = "90eb6d69"
```

--------------------------------

### Example JSON Event Output

Source: https://sebadob.github.io/rauthy/config/logging.html

This is an example of the JSON output you might receive when querying for events.

```json
{
  "name": "events",
  "created": 1720428190,
  "expires": null,
  "access": [
    {
      "group": "Events",
      "access_rights": [
        "read"
      ]
    }
  ]
}
```

--------------------------------

### Start Docker Compose Services

Source: https://sebadob.github.io/rauthy/getting_started/docker.html

Starts the services defined in the docker-compose.yaml file in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Example API Key Authentication Header

Source: https://sebadob.github.io/rauthy/work/api_keys.html

An example of a correctly formatted Authorization header using a sample API Key. This format is automatically generated by the Rauthy Admin UI.

```http
Authorization: API-Key my_key$twUA2M7RZ8H3FyJHbti2AcMADPDCxDqUKbvi8FDnm3nYidwQx57Wfv6iaVTQynMh
```

--------------------------------

### SCIM Sync Flow Example

Source: https://sebadob.github.io/rauthy/print.html

This section outlines the typical SCIM v2 sync flow when adding SCIM v2 to a client, involving user and group synchronization.

```APIDOC
## SCIM Sync Flow

### Description
This describes the SCIM v2 sync flow, particularly when adding SCIM v2 to a client, which triggers a complete sync. This flow involves user and group synchronization steps.

### Sync Steps

1.  **User Synchronization**:
    *   `GET {base_url}/Users` is called, initially with `filter=externalId`. If no user is found, it retries with `filter=userName`.
    *   **User Handling**: 
        *   If the user exists but should not be synced (e.g., due to group prefix filter), `DELETE {base_url}/Users/{id}` is called (if `scim.sync_delete_users` is enabled).
        *   If the user does not exist on the client, `POST {base_url}/Users` is called to create the new user.
        *   If the user was found via `GET`, all values are updated, ensuring `externalId` is set correctly. If found by `userName`, `externalId` is also updated.

2.  **Group Synchronization**:
    *   This step is performed only if Rauthy is configured to sync groups for the client.
    *   `GET {base_url}/Groups` is called, optionally with `filter=externalId` or `filter=displayName`.
    *   Remote groups are compared against Rauthy's group assignments.
    *   Groups are deleted on the remote side only if they have a matching `externalId` and are marked for deletion in Rauthy's configuration (`scim.sync_delete_groups`).
    *   If groups should exist remotely but don't, `POST {base_url}/Groups` is called to create them.
    *   If a group match is found by `externalId` but the name is outdated, `PATCH {base_url}/Groups/{id}` is used to update the group name.

3.  **Group Membership Synchronization**:
    *   Once users and groups are synchronized, membership assignments are verified.
    *   `PatchOp` operations are used with `PATCH {base_url}/Groups/{id}` to adjust group memberships.

### Group Name Update

- If a group's name is updated, Rauthy performs a `PATCH {base_url}/Groups/{id}` with the `replace` operation to update the group's name or `externalId`.

### Info on Deletion Flags

- If `scim.sync_delete_groups` or `scim.sync_delete_users` is disabled, Rauthy will not delete resources on the remote system. Instead, it will remove the `externalId` value from the resource in Rauthy, indicating that the resource is no longer managed by Rauthy. This is useful for preserving data linked to resources that are no longer active.
```

--------------------------------

### Set Active Encryption Key Configuration

Source: https://sebadob.github.io/rauthy/config/encryption.html

Example of setting the `key_active` parameter to specify the default encryption key ID.

```ini
[encryption]
key_active = "Wx1zrbLF"

```

--------------------------------

### Run Rauthy with Docker

Source: https://sebadob.github.io/rauthy/getting_started/docker.html

Starts Rauthy on localhost using a Docker image with a basic default configuration for local testing. Do not use this configuration in production as it contains hardcoded secrets. The LOCAL_TEST=true environment variable restricts functionality to localhost.

```bash
docker run -it --rm -e LOCAL_TEST=true -p 8443:8443 ghcr.io/sebadob/rauthy:0.35.1
```

--------------------------------

### Construct Registration URL with Redirect Hint

Source: https://sebadob.github.io/rauthy/config/user_reg.html

Append the `redirect_uri` query parameter to the Rauthy registration URL to guide users back to your application after registration or password reset.

```url
https://iam.example.com/auth/v1/users/register?redirect_uri=https%3A%2F%2Fgithub.com
```

--------------------------------

### API Key Bootstrap Configuration

Source: https://sebadob.github.io/rauthy/config/bootstrap.html

Configuration section for bootstrapping an API key during initial production database setup. The key must be base64 encoded JSON matching the specified structure. Refer to `api_key_example.json` for a template.

```toml
[bootstrap]
# You can provide an API Key during the initial prod database
# bootstrap. This key must match the format and pass validation.
# You need to provide it as a base64 encoded JSON in the format:
#
# ```
# struct ApiKeyRequest {
#     /// Validation: `^[a-zA-Z0-9_-/]{2,24}$`
#     name: String,
#     /// Unix timestamp in seconds in the future (max year 2099)
#     exp: Option<i64>,
#     access: Vec<ApiKeyAccess>,
# }
#
# struct ApiKeyAccess {
#     group: AccessGroup,
#     access_rights: Vec<AccessRights>,
# }
#
# enum AccessGroup {
#     Blacklist,
#     Clients,
#     Events,
#     Generic,
#     Groups,
#     Roles,
#     Secrets,
#     Sessions,
#     Scopes,
#     UserAttributes,
#     Users,
# }
#
# #[serde(rename_all="lowercase")]
# enum AccessRights {
#     Read,
#     Create,
#     Update,
#     Delete,
# }
# ```
#
# You can use the `api_key_example.json` from `/` as
# an example. Afterward, just
# `base64 api_key_example.json | tr -d '\n'`
#

```

--------------------------------

### Example JSON for API Key Bootstrap

Source: https://sebadob.github.io/rauthy/config/bootstrap.html

Defines a JSON structure for creating an API key with specific access rights to clients, roles, and groups. This JSON should be base64 encoded when provided for bootstrapping.

```json
{
  "name": "bootstrap",
  "exp": 1735599600,
  "access": [
    {
      "group": "Clients",
      "access_rights": [
        "read",
        "create",
        "update",
        "delete"
      ]
    },
    {
      "group": "Roles",
      "access_rights": [
        "read",
        "create",
        "update",
        "delete"
      ]
    },
    {
      "group": "Groups",
      "access_rights": [
        "read",
        "create",
        "update",
        "delete"
      ]
    }
  ]
}
```

--------------------------------

### Set Up Data Directory for Rauthy CLI

Source: https://sebadob.github.io/rauthy/getting_started/k8s.html

Creates a 'data' directory and sets ownership to user ID 10001 and the current group. This is necessary because the Rauthy binary inside the container runs with these IDs and needs write access to this directory.

```bash
mkdir data && sudo chown 10001:$(id -g) data
```

--------------------------------

### Configure Rauthy Start Event Level

Source: https://sebadob.github.io/rauthy/config/logging.html

Set the event level when a Rauthy instance is started. The default level is 'info'.

```ini
# The level for the generated Event after a Rauthy
# instance has been started
#
# default: info
# overwritten by: EVENT_LEVEL_RAUTHY_START
level_rauthy_start = 'info'
```

--------------------------------

### Ephemeral Client ID Example

Source: https://sebadob.github.io/rauthy/work/ephemeral_clients.html

The client_id for an ephemeral client must exactly match the URI of its JSON configuration document. This example shows the required format.

```json
"client_id": "https://github.com/sebadob/rauthy/blob/main/ephemeral_client_example.json"
```

--------------------------------

### Create Rauthy Service Configuration File

Source: https://sebadob.github.io/rauthy/print.html

Use this command to create the `sts.yaml` file for Rauthy service configuration.

```bash
touch sts.yaml
```

--------------------------------

### Enable Open User Registration

Source: https://sebadob.github.io/rauthy/print.html

Allows anyone to register for a new user account without requiring admin intervention. Ensure email sending is configured if this is enabled.

```toml
[user_registration]
enable = true
```

--------------------------------

### Apply Kubernetes Manifests

Source: https://sebadob.github.io/rauthy/getting_started/k8s.html

Command to apply all Kubernetes configuration files in the current directory.

```bash
kubectl apply -f .

```

--------------------------------

### Run Rauthy CLI Help

Source: https://sebadob.github.io/rauthy/print.html

Execute this command to view the help information for the Rauthy CLI. This is useful for understanding available commands and options.

```bash
cargo run -- --help
```

```bash
rauthy --help
```

```bash
./rauthy --help
```

--------------------------------

### Example JWT Token with Custom Claim

Source: https://sebadob.github.io/rauthy/work/custom_scopes_attributes.html

This JSON represents an example JWT token that includes a custom user attribute ('my_attr') within the 'custom' section. This is the expected output after successfully configuring custom scopes and attributes.

```json
{
  "iat": 1721722389,
  "exp": 1721722399,
  "nbf": 1721722389,
  "iss": "http://localhost:8080/auth/v1",
  "sub": "za9UxpH7XVxqrtpEbThoqvn2",
  "aud": "rauthy",
  "nonce": "Fars0wPqrm9f6XimDKD08CPl",
  "azp": "rauthy",
  "typ": "Id",
  "amr": [
    "pwd"
  ],
  "auth_time": 1721722389,
  "at_hash": "Hd5ugcSzxwl1epF7Il3pEpq0gznnqs2SnSVZCdNw0EI",
  "preferred_username": "admin@localhost",
  "roles": [
    "rauthy_admin",
    "admin"
  ],
  "custom": {
    "my_attr": "This is Batman!"
  }
}
```

--------------------------------

### Display Nioca X509 Help

Source: https://sebadob.github.io/rauthy/config/tls.html

Run this command to view the full feature set and customization options for the Nioca x509 command-line tool.

```bash
nioca x509 -h
```

--------------------------------

### Display Generated Configuration

Source: https://sebadob.github.io/rauthy/print.html

Prints the content of the generated configuration file using sudo, as it may have restricted permissions.

```bash
sudo cat data/config-generated.toml
```

--------------------------------

### Authorization Header Format

Source: https://sebadob.github.io/rauthy/config/bootstrap.html

Example of how to format the Authorization header using the API key name and its secret. This format is required for authenticating requests.

```http
Authorization: API-Key <API Key name>$<API Key secret>
```

```http
Authorization: API-Key bootstrap$twUA2M7RZ8H3FyJHbti2AcMADPDCxDqUKbvi8FDnm3nYidwQx57Wfv6iaVTQynMh
```

--------------------------------

### Enable Swagger UI

Source: https://sebadob.github.io/rauthy/print.html

Set `swagger_ui_enable` to `true` to enable the Swagger UI. This will consume approximately 13MB of additional memory and is initialized at application start.

```ini
[server]
# Can be set to `true` to enable the Swagger UI.
# This will consume ~13mb of additional memory.
#
# default: false
# overwritten by: SWAGGER_UI_ENABLE
swagger_ui_enable = false

```

--------------------------------

### Enable Swagger UI

Source: https://sebadob.github.io/rauthy/config/tuning.html

Set `swagger_ui_enable` to `true` to enable the Swagger UI for API documentation. This consumes approximately 13MB of additional memory and is initialized at startup if enabled.

```toml
[server]
swagger_ui_enable = false
```

--------------------------------

### Monitor Rauthy Docker Logs

Source: https://sebadob.github.io/rauthy/print.html

Command to stream logs from the Rauthy Docker container in real-time. Useful for observing initial setup and password generation.

```bash
docker logs -f rauthy

```

--------------------------------

### Bootstrap Directory Configuration

Source: https://sebadob.github.io/rauthy/config/bootstrap.html

Configure the directory where Rauthy will look for additional bootstrapping data in JSON format. This allows for bootstrapping entities like roles, groups, users, and clients.

```toml
bootstrap_dir = 'bootstrap'
```

--------------------------------

### Create Rauthy Data and TLS Directories

Source: https://sebadob.github.io/rauthy/getting_started/docker.html

Creates necessary directories for Rauthy's persistent data and TLS certificates. Ensure these directories exist before proceeding with configuration.

```bash
mkdir -p rauthy/data rauthy/tls
```

--------------------------------

### Configure IngressRoute with TLS Secret

Source: https://sebadob.github.io/rauthy/getting_started/k8s.html

Example of an IngressRoute that includes TLS configuration, referencing a Kubernetes secret for the certificate. Replace `secret-name-of-your-tls-certificate` with the actual secret name.

```yaml
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: rauthy-https
  namespace: rauthy
spec:
  entryPoints:
    - websecure
  tls:
    # Paste the name of the TLS secret here
    secretName: secret-name-of-your-tls-certificate
  routes:
    - match: Host(`auth.example.com`)
      kind: Rule
      services:
        - name: rauthy
          port: 8080

```

--------------------------------

### TOML Configuration for Rauthy Cluster Node ID

Source: https://sebadob.github.io/rauthy/print.html

Example TOML configuration snippet for setting the Rauthy cluster node ID. This is mandatory even for single-node deployments.

```toml
[cluster]

```

--------------------------------

### View Docker Logs

Source: https://sebadob.github.io/rauthy/getting_started/first_start.html

Use this command to view the logs of a running Rauthy container in Docker. This is useful for retrieving the initial admin password generated on the first start.

```bash
docker logs -f rauthy
```

--------------------------------

### Verify Rauthy CLI Access

Source: https://sebadob.github.io/rauthy/getting_started/docker.html

Tests if the Rauthy CLI is accessible and working correctly by running the --help command. This confirms the Docker alias and container setup.

```bash
rauthy --help
```

--------------------------------

### Set up Rauthy Docker Alias

Source: https://sebadob.github.io/rauthy/config/cli.html

This alias simplifies running Rauthy commands via Docker. It allows for easy access to the CLI without direct binary installation.

```bash
alias rauthy='docker run -it --rm ghcr.io/sebadob/rauthy'
```

--------------------------------

### Verify Generated Certificate Files

Source: https://sebadob.github.io/rauthy/print.html

List the files in the current directory to confirm that the `ca-chain.pem`, `cert-chain.pem`, and `key.pem` files have been successfully copied.

```bash
ca-chain.pem
cert-chain.pem
key.pem

```

--------------------------------

### Generate Random Base64 String using openssl

Source: https://sebadob.github.io/rauthy/getting_started/k8s.html

Generates a random base64 encoded string of a specified length (48 bytes in this example) using openssl, suitable for secrets.

```bash
openssl rand -base64 48
```