Pular para o conteúdo principal

OAuth 2.0

Introdução​

O Casdoor suporta o uso de Access Token para autenticar clientes. Nesta seção, mostraremos como obter um Access Token, como verificar um Access Token e como usar um Access Token.

Como Obter um Access Token​

Há duas maneiras de obter um Access Token: você pode usar os SDKs do Casdoor. Para informações detalhadas, por favor consulte a documentação do SDK. Aqui, mostraremos principalmente como usar a API para obter o Access Token.

O Casdoor suporta quatro tipos de concessão OAuth: Authorization Code Grant, Implicit Grant, Resource Owner Password Credentials Grant e Client Credentials Grant.

Por razões de segurança, o aplicativo Casdoor tem o modo de código de autorização ativado por padrão. Se você precisa usar outros modos, por favor vá ao aplicativo apropriado para configurá-lo.

Tipos de Concessão

Authorization Code Grant​

Primeiro, redirecione seus usuários para:

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

Escopos Disponíveis​

NomeDescrição
openid (no scope)sub (id do usuário), iss (emissor) e aud (audiência)
profileinformações do perfil do usuário, incluindo nome, displayName e avatar
emailendereço de email do usuário
addressendereço do usuário
phonenúmero de telefone do usuário
informação

Sua Aplicação OAuth pode solicitar os escopos no redirecionamento inicial. Você pode especificar múltiplos escopos separando-os com um espaço usando %20:

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

Para mais detalhes, por favor veja o padrão OIDC

Após seu usuário se autenticar com o Casdoor, o Casdoor irá redirecioná-lo para:

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

Agora que você obteve o código de autorização, faça uma solicitação POST para:

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

na sua aplicação backend:

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

Você receberá a seguinte resposta:

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

O Casdoor também suporta o recurso PKCE. Ao obter o código de autorização, você pode adicionar dois parâmetros para habilitar o PKCE:

&code_challenge_method=S256&code_challenge=YOUR_CHANNELLENGE

Ao obter o token, você precisa passar o parâmetro code_verifier para verificar o PKCE. Vale mencionar que com o PKCE habilitado, Client_Secret não é necessário, mas se você passá-lo, deve ser o valor correto.

Implicit Grant​

Talvez sua aplicação não tenha um backend, e você precise usar Implicit Grant. Primeiro, você precisa ter certeza de que o Implicit Grant está habilitado, então redirecione seus usuários para:

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

Após seu usuário se autenticar com o Casdoor, o Casdoor irá redirecioná-lo para:

https://REDIRECT_URI/#access_token=ACCESS_TOKEN

O Casdoor também suporta o id_token como response_type, que é um recurso do OpenID.

Resource Owner Password Credentials Grant​

Se sua aplicação não tem um frontend que redireciona os usuários para o Casdoor, então você pode precisar disso.

Primeiro, você precisa ter certeza de que o Password Credentials Grant está habilitado e enviar uma solicitação POST para:

https://<CASDOOR_HOST>/api/login/oauth/access_token
{
    "grant_type": "password",
    "client_id": ClientId,
    "client_secret": ClientSecret,
    "username": Username,
    "password": Password,
}

Você receberá a seguinte resposta:

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

Client Credentials Grant​

Você também pode usar Client Credentials Grant quando sua aplicação não tem um frontend.

Primeiro, você precisa ter certeza de que o Client Credentials Grant está habilitado e enviar uma solicitação POST para https://<CASDOOR_HOST>/api/login/oauth/access_token:

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

Você receberá a seguinte resposta:

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

É importante notar que o AccessToken obtido desta forma difere dos três primeiros, pois corresponde à aplicação e não ao usuário.

Refresh Token​

Talvez você queira atualizar seu Access Token, então você pode usar o refreshToken que obteve acima.

Primeiro, você precisa definir o tempo de expiração do Refresh Token no aplicativo (padrão é 0 horas), e enviar uma solicitação POST para https://<CASDOOR_HOST>/api/login/oauth/refresh_token

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

Você receberá uma resposta como esta:

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

Como Verificar Access Token​

O Casdoor atualmente suporta o endpoint de introspecção de token. Este endpoint é protegido por Autenticação 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

Você receberá a seguinte resposta:

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

Como Usar AccessToken​

Você pode usar AccessToken para acessar APIs do Casdoor que requerem autenticação.

Por exemplo, existem duas maneiras 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>"

O Casdoor irá analisar o access_token e retornar as informações do usuário correspondentes de acordo com o scope. Você receberá a mesma resposta, que se parece com isto:

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

Se você espera mais informações do usuário, adicione scope ao obter o AccessToken na etapa Authorization Code Grant.

Diferenças entre as APIs userinfo e get-account​

  • /api/userinfo: Esta API retorna informações do usuário como parte do protocolo OIDC. Ela fornece informações limitadas, incluindo apenas as informações básicas definidas nos padrões OIDC. Para uma lista de escopos disponíveis suportados pelo Casdoor, por favor consulte a seção de escopos disponíveis.

  • /api/get-account: Esta API recupera o objeto do usuário para a conta atualmente logada. É uma API específica do Casdoor que permite obter todas as informações do usuário no Casdoor.