OAuth 2.0

はじめに

Casdoorは、クライアントを認証するためにAccessTokenを使用することをサポートしています。 このセクションでは、AccessTokenの取得方法、AccessTokenの検証方法、およびAccessTokenの使用方法をご紹介します。

AccessTokenの取得方法

AccessTokenを取得する方法は2つあります：Casdoor SDKsを使用することができます。 詳細については、SDKのドキュメントを参照してください。 ここでは、APIを使用してAccessTokenを取得する方法を主にご紹介します。

Casdoorは、認可コードグラント、インプリシットグラント、リソースオーナーパスワードクレデンシャルグラント、クライアントクレデンシャルグラントの4種類のOAuthグラントタイプをサポートしています。

セキュリティ上の理由から、Casdoorアプリはデフォルトで認可コードモードがオンになっています。 他のモードを使用する必要がある場合は、適切なアプリで設定してください。

認可コードグラント

まず、ユーザーを以下にリダイレクトしてください：

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

利用可能なスコープ

名前	説明
openid (no scope)	sub（ユーザーのID）、iss（発行者）、およびaud（聴衆）
profile	ユーザープロファイル情報、名前、表示名、アバターを含む
email	ユーザーのメールアドレス
address	ユーザーの住所
phone	ユーザーの電話番号

情報

OAuthアプリケーションは、初期のリダイレクトでスコープを要求することができます。 スペースを使用して%20で区切ることにより、複数のスコープを指定することができます：

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

詳細については、OIDC標準をご覧ください

Casdoorでユーザーが認証された後、Casdoorは以下にリダイレクトします：

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

認可コードを取得したら、以下にPOSTリクエストを行ってください：

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

バックエンドアプリケーションで：

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

次のようなレスポンスが得られます：

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

注

Casdoorは、PKCE機能もサポートしています。 認可コードを取得する際に、PKCEを有効にするために2つのパラメータを追加することができます：

&code_challenge_method=S256&code_challenge=YOUR_CHANNELLENGE

トークンを取得する際には、PKCEを検証するためにcode_verifierパラメータを渡す必要があります。 PKCEが有効になっている場合、Client_Secretは必要ありませんが、渡す場合は正しい値である必要があります。

インプリシットグラント

もしかすると、あなたのアプリケーションにはバックエンドがなく、インプリシットグラントを使用する必要があるかもしれません。 まず、インプリシットグラントが有効になっていることを確認し、次にユーザーを以下にリダイレクトしてください：

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

Casdoorでユーザーが認証された後、Casdoorは以下にリダイレクトします：

https://REDIRECT_URI/#access_token=ACCESS_TOKEN

Casdoorは、id_tokenをresponse_typeとしてサポートしており、これは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.

リソースオーナーパスワードクレデンシャルグラント

もしアプリケーションにフロントエンドがなく、ユーザーをCasdoorにリダイレクトするものがない場合、これが必要になるかもしれません。

まず、パスワードクレデンシャルグラントが有効になっていることを確認し、POSTリクエストを以下に送信してください：

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

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

次のようなレスポンスが得られます：

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

クライアントクレデンシャルグラント

また、アプリケーションにフロントエンドがない場合は、クライアントクレデンシャルグラントを使用することもできます。

まず、クライアントクレデンシャルグラントが有効になっていることを確認し、POSTリクエストをhttps://<CASDOOR_HOST>/api/login/oauth/access_tokenに送信してください：

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

次のようなレスポンスが得られます：

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

この方法で取得したAccessTokenは、最初の3つと異なり、ユーザーではなくアプリケーションに対応しているという点に注意が必要です。

リフレッシュトークン

AccessTokenを更新したい場合は、上記で取得したrefreshTokenを使用できます。

まず、アプリケーションでリフレッシュトークンの有効期限を設定し（デフォルトは0時間）、POSTリクエストをhttps://<CASDOOR_HOST>/api/login/oauth/refresh_tokenに送信してください

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

このようなレスポンスが得られます：

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

AccessTokenの検証方法

Casdoorは現在、トークン内省エンドポイントをサポートしています。 このエンドポイントはBasic認証（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

次のようなレスポンスを受け取ります：

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

AccessTokenの使用方法

CasdoorのAPIにアクセスするために、認証が必要な場合はAccessTokenを使用できます。

例えば、/api/userinfoをリクエストするには2つの異なる方法があります。

タイプ1：クエリパラメータ

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

タイプ2：HTTPベアラートークン

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

Casdoorはaccess_tokenを解析し、scopeに応じて対応するユーザー情報を返します。 同じレスポンスを受け取りますが、このように見えます：

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

より多くのユーザー情報を期待する場合は、ステップ認可コードグラントでAccessTokenを取得する際にscopeを追加してください。

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.

userinfoとget-accountAPIの違い

• /api/userinfo：このAPIはOIDCプロトコルの一部としてユーザー情報を返します。 OIDC標準で定義されている基本情報のみを含む限定的な情報を提供します。 Casdoorでサポートされている利用可能なスコープのリストについては、利用可能なスコープセクションを参照してください。

• /api/get-account：このAPIは、現在ログインしているアカウントのユーザーオブジェクトを取得します。 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.