> ## Documentation Index
> Fetch the complete documentation index at: https://docs.warnly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> This document describes how to configure authentication mechanisms for Warnly.

## OIDC

Warnly integrates with OIDC providers to authenticate users. Once configured, users can log in using their OIDC credentials, and Warnly will automatically create user accounts and manage access based on the configured settings.

### Configuration

To enable OIDC authentication, set the following environment variables:

| Property                | Description                                                           | Required |
| ----------------------- | --------------------------------------------------------------------- | -------- |
| OIDC\_PROVIDER\_NAME    | Name of the OIDC provider (e.g., 'google', 'keycloak')                | Yes      |
| OIDC\_ISSUER\_URL       | OIDC issuer URL                                                       | Yes      |
| OIDC\_CLIENT\_ID        | OIDC client ID                                                        | Yes      |
| OIDC\_CLIENT\_SECRET    | OIDC client secret                                                    | Yes      |
| OIDC\_REDIRECT\_ADDRESS | Public URL on which Warnly instance is reachable                      | Yes      |
| OIDC\_SCOPES            | Space-separated list of OIDC scopes (default: 'openid email profile') | No       |
| OIDC\_EMAIL\_MATCHES    | Space-separated list of email regex patterns for user filtering       | No       |
| OIDC\_USE\_PKCE         | Enable PKCE for OIDC authentication flow (default: true)              | No       |

### Callback URL

When configuring your OIDC provider, you need to set the callback URL to:

```
https://your-warnly-instance.com/oidc/{provider_name}/callback
```

Replace `{provider_name}` with the value of `OIDC_PROVIDER_NAME`.

### Email Matches

You can restrict access to specific users by configuring email patterns. Only users whose email addresses match the provided regular expressions will be allowed to authenticate.

For example, to allow only users with `@yourcompany.com` emails:

```bash theme={null}
OIDC_EMAIL_MATCHES=^.*@yourcompany\.com$
```

Multiple patterns can be separated by spaces.

### Example: OIDC with Keycloak

1. In your Keycloak admin console, create a new client
2. Set the client type to "OpenID Connect"
3. Configure the redirect URI: `https://your-warnly-instance.com/oidc/keycloak/callback`
4. Enable "Standard flow" and "Direct access grants"
5. Configure the following environment variables:

```bash theme={null}
OIDC_PROVIDER_NAME=keycloak
OIDC_ISSUER_URL=https://your-keycloak-instance.com/realms/your-realm
OIDC_CLIENT_ID=your-keycloak-client-id
OIDC_CLIENT_SECRET=your-keycloak-client-secret
OIDC_REDIRECT_ADDRESS=https://your-warnly-instance.com
OIDC_SCOPES="openid email profile"
```

### Troubleshooting

#### Common Issues

1. **Invalid redirect URI**: Ensure the callback URL in your OIDC provider matches the configured `OIDC_REDIRECT_ADDRESS` and provider name.

2. **Email not matching**: Check that the `email` scope is requested and the user's email matches the `OIDC_EMAIL_MATCHES` patterns.

3. **PKCE issues**: If your OIDC provider doesn't support PKCE, set `OIDC_USE_PKCE=false`.

4. **HTTPS required**: Some providers require HTTPS for the redirect URI. Ensure your Warnly instance is accessible over HTTPS.

#### Debugging

* Check the Warnly logs for OIDC-related errors
* Verify the OIDC issuer URL is accessible and returns valid OIDC configuration
* Ensure the client ID and secret are correct
* Test the OIDC flow manually using tools like [OIDC Debugger](https://oidcdebugger.com/)

Most standard OIDC providers should work, but may require specific configuration adjustments.