OAuth 2.0

Introducción

Casdoor soporta el uso de Access Token para autenticar clientes. En esta sección, te mostraremos cómo obtener un Access Token, cómo verificar un Access Token y cómo usar un Access Token.

Cómo obtener un Access Token

Hay dos maneras de obtener un Access Token: puedes usar los SDKs de Casdoor. Para información detallada, por favor consulta la documentación del SDK. Aquí, principalmente te mostraremos cómo usar la API para obtener el Access Token.

Casdoor supports standard OAuth 2.0 grant types including Authorization Code Grant, Implicit Grant, Resource Owner Password Credentials Grant, Client Credentials Grant, Refresh Token, Device Authorization Grant, and Token Exchange.

Por razones de seguridad, la aplicación Casdoor tiene el modo de código de autorización activado por defecto. Si necesitas usar otros modos, por favor ve a la aplicación apropiada para configurarlo.

Authorization Code Grant

Primero, redirige a tus usuarios a:

https://<CASDOOR_HOST>/login/oauth/authorize?
client_id=CLIENT_ID&
redirect_uri=REDIRECT_URI&
response_type=code&
scope=openid&
state=STATE

Ámbitos disponibles

Nombre	Descripción
openid (no scope)	sub (id del usuario), iss (emisor), y aud (audiencia)
profile	información del perfil del usuario, incluyendo nombre, displayName y avatar
email	dirección de correo electrónico del usuario
address	user's address — returned as an OIDC address object in JWT-Standard tokens; see OIDC Address Claim for details
phone	número de teléfono del usuario

información

Tu Aplicación OAuth puede solicitar los ámbitos en la redirección inicial. Puedes especificar múltiples ámbitos separándolos con un espacio usando %20:

https://<CASDOOR_HOST>/login/oauth/authorize?
client_id=...&
scope=openid%20email

Para más detalles, por favor consulta el estándar OIDC

Después de que tu usuario se haya autenticado con Casdoor, Casdoor los redirigirá a:

https://REDIRECT_URI?code=CODE&state=STATE

Ahora que has obtenido el código de autorización, haz una solicitud POST a:

https://<CASDOOR_HOST>/api/login/oauth/access_token

en tu aplicación de backend:

{
    "grant_type": "authorization_code",
    "client_id": ClientId,
    "client_secret": ClientSecret,
    "code": Code,
}

Recibirás la siguiente respuesta:

{
    "access_token": "eyJhb...",
    "id_token": "eyJhb...",
    "refresh_token": "eyJhb...",
    "token_type": "Bearer",
    "expires_in": 10080,
    "scope": "openid"
}

nota

Casdoor supports PKCE (Proof Key for Code Exchange) for enhanced security. To enable PKCE, add two parameters when requesting the authorization code:

&code_challenge_method=S256&code_challenge=YOUR_CHALLENGE

The code challenge should be a Base64-URL-encoded SHA-256 hash of your randomly generated code verifier (43-128 characters). When requesting the token, include the original code_verifier parameter. With PKCE enabled, client_secret becomes optional, but if provided, it must be correct.

For OAuth providers configured in Casdoor (like Twitter and custom providers with PKCE enabled), Casdoor automatically generates unique code verifiers for each authentication flow, so you don't need to manually implement PKCE.

Binding Tokens to Specific Services

When your application needs to call multiple backend services, you might want tokens that are explicitly bound to a specific service. This prevents security issues where a token meant for one service could accidentally be used with another.

Casdoor supports RFC 8707 Resource Indicators, which lets you specify the intended service when requesting authorization. Add the resource parameter with an absolute URI identifying your service:

https://<CASDOOR_HOST>/login/oauth/authorize?
client_id=CLIENT_ID&
redirect_uri=REDIRECT_URI&
response_type=code&
scope=openid&
state=STATE&
resource=https://api.example.com

When you exchange the authorization code for tokens, include the same resource parameter:

{
    "grant_type": "authorization_code",
    "client_id": ClientId,
    "client_secret": ClientSecret,
    "code": Code,
    "resource": "https://api.example.com"
}

