Identity Providers (IdP)
Relevant source files
The following files were used as context for generating this wiki page:
Identity Providers (IdP) in Casdoor are components that allow users to authenticate using external services such as social media (GitHub, Google), enterprise systems (Azure AD, SAML), or custom OAuth2/OIDC implementations. Casdoor acts as a central hub, abstracting the complexities of various third-party protocols into a unified interface for applications.
The IdP system is designed to be highly extensible. It supports a wide range of native implementations, integrates with the goth library for additional social providers, and provides a "Custom" provider type that allows administrators to map arbitrary third-party user attributes to Casdoor's internal user model.
Sources: README.md:1-5, idp/provider.go:34-106, idp/custom.go:94-118
Backend Architecture
The backend implementation relies on a central interface and a factory pattern to instantiate the appropriate provider logic based on the configuration.
The IdProvider Interface
Every identity provider implementation must satisfy the IdProvider interface. This ensures a consistent method for exchanging authorization codes for tokens and fetching user information across different platforms.
The diagram shows the standard interface and how specialized providers like Custom and WeCom implement it.
Sources: idp/provider.go:48-52, idp/custom.go:31-38, idp/wecom_internal.go:30-35
Provider Selection Logic
The GetIdProvider function serves as a factory. It evaluates the Type and SubType defined in the ProviderInfo to return the correct implementation. It first checks for native Casdoor implementations (e.g., GitHub, Google, WeCom) before falling back to the goth library or custom providers.
Selection flow for determining which backend handler to use for a specific IdP configuration.
Sources: idp/provider.go:54-106
Data Models
The system uses standardized structures to pass information between the external provider and Casdoor's internal storage.
UserInfo Structure
This structure represents the normalized user data retrieved from an external provider.
| Field | Description |
|---|---|
Id | The unique identifier from the external provider. |
Username | The login name or handle provided by the external service. |
DisplayName | The user's public-facing name. |
Email | The user's email address (if available and authorized). |
AvatarUrl | Link to the user's profile picture. |
Extra | A map for provider-specific attributes that don't fit standard fields. |
Sources: idp/provider.go:21-32
Custom Provider Mapping
Custom providers allow developers to define a UserMapping. This maps nested JSON keys from a third-party UserInfo response to Casdoor's fields using dot notation (e.g., data.profile.username).
Sources: idp/custom.go:56-74, idp/custom.go:95-104
Frontend Implementation
The frontend manages the initial redirection to the identity provider and handles security features like PKCE.
Authentication URL Generation
The getAuthUrl function in the frontend assembles the redirection target based on the provider's metadata, requested scopes, and application settings.
Interaction between the user, frontend, and external IdP during the initial auth request.
Sources: web/src/auth/Provider.js:283-300, web/src/auth/Provider.js:21-25
PKCE Support
Casdoor implements Proof Key for Code Exchange (PKCE) for enhanced security in public clients.
- Code Verifier: A random 32-byte string generated via
crypto.getRandomValues. - Code Challenge: A SHA-256 hash of the verifier, URL-safe base64 encoded.
- Storage: The verifier is stored in
localStoragekeyed by the OAuthstateto be retrieved after the callback.
Sources: web/src/auth/Provider.js:21-46, web/src/auth/Provider.js:298-300
API Endpoints
The provider management is handled through a RESTful API.
| Method | Endpoint | Description |
|---|---|---|
POST | /api/add-provider | Registers a new IdP configuration. |
POST | /api/update-provider | Modifies an existing IdP's settings. |
GET | /api/get-provider | Retrieves details for a specific provider by ID. |
GET | /api/get-providers | Lists all providers owned by an organization. |
POST | /api/delete-provider | Removes a provider configuration. |
Sources: swagger/swagger.yml:256-271, swagger/swagger.yml:926-941, routers/router.go:94-99
Implementation Example: Custom Provider
The CustomIdProvider highlights how Casdoor handles flexible attribute mapping. It retrieves the access token via a standard OAuth2 exchange and then makes an authenticated GET request to the UserInfoURL.
func (idp *CustomIdProvider) GetUserInfo(token *oauth2.Token) (*UserInfo, error) {
accessToken := token.AccessToken
request, err := http.NewRequest("GET", idp.UserInfoURL, nil)
// ... add Bearer token ...
resp, err := idp.Client.Do(request)
// ... unmarshal JSON ...
for k, v := range idp.UserMapping {
val, _ := getNestedValue(dataMap, v)
dataMap[k] = val
}
// ... decode to UserInfo ...
}
Sources: idp/custom.go:76-118
Summary
The Identity Provider system in Casdoor provides a robust bridge between external authentication sources and the internal user management system. By combining a strict backend interface with flexible frontend URL generation and custom mapping capabilities, it supports nearly any OAuth2/OIDC or SAML-compliant service. This architecture allows Casdoor to scale from simple social logins to complex enterprise federations.