mirror of
https://github.com/joaovitoriasilva/endurain.git
synced 2026-01-07 23:13:57 -05:00
Revise and expand SSO documentation, update nav
Replaces the old 'Single-sign-on' doc with a new, comprehensive 'single-sign-on.md' covering SSO setup for multiple providers, troubleshooting, and security. Updates mkdocs.yml to reference the new file, enhance navigation, and enable additional markdown extensions and icons for improved documentation formatting.
This commit is contained in:
João Vitória Silva
@@ -1,40 +0,0 @@
|
||||
Instructions for SSO with Pocket ID
|
||||
|
||||
Note that if you already have a login on Endurain, the email address must match that with your SSO account otherwise Endurain will create a new user with the SSO email address.
|
||||
You'll need the FQDN of your OIDC provier and of your Endurain installation.
|
||||
|
||||
Log into Pocket ID and head to "Administration" and "OIDC Clients"
|
||||
Select "Add OIDC client"
|
||||
Name - "Endurain"
|
||||
Client Launch URL - the FQDN of your installation of Endurain e.g. https://endurain.mydomain.com
|
||||
Callback URLS - https://endurain.mydomain.com/api/v1/public/idp/callback/pocket-id
|
||||
|
||||
Click save and make a note of your Client ID and Secret.
|
||||
|
||||
In Endurain, head over to "Settings" and "Identity Providers". Select "Add Identity Provider" and "Custom"
|
||||
Provider Name: Pocket ID
|
||||
Slug: pocket-id
|
||||
Provider Type: OIDC
|
||||
Issuer URL: the FQDN of your Pocket ID instance (no trailing /)
|
||||
Client ID: from above
|
||||
Client secret: from above
|
||||
Scopes: openid profile email
|
||||
|
||||
|
||||
|
||||
Instructions for SSO with Tailscale TSIDP
|
||||
|
||||
Log into your instance of TSIDP and select "Add new client"
|
||||
Client Name: "Endurain"
|
||||
Redirect URIs: https://endurain.mydomain.com/api/v1/public/idp/callback/tsidp
|
||||
|
||||
Click "create client" and make a note of the client ID and secret.
|
||||
|
||||
In Endurain, head over to "Settings" and "Identity Providers". Select "Add Identity Provider" and "Custom"
|
||||
Provider Name: TSIDP
|
||||
Slug: tsidp
|
||||
Provider Type: OIDC
|
||||
Issuer URL: the FQDN of your Pocket ID instance (no trailing /)
|
||||
Client ID: from above
|
||||
Client secret: from above
|
||||
Scopes: openid profile email
|
||||
204
docs/features/single-sign-on.md
Normal file
204
docs/features/single-sign-on.md
Normal file
@@ -0,0 +1,204 @@
|
||||
# Single Sign-On (SSO) Configuration
|
||||
|
||||
Endurain supports Single Sign-On (SSO) integration through OAuth 2.0 and OpenID Connect (OIDC) protocols. This allows users to authenticate using their existing identity provider accounts.
|
||||
|
||||
## Important Notes
|
||||
|
||||
!!! warning "Email Address Matching"
|
||||
If you already have an existing Endurain account, the email address in your SSO provider **must match** your Endurain account email. If the email addresses don't match, Endurain will create a new user account with the SSO email address.
|
||||
|
||||
!!! tip "Requirements"
|
||||
You'll need:
|
||||
|
||||
- The fully qualified domain name (FQDN) of your OIDC provider
|
||||
- The FQDN of your Endurain installation
|
||||
- Administrator access to both your identity provider and Endurain
|
||||
|
||||
## Supported Identity Providers
|
||||
|
||||
Endurain provides built-in support for the following identity providers:
|
||||
|
||||
- **Authelia**
|
||||
- **Authentik**
|
||||
- **Casdoor**
|
||||
- **Keycloak**
|
||||
- **Pocket ID**
|
||||
|
||||
The system also supports custom OIDC providers including:
|
||||
|
||||
- Google
|
||||
- GitHub
|
||||
- Microsoft Entra ID
|
||||
- Any other OIDC-compliant provider
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
### Pocket ID
|
||||
|
||||
Pocket ID is a lightweight, self-hosted identity provider that works seamlessly with Endurain.
|
||||
|
||||
#### Step 1: Configure Pocket ID
|
||||
|
||||
1. Log into your Pocket ID instance
|
||||
2. Navigate to **Administration** → **OIDC Clients**
|
||||
3. Select **Add OIDC client**
|
||||
4. Configure the following settings:
|
||||
- **Name**: `Endurain`
|
||||
- **Client Launch URL**: Your Endurain FQDN (e.g., `https://endurain.mydomain.com`)
|
||||
- **Callback URLs**: `https://endurain.mydomain.com/api/v1/public/idp/callback/pocket-id`
|
||||
5. Click **Save**
|
||||
6. **Important**: Make a note of your **Client ID** and **Client Secret**
|
||||
|
||||
#### Step 2: Configure Endurain
|
||||
|
||||
1. Log into your Endurain instance
|
||||
2. Navigate to **Settings** → **Identity Providers**
|
||||
3. Select **Add Identity Provider** → **Select Pocket ID**
|
||||
4. Configure the following settings:
|
||||
- **Provider Name**: `Pocket ID`
|
||||
- **Slug**: `pocket-id`
|
||||
- **Provider Type**: `OIDC`
|
||||
- **Issuer URL**: Your Pocket ID FQDN (e.g., `https://pocketid.mydomain.com`) - **no trailing slash**
|
||||
- **Client ID**: The Client ID from Step 1
|
||||
- **Client Secret**: The Client Secret from Step 1
|
||||
- **Scopes**: `openid profile email`
|
||||
5. Click **Save**
|
||||
|
||||
#### Step 3: Test the Integration
|
||||
|
||||
1. Log out of Endurain
|
||||
2. On the login page, you should see a **Sign in with Pocket ID** button
|
||||
3. Click the button to test the SSO flow
|
||||
|
||||
---
|
||||
|
||||
### Tailscale TSIDP
|
||||
|
||||
Tailscale's identity provider (TSIDP) can be used for secure authentication within your Tailscale network.
|
||||
|
||||
#### Step 1: Configure TSIDP
|
||||
|
||||
1. Log into your TSIDP instance
|
||||
2. Select **Add new client**
|
||||
3. Configure the following settings:
|
||||
- **Client Name**: `Endurain`
|
||||
- **Redirect URIs**: `https://endurain.mydomain.com/api/v1/public/idp/callback/tsidp`
|
||||
4. Click **Create client**
|
||||
5. **Important**: Make a note of your **Client ID** and **Client Secret**
|
||||
|
||||
#### Step 2: Configure Endurain
|
||||
|
||||
1. Log into your Endurain instance
|
||||
2. Navigate to **Settings** → **Identity Providers**
|
||||
3. Select **Add Identity Provider** → **Custom**
|
||||
4. Configure the following settings:
|
||||
- **Provider Name**: `TSIDP`
|
||||
- **Slug**: `tsidp`
|
||||
- **Provider Type**: `OIDC`
|
||||
- **Issuer URL**: Your TSIDP FQDN (e.g., `https://tsidp.mydomain.com`) - **no trailing slash**
|
||||
- **Client ID**: The Client ID from Step 1
|
||||
- **Client Secret**: The Client Secret from Step 1
|
||||
- **Scopes**: `openid profile email`
|
||||
5. Click **Save**
|
||||
|
||||
#### Step 3: Test the Integration
|
||||
|
||||
1. Log out of Endurain
|
||||
2. On the login page, you should see a **Sign in with TSIDP** button
|
||||
3. Click the button to test the SSO flow
|
||||
|
||||
---
|
||||
|
||||
## General Configuration Steps
|
||||
|
||||
For any OIDC-compliant identity provider, follow these general steps:
|
||||
|
||||
### 1. Configure Your Identity Provider
|
||||
|
||||
Create an OAuth 2.0/OIDC client application with the following settings:
|
||||
|
||||
- **Application Name**: `Endurain`
|
||||
- **Redirect/Callback URI**: `https://<your-endurain-domain>/api/v1/public/idp/callback/<slug>`
|
||||
- **Grant Type**: `Authorization Code`
|
||||
- **Scopes**: At minimum `openid profile email`
|
||||
|
||||
Save the generated **Client ID** and **Client Secret**.
|
||||
|
||||
### 2. Configure Endurain
|
||||
|
||||
1. Log into Endurain as an administrator
|
||||
2. Navigate to **Settings** → **Identity Providers**
|
||||
3. Click **Add Identity Provider**
|
||||
4. Select your provider type or choose **Custom** for OIDC providers
|
||||
5. Fill in the required fields (see table below)
|
||||
6. Click **Save**
|
||||
|
||||
| Field | Description | Example |
|
||||
| ----- | ----------- | ------- |
|
||||
| **Provider Name** | Display name shown on login button | `Google`, `GitHub`, etc. |
|
||||
| **Slug** | URL-safe identifier (lowercase, hyphens) | `google`, `github` |
|
||||
| **Provider Type** | Protocol type | `OIDC` or `OAuth2` |
|
||||
| **Issuer URL** | Provider's base URL (no trailing slash) | `https://accounts.google.com` |
|
||||
| **Client ID** | OAuth client identifier | From Step 1 |
|
||||
| **Client Secret** | OAuth client secret | From Step 1 |
|
||||
| **Scopes** | Space-separated OAuth scopes | `openid profile email` |
|
||||
|
||||
### 3. Verify the Configuration
|
||||
|
||||
1. Log out of Endurain
|
||||
2. Visit the login page
|
||||
3. Verify that a **Sign in with `Provider Name`** button appears
|
||||
4. Test the authentication flow
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Problem**: "Invalid redirect URI" error
|
||||
|
||||
- **Solution**: Ensure the callback URL in your identity provider matches exactly: `https://<your-domain>/api/v1/public/idp/callback/<slug>`
|
||||
|
||||
**Problem**: "Email address mismatch" creates duplicate account
|
||||
|
||||
- **Solution**: Update your existing Endurain account email to match your SSO provider email, or link the identity provider to your existing account
|
||||
|
||||
**Problem**: SSO button doesn't appear on login page
|
||||
|
||||
- **Solution**:
|
||||
- Verify the identity provider is enabled in Endurain settings
|
||||
- Check if external authentication is enabled on server settings
|
||||
- Check that the provider configuration is saved correctly
|
||||
- Clear your browser cache and refresh the page
|
||||
|
||||
**Problem**: "Invalid issuer URL" error
|
||||
|
||||
- **Solution**: Ensure the Issuer URL does not have a trailing slash and is the correct base URL for your identity provider
|
||||
|
||||
### Logs
|
||||
|
||||
For detailed troubleshooting, check the Endurain backend logs:
|
||||
|
||||
```bash
|
||||
docker logs endurain-backend
|
||||
# and/or
|
||||
tail -n 100 logs/app.log
|
||||
```
|
||||
|
||||
Look for authentication-related errors that can help identify configuration issues.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
!!! warning "Security Best Practices"
|
||||
- Always use **HTTPS** for both Endurain and your identity provider
|
||||
- Keep your **Client Secret** confidential and never commit it to version control
|
||||
- Regularly rotate client secrets
|
||||
- Use strong, randomly generated secrets
|
||||
- Limit OAuth scopes to only what's necessary (`openid profile email` is typically sufficient)
|
||||
- Monitor authentication logs for suspicious activity
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Authentication Developer Guide](../developer-guide/authentication.md) - Technical details about Endurain's authentication system
|
||||
- [Getting Started Guide](../getting-started/getting-started.md) - General setup instructions
|
||||
- [OAuth 2.0 Specification](https://oauth.net/2/) - Official OAuth 2.0 documentation
|
||||
- [OpenID Connect Specification](https://openid.net/connect/) - Official OIDC documentation
|
||||
10
mkdocs.yml
10
mkdocs.yml
@@ -2,6 +2,11 @@ site_name: Endurain documentation
|
||||
repo_url: https://github.com/endurain-project/endurain
|
||||
theme:
|
||||
name: material
|
||||
icon:
|
||||
admonition:
|
||||
alert: material/alert
|
||||
note: material/information
|
||||
tip: material/lightbulb-on
|
||||
palette:
|
||||
# Palette toggle for light mode
|
||||
- media: "(prefers-color-scheme: light)"
|
||||
@@ -16,6 +21,10 @@ theme:
|
||||
toggle:
|
||||
icon: material/brightness-4
|
||||
name: Switch to light mode
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
- pymdownx.details
|
||||
- pymdownx.superfences
|
||||
nav:
|
||||
- Home: index.md
|
||||
- Hosting Guide:
|
||||
@@ -24,6 +33,7 @@ nav:
|
||||
- Bare-Metal Installation Guide: getting-started/bare-metal.md
|
||||
- MariaDB to Postgres migration: getting-started/maria-to-postgres-migration.md
|
||||
- Features:
|
||||
- Single Sign-On (SSO): features/single-sign-on.md
|
||||
- Sleep Scoring: features/sleep-scoring.md
|
||||
- Integrations:
|
||||
- 3rd party apps: integrations/3rd-party-apps.md
|
||||
|
||||
Reference in New Issue
Block a user