メインコンテンツにスキップ

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の機能です。

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

もしアプリケーションにフロントエンドがなく、ユーザーを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を追加してください。

userinfoとget-accountAPIの違い​

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

  • /api/get-account：このAPIは、現在ログインしているアカウントのユーザーオブジェクトを取得します。 これはCasdoor固有のAPIであり、Casdoor内のユーザーのすべての情報を取得することができます。