# authentik Integration

NexaMFA acts as an OIDC provider that authentik can call as an external authentication source.

## NexaMFA Settings

Set:

```env
PUBLIC_BASE_URL=https://mfa.example.com
OIDC_ISSUER=https://mfa.example.com
OIDC_CLIENT_ID=authentik
OIDC_CLIENT_SECRET=generate-a-long-secret
OIDC_REDIRECT_URIS=https://authentik.example.com/application/o/nexamfa/callback/
```

The discovery URL is:

```text
https://mfa.example.com/.well-known/openid-configuration
```

## authentik Setup

1. In authentik, create an OAuth2/OIDC source or provider entry for NexaMFA.
2. Use the discovery URL above if your authentik flow supports discovery.
3. Set client ID to `authentik`.
4. Set client secret to `OIDC_CLIENT_SECRET`.
5. Set scopes to `openid profile email`.
6. Configure the redirect URI in NexaMFA and authentik to match exactly.
7. Ensure authentik sends the username as `login_hint` during `/oauth/authorize`.

## Flow

1. authentik redirects the browser to `/oauth/authorize`.
2. NexaMFA validates the client and redirect URI.
3. NexaMFA creates a challenge for the `login_hint` user and sends FCM push containing only `challenge_id`.
4. The browser waits on the NexaMFA approval page.
5. The Android app fetches challenge details, shows service, username, IP, timestamp, and location if present.
6. The user approves with biometric or device credential.
7. The Android app signs the canonical payload and posts approval.
8. NexaMFA issues an authorization code and redirects back to authentik.
9. authentik exchanges the code at `/oauth/token`.

## Zoraxy

Route `https://mfa.example.com` to `backend:8000` and keep HTTPS enabled. The OIDC issuer must exactly match the public HTTPS origin.