tcjlj/OpenFlare
1
0
Fork 0
mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-10-09 00:56:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

[优化] 更新文档

Browse Source
This commit is contained in:
ryan
2026-06-01 23:19:32 +08:00
parent a850b0a188
commit 2525664013
76 changed files with 6493 additions and 2497 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/guide/sso.md
+56 -54
View File
@@ -1,104 +1,106 @@
# SSO Login
# SSO Login Configuration
You will learn how to configure GitHub OAuth or a standard OIDC login source for OpenFlare, how to set callback URLs, and how third-party accounts bind to local users.
You will learn: How to configure GitHub OAuth or standard OIDC login portals for OpenFlare, how to fill in callback URLs, and how third-party accounts bind to existing local users.
OpenFlare supports third-party login through authentication sources. The current supported source types are GitHub OAuth and standard OIDC providers, such as Logto, authentik, Keycloak, and Casdoor.
OpenFlare supports third-party logins configured via Authentication Sources. Currently, GitHub OAuth and standard OIDC Providers (e.g., Logto, authentik, Keycloak, Casdoor) are supported.
After an authentication source is configured and enabled, it appears on the login page. Users can sign in with the third-party account or bind it to the current local account while already signed in.
Once an Authentication Source is configured and enabled, it displays in the third-party login section of the login page. Users can log in using their third-party accounts or bind their third-party accounts to their current local account while logged in.
## Before You Start
## Prerequisites
Prepare:
Before starting, prepare the following:
| Item | Description |
| --- | --- |
| OpenFlare public URL | The URL users open in their browser, such as `https://openflare.example.com` |
| Source name | Internal unique name, such as `github` or `company-oidc` |
| Client ID | Provided by the third-party application |
| Client Secret | Provided by the third-party application |
| OIDC Discovery URL | Required only for OIDC, such as `https://idp.example.com/.well-known/openid-configuration` |
| OpenFlare URL | The actual URL accessed by user browsers, e.g., `https://openflare.example.com` |
| Auth Source Name | Unique internal identifier in OpenFlare, e.g., `github`, `company-oidc` |
| Client ID | Provided after creating an application in the third-party platform |
| Client Secret | Provided after creating an application in the third-party platform |
| OIDC Discovery URL | Required for OIDC only, e.g., `https://idp.example.com/.well-known/openid-configuration` |
Confirm that the server address in system settings matches the domain users access.
**Verify that "System Settings -> General Settings -> Server Address" accurately matches your domain name.**
The source name can contain letters, numbers, hyphens, and underscores, and must start with a letter or number. The source name is part of the callback URL. If you rename it later, update the callback URL in the third-party platform too.
The Auth Source name can only contain letters, numbers, hyphens, or underscores, and must start with a letter or number. The Auth Source name will appear in the callback URL; if you modify the name after saving, you must simultaneously modify the callback URL on the third-party platform.
## Callback URL
Set the Redirect URI / Callback URL in the third-party platform to:
The Redirect URI / Callback URL in third-party platforms is formatted as:
```text
<OpenFlare public URL>/oauth/<source name>
<OpenFlare URL>/oauth/<Auth Source Name>
```
Examples:
Example:
```text
https://openflare.example.com/oauth/github
https://openflare.example.com/oauth/company-oidc
```
When creating or editing an authentication source, the UI shows the callback URL based on the current browser URL and source name.
When creating or editing an authentication source in the management console, the form automatically generates the callback URL based on your current browser URL and the Auth Source name you entered.
## Configure GitHub Login
1. Create an OAuth App in GitHub.
2. Set `Homepage URL` to the OpenFlare public URL.
3. Set `Authorization callback URL` to the callback shown by OpenFlare, such as `https://openflare.example.com/oauth/github`.
4. Copy the Client ID and Client Secret.
5. Sign in to OpenFlare and open Settings -> System Settings -> Authentication Sources.
6. Add a source and select `GitHub`.
7. Fill in source name, display name, Client ID, and Client Secret.
8. Keep the default scope `user:email` unless your GitHub app requires a different value.
9. Save and enable the source.
2. Fill `Homepage URL` with your OpenFlare URL.
3. Fill `Authorization callback URL` with the callback URL generated in OpenFlare, e.g., `https://openflare.example.com/oauth/github`.
4. Copy the Client ID and Client Secret provided by GitHub.
5. Log into the OpenFlare management console, go to "Settings -> System Settings -> Configure Authentication Sources".
6. Add an authentication source, choosing `GitHub` as the type.
7. Fill in the Auth Source name, display name, Client ID, and Client Secret.
8. The Scope defaults to `user:email`, which usually requires no modification.
9. Save and enable the authentication source.
The login page will show the GitHub button after the source is enabled.
Once enabled, the corresponding GitHub login button will display on the login page.
## Configure OIDC Login
1. Create an application or client in the OIDC provider.
2. Choose a Web / Confidential Client type.
3. Set Redirect URI / Callback URL to the value shown by OpenFlare, such as `https://openflare.example.com/oauth/company-oidc`.
1. Create an application or client in your OIDC Provider.
2. Select Web / Confidential Client as the application type.
3. Fill `Redirect URI / Callback URL` with the callback URL generated in OpenFlare, e.g., `https://openflare.example.com/oauth/company-oidc`.
4. Copy the Client ID and Client Secret.
5. Get the provider Discovery URL, usually ending in `/.well-known/openid-configuration`.
6. Sign in to OpenFlare and open Settings -> System Settings -> Authentication Sources.
7. Add a source and select `OIDC`.
8. Fill in source name, display name, Client ID, Client Secret, and OIDC Discovery URL.
9. Keep the default scope `openid profile email` unless the provider restricts scopes.
10. Save and enable the source.
5. Retrieve the Provider's Discovery URL, which usually ends with `/.well-known/openid-configuration`.
6. Log into the OpenFlare management console, go to "Settings -> System Settings -> Configure Authentication Sources".
7. Add an authentication source, choosing `OIDC` as the type.
8. Fill in the Auth Source name, display name, Client ID, Client Secret, and OIDC Discovery URL.
9. Scope defaults to `openid profile email`. If the Provider restricts scopes, adjust to values permitted by the Provider.
10. Save and enable the authentication source.
The login page will show the OIDC button after the source is enabled.
Once enabled, the corresponding OIDC login button will display on the login page.
## Login and Binding Behavior
## Login & Binding Behaviors
Once a third-party account returns to OpenFlare, it is processed according to the following rules:
| Scenario | Behavior |
| --- | --- |
| Third-party account already bound to a local user | Sign in directly |
| User is already signed in and starts third-party authorization | Bind the third-party account to the current local user |
| Third-party account is unbound and registration is allowed | Create a normal local user and bind it |
| Third-party account is unbound and registration is disabled | Ask the user to enter existing local credentials to bind |
| Third-party account is already bound to a local user | Logs in directly |
| User is already logged in and initiates third-party authorization | Binds to the current local user |
| Third-party account is unbound, and registration is enabled | Automatically creates a standard user and binds |
| Third-party account is unbound, and registration is disabled | Prompts to enter an existing local username and password to complete the binding |
If you only want existing users to use SSO, disable registration. Unbound third-party accounts will enter the existing-account binding flow.
If you want only existing users to use SSO, you can disable user registration. Unbound third-party accounts will then trigger the binding flow.
## Update a Source
## Modify Authentication Source
When editing an authentication source, leave Client Secret empty to keep the existing secret. Entering a new value overwrites it.
When editing an authentication source, leaving the Client Secret field blank retains the existing secret; entering a new value will overwrite the saved secret.
If you change the source name, the callback URL changes too. Update Redirect URI / Callback URL in the third-party platform, or the provider will reject the callback.
If you modify the Auth Source name, the callback URL changes accordingly. You must modify the Redirect URI / Callback URL on the third-party platform; otherwise, the third-party platform will deny the callback or return an error.
## FAQ
## Common Problems
### `invalid_scope`
### Returns `invalid_scope`
The provider does not allow the configured scope. The OIDC default is `openid profile email`; the GitHub default is `user:email`. Adjust the scope in OpenFlare or allow it in the provider.
This indicates that the third-party platform does not permit the configured Scope. OIDC defaults to `openid profile email`, and GitHub defaults to `user:email`. Adjust the Scope in the authentication source edit page or configure the third-party platform to permit the scope.
### Callback URL Mismatch
### Callback Address Mismatch
Check that the Redirect URI / Callback URL in the provider exactly matches the URL shown by OpenFlare. Protocol, domain, port, and path must all match.
Verify if the Redirect URI / Callback URL configured in the third-party platform matches the prompt in the OpenFlare form exactly. The protocol, domain, port, and path must match.
### No Third-Party Login Button
### Third-party Login Button Not Showing on Login Page
Check that the source is enabled and that Client ID and Client Secret are saved. OpenFlare validates these fields before enabling a source.
Verify if the authentication source is enabled and confirm that the Client ID and Client Secret are saved. OpenFlare validates these fields before enabling the source.
### Client Secret Is Not Shown in the List
### Client Secret Saved but Not Displayed in Clear Text
This is expected. OpenFlare does not return Client Secret through the API; it only shows whether the secret is configured.
This is expected behavior. OpenFlare does not echo the Client Secret back via API, displaying only whether the secret is configured.