Skip to main content

OAuth 2.0

Introduction​

Casdoor supports AccessToken to authenticate clients. In this section, we will show you how to get AccessToken, how to verify AccessToken and how to use AccessToken.

How to get AccessToken​

You have two ways to get the AccessToken: you can use the Casdoor SDKs, for details please refer to the SDK documentation, here we will mainly show you how to use the API to get the AccessToken.

Casdoor supports four OAuth grant types: Authorization Code Grant, Implicit Grant, Resource Owner Password Credentials Grant, and Client Credentials Grant.

For security reasons, the Casdoor app has the authorization code mode turned on by default. If you need to use other modes, please go to the appropriate app to set it.

Grant Types

Authorization Code Grant ​

First redirect your users to:

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

Available scopes​

NameDescription
openid (no scope)sub (user's id), iss (issuer) and aud (audience)
profileuser profile info, include name, displayName, avatar
emailuser's email address
addressuser's address
phoneuser's phone number
info

Your OAuth Application can request the scopes in the initial redirection. You can specify multiple scopes by separating them with a space using %20:

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

For more details, please see OIDC standard

After your user has authenticated with casdoor, casdoor will redirect him to: 

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

Now that you have obtained the authorization code, make a POST request to:

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

in your backend application:

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

You will get the following response:

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

Casdoor also supports PKCE feature, when getting the authorization code, you can add two parameters to enable PKCE:

&code_challenge_method=S256&code_challenge=YOUR_CHANLLENGE

When getting the token you need to pass code_verifier parameter to verify PKCE. It is worth mentioning that with PKCE enabled, Client_Secret is not required, but if you pass it, it must be the correct value.

Implicit Grant​

Maybe your application doesn't have a backend, and you need to use Implicit Grant. First you need to make sure you have Implicit Grant enabled, then redirect your users to:

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

After your user has authenticated with casdoor, casdoor will redirect him to:

https://REDIRECT_URI/#token=ACCESS_TOKEN

Casdoor also supports id_token as response_type, which is a feature of OpenID.

Resource Owner Password Credentials Grant​

If your application doesn't have a frontend that redirects users to Casdoor, then you may need this.

First you need to make sure you have Password Credentials Grant enabled, and send a POST request to:

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​

You can also use Client Credentials Grant when your application does not have a frontend.

First you need to make sure you have Client Credentials Grant enabled, and send a POST request to https://<CASDOOR_HOST>/api/login/oauth/access_token:

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

You will get the following response:

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

It is important to note that the AccessToken obtained in this way differs from the first three in that it corresponds to the application rather than to the user.

RefreshToken​

Maybe you want to update your accessToken, then you can use the refreshToken you got above.

First you need to set the expiration time of refreshToken in the application (default is 0 hours), and send a POST request to https://<CASDOOR_HOST>/api/login/oauth/refresh_token

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

You will get the response like:

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

How to verify AccessToken​

Casdoor currently has support for token introspection endpoint. Currently the endpoind is protected by Basic Authoritarian(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

You will get the following response like:

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

How to use AccessToken​

You can use AccessToken to access Casdoor APIs that require authentication.

For example, two different ways to request /api/userinfo.

Type 1. Query parameter

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

Type 2. HTTP Bearer token

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

Casdoor will parse the access_token, returning corresponding user information according to the scope. You will get the same response like:

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

If you expect more user's information, adding scope when getting AccessToken in step Authorization Code Grant.

Differences between userinfo and get-account APIs​

  • /api/userinfo: returns user information as part of OIDC protocol. Less information is returned, including only the basic information in OIDC standards. Please see available scopes that Casdoor supports.

  • /api/get-account: gets the user object for the currently logged-in account. It is a Casdoor-only API to obtain all information of the user in Casdoor.