The resulting access token will have its aud (audience) claim set to your resource URI instead of the client ID. Your backend service can then verify that tokens were issued specifically for it by checking the audience claim. The resource must match exactly between the authorization and token requests.

Signup Flow with OAuth

When users sign up through the OAuth authorization flow, they are automatically redirected to your application's callback URL with the authorization code, just like the sign-in flow. Previously, users had to manually click through intermediate pages after creating their account. Now the signup process matches the streamlined experience of signing in—once registration completes, Casdoor immediately generates the authorization code and redirects to your redirect_uri.

Your application doesn't need any changes to support this. The authorization parameters (client_id, response_type, redirect_uri, etc.) are automatically passed through the signup process when users choose to create a new account during OAuth authorization.

Implicit Grant

Tal vez tu aplicación no tenga un backend, y necesites usar Implicit Grant. Primero, necesitas asegurarte de tener habilitado Implicit Grant, luego redirige a tus usuarios a:

https://<CASDOOR_HOST>/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=token&scope=openid&state=STATE

Después de que tu usuario se haya autenticado con Casdoor, Casdoor los redirigirá a:

https://REDIRECT_URI/#access_token=ACCESS_TOKEN

Casdoor también soporta el id_token como response_type, que es una característica de OpenID.

Device Grant

Maybe your devices have limited input capabilities or lack a suitable browser, and you need to use Device Grant. First, you need to make sure you have Device Grant enabled, the request device_authorization_endpoint in OIDC discover, then use QR code or text to show verification_uri and lead user to enter login page.

Second, you should request token endpoint to get Access Token with parameter define in rfc8628.

Resource Owner Password Credentials Grant

Si tu aplicación no tiene un frontend que redirija a los usuarios a Casdoor, entonces esto te puede ser necesario.

Primero, necesitas asegurarte de tener habilitado Password Credentials Grant y enviar una solicitud POST a:

https://<CASDOOR_HOST>/api/login/oauth/access_token

{
    "grant_type": "password",
    "client_id": ClientId,
    "client_secret": ClientSecret,
    "username": Username,
    "password": Password,
}

You will get the following response:

{
    "access_token": "eyJhb...",
    "id_token": "eyJhb...",
    "refresh_token": "eyJhb...",
    "token_type": "Bearer",
    "expires_in": 10080,
    "scope": "openid"
}

Client Credentials Grant

También puedes usar Client Credentials Grant cuando tu aplicación no tenga un frontend.

Primero, necesitas asegurarte de tener habilitado Client Credentials Grant y enviar una solicitud POST a https://<CASDOOR_HOST>/api/login/oauth/access_token:

{
    "grant_type": "client_credentials",
    "client_id": ClientId,
    "client_secret": ClientSecret,
}

Recibirás la siguiente respuesta:

{
    "access_token": "eyJhb...",
    "id_token": "eyJhb...",
    "refresh_token": "eyJhb...",
    "token_type": "Bearer",
    "expires_in": 10080,
    "scope": "openid"
}

Es importante notar que el AccessToken obtenido de esta manera difiere de los primeros tres en que corresponde a la aplicación y no al usuario.

Refresh Token

Tal vez quieras actualizar tu Access Token, entonces puedes usar el refreshToken que obtuviste arriba.

Primero, necesitas configurar el tiempo de expiración del Refresh Token en la aplicación (por defecto es 0 horas), y enviar una solicitud POST a https://<CASDOOR_HOST>/api/login/oauth/refresh_token

{
    "grant_type": "refresh_token",
    "refresh_token": REFRESH_TOKEN,
    "scope": SCOPE,
    "client_id": ClientId,
    "client_secret": ClientSecret,
}

Recibirás una respuesta como esta:

{
    "access_token": "eyJhb...",
    "id_token": "eyJhb...",
    "refresh_token": "eyJhb...",
    "token_type": "Bearer",
    "expires_in": 10080,
    "scope": "openid"
}

Token Exchange Grant

Token Exchange (RFC 8693) lets you swap an existing token for a new one with different characteristics—particularly useful when one service needs to call another on behalf of a user, or when you need to narrow down a token's scope for a specific downstream service.

