OAuth2 And SSO
Page Guide
ScenarioFor projects that integrate FastBee with a unified identity system, third-party login, or OAuth2 service mode.
PrerequisiteClient, callback URI, scope, user mapping, and logout strategy have been planned.
AcceptanceThe third-party system can authorize, obtain token, read user information, and log out according to the expected policy.
1. Capability Scope
FastBee OAuth/SSO is provided by fastbee-plugs/fastbee-oauth-server.
| Capability | API Or Path | Description |
|---|---|---|
| Authorization | /oauth2/authorize, /oauth/authorize | Authorization code entry. |
| Token | /oauth2/token, /oauth/token | Obtain access token. |
| Login confirmation | /oauth2/doLogin, /oauth2/doConfirm | Login and authorization confirmation. |
| Token check | /oauth2/check-token, /oauth/check_token | Validate token. |
| Token revoke | /oauth2/revoke, /oauth/revoke | Logout or revoke authorization. |
| User info | /oauth2/userinfo | Get current user profile. |
| OIDC metadata | /.well-known/openid-configuration | OpenID Connect metadata. |
| JWKS | /oauth2/jwks | Public key information. |
| SSO | /sso/* | Single sign-on related APIs. |
2. Client Configuration
| Field | Description | Recommendation |
|---|---|---|
| Client ID | Unique client identifier. | Use a short business system code. |
| Client Secret | Client credential. | Rotate regularly in production. |
| Redirect URI | Authorization callback address. | Must match the third-party configuration exactly. |
| Scope | Authorization range. | Open only the minimum required scope. |
| Grant Type | Authorization mode. | Authorization code is commonly used. |
| Token lifetime | Access token validity period. | Configure according to security requirements. |
| Refresh Token | Whether refresh is allowed. | Enable for long-session scenarios. |
3. Authorization Code Flow
4. Integration Checks
| Check Item | Expected Result |
|---|---|
| Callback URI | User returns to the third-party system after authorization. |
| Code | Callback contains an authorization code. |
| Token | Third-party system obtains access token successfully. |
| User info | /userinfo returns the current user profile. |
| Scope | Granted scope matches client configuration. |
| Logout | FastBee and third-party logout policies are clear. |
| Audit | Login and authorization logs are traceable. |
5. FAQ
redirect_uri mismatch
The callback address must exactly match the client configuration, including protocol, domain, port, path, and trailing slash.
Token request fails
Check the Client ID, Client Secret, whether the authorization code has expired, and whether the grant type is enabled.
User information is empty
Check whether the token is valid, whether the user is disabled, and whether the scope includes permission to read user information.
Incomplete single logout
Decide whether to log out of only the third-party system, only FastBee, or both. Each project should define a consistent policy.
6. Development Entry
| Type | Path Or API | Description |
|---|---|---|
| Frontend page | vue3/src/views/iot/clientDetails, vue3/src/views/system/sysclient | Client configuration. |
| OAuth module | springboot/fastbee-plugs/fastbee-oauth-server | OAuth2 and SSO service. |
| Client API | /iot/clientDetails | Client management. |
| OAuth tables | oauth_client_details, oauth_access_token, oauth_refresh_token | Authorization data. |
| User tables | sys_user, sys_auth_user | User and third-party identity mapping. |