nessi
f925009977
Add complete NexaMFA push MFA system with: - FastAPI backend with PostgreSQL, Redis, OIDC provider, and Prometheus metrics - React TypeScript admin console - Android Kotlin/Jetpack Compose app with biometric authentication - Docker Compose deployment configuration - Gitea CI workflow for backend, frontend, and Android builds - Environment configuration template with security settings - Documentation for security model, deployment
48 lines
1.7 KiB
Markdown
48 lines
1.7 KiB
Markdown
# 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.
|