To exchange a token, send a POST request to https://<CASDOOR_HOST>/api/login/oauth/access_token:

{
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "client_id": ClientId,
    "client_secret": ClientSecret,
    "subject_token": SubjectToken,
    "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "scope": "openid email"
}

The subject_token is the token you want to exchange—typically an access token or JWT you already have. If you want to narrow the permissions in the new token, specify a scope that's a subset of the original token's scope. When you omit scope, the new token inherits the same scope as the subject token.

Casdoor supports three token types for subject_token_type:

• urn:ietf:params:oauth:token-type:access_token (default)
• urn:ietf:params:oauth:token-type:jwt
• urn:ietf:params:oauth:token-type:id_token

The response returns a new token tied to the same user as your subject token:

{
    "access_token": "eyJhb...",
    "id_token": "eyJhb...",
    "refresh_token": "eyJhb...",
    "token_type": "Bearer",
    "expires_in": 10080,
    "scope": "openid email"
}

For example, an API gateway might exchange a broad-scoped access token for a narrower one before forwarding requests to a downstream microservice. This pattern—called scope downscoping—ensures each service gets only the permissions it needs, rather than inheriting full access from the original token.

Cómo verificar Access Token

Casdoor actualmente soporta el endpoint de introspección de token. Este endpoint está protegido por Autenticación Básica (ClientId:ClientSecret).

POST /api/login/oauth/introspect HTTP/1.1
Host: CASDOOR_HOST
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

token=ACCESS_TOKEN&token_type_hint=access_token

Recibirás la siguiente respuesta:

{
    "active": true,
    "client_id": "c58c...",
    "username": "admin",
    "token_type": "Bearer",
    "exp": 1647138242,
    "iat": 1646533442,
    "nbf": 1646533442,
    "sub": "7a6b4a8a-b731-48da-bc44-36ae27338817",
    "aud": [
        "c58c..."
    ],
    "iss": "http://localhost:8000"
}

Cómo usar AccessToken

Puedes usar AccessToken para acceder a las APIs de Casdoor que requieren autenticación.

Por ejemplo, hay dos maneras diferentes de solicitar /api/userinfo.

Tipo 1: Parámetro de consulta

https://<CASDOOR_HOST>/api/userinfo?accessToken=<your_access_token>

Tipo 2: Token Bearer HTTP

https://<CASDOOR_HOST>/api/userinfo with the header: "Authorization: Bearer <your_access_token>"

Casdoor analizará el access_token y devolverá la información del usuario correspondiente según el scope. Recibirás la misma respuesta, que se ve así:

{
    "sub": "7a6b4a8a-b731-48da-bc44-36ae27338817",
    "iss": "http://localhost:8000",
    "aud": "c58c..."
}

Si esperas más información del usuario, añade scope al obtener el AccessToken en el paso Authorization Code Grant.

Accessing OAuth Provider Tokens

When users authenticate through OAuth providers (GitHub, Google, etc.), you can access the provider's original access token to make API calls to the third-party service on their behalf. This token is stored in the user's originalToken field.

The token is available through the /api/get-account endpoint:

{
  "status": "ok",
  "data": {
    "name": "user123",
    "originalToken": "ya29.a0AfH6SMBx...",
    ...
  }
}

The originalToken is visible only when the user requests their own account or when the requester is an admin. For other requests, it is masked for privacy.

This allows your application to interact with third-party APIs (e.g., GitHub API, Google Drive API) using the provider's access token without requiring additional OAuth flows.

Diferencias entre las APIs userinfo y get-account

• /api/userinfo: Esta API devuelve información del usuario como parte del protocolo OIDC. Proporciona información limitada, incluyendo solo la información básica definida en los estándares OIDC. Para una lista de ámbitos disponibles soportados por Casdoor, por favor consulta la sección de ámbitos disponibles.

• /api/get-account: Esta API recupera el objeto del usuario para la cuenta actualmente conectada. It is a Casdoor-specific API that allows you to obtain all the information of the user in Casdoor, including the OAuth provider's access token when applicable.