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 soporta cuatro tipos de concesión OAuth: Authorization Code Grant, Implicit Grant, Resource Owner Password Credentials Grant, y Client Credentials Grant.

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	dirección del usuario
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 también soporta la característica PKCE. Al obtener el código de autorización, puedes agregar dos parámetros para habilitar PKCE:

&code_challenge_method=S256&code_challenge=TU_DESAFÍO

Al obtener el token, necesitas pasar el parámetro code_verifier para verificar PKCE. Cabe mencionar que con PKCE habilitado, Client_Secret no es requerido, pero si lo pasas, debe ser el valor correcto.

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.

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,
}

Recibirás la siguiente respuesta:

{
    "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"
}

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.

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. Es una API específica de Casdoor que te permite obtener toda la información del usuario en Casdoor.