Using OAuth 2.0
ご覧のページは、お客様の利便性のために一部機械翻訳されています。また、ドキュメントは頻繁に更新が加えられており、翻訳は未完成の部分が含まれることをご了承ください。最新情報は都度公開されておりますため、必ず英語版をご参照ください。翻訳に問題がある場合は、 こちら までご連絡ください。

OAuth2によるアカウントアクセスの認証

アプリケーションの登録が完了したら、ユーザーの認証を開始できます。そのためには、認証サーバー(Liferay DXP)へのURLを構築する必要があります。認証サーバーは、前回のチュートリアルで説明したようにスコープとして定義されたリソースに対する要求された権限をユーザーに承認するよう求めます。

認証コードの流れ

最も一般的なOAuthフローは、Webアプリケーションで使用される認可コードフローです。このURLには、以下のリクエストパラメータが必要です。

  • response_type
  • client_id

この認証用のURLを構築するには、次のパターンに従ってください。

https://[hostname]/o/oauth2/authorize?response_type=code&client_id=[client ID]

クライアントIDは、アプリケーション登録時に取得されます。これは自動的に生成されます(アプリケーションを編集すれば変更できます)。

ユーザーがリソースへの要求されたアクセス許可を承認すると、承認サーバーは、登録されたコールバックURI(別名リダイレクトURI)でアプリケーションに認証コードをクエリ文字列パラメーターとして返します。

[your callback URI]?code=[authorization server generated code]

アプリケーションは、以下のパターンに従ってPOSTリクエストを送信することにより、この認証コードをアクセストークンと交換する必要があります。

http://localhost:8080/o/oauth2/token
重要

「ウェブアプリケーション」という言葉は、時として曖昧に使われ、上記のURLがウェブブラウザから直接リクエストされるアプリケーションを指す場合もある。そうなると、クライアントシークレットが漏洩し、グラントフローとアプリケーションのセキュリティが損なわれることになります。このような場合は、アプリケーションを登録する際に、 User Agent Application クライアント プロファイルを選択してください。これにより、アプリケーションに安全な代替手段が提供されます。PKCE拡張認証コードフロー(下記参照)です。

リクエストの本文に以下のパラメータが含まれている場合(エンコード形式は application/x-www-form-urlencoded)…

client_id=[client ID] client_secret=[client secret] grant_type=authorization_code code=[authorization server generated code] redirect_uri=[registered callback URI]

…HTTPレスポンスの本文には、次のようなJSONが含まれています。

{
  "access_token": "[authorization server generated access token]",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "[the scopes that were authorized by the user]",
  "refresh_token": "[authorization server generated refresh token]"
}

ここからアクセストークンを抽出し、保存する必要があります。トークンを無期限に使用する場合(上記の例の600秒を超える場合)、リフレッシュトークンも必要になります。これは、リフレッシュトークンフローと組み合わせて使用することで、追加のユーザー認証なしに、同じ権限を持つ新しいアクセストークンを取得できます。認証サーバーは、アプリケーション登録がこのフローに登録されている場合にのみ、リフレッシュトークンを発行します。

重要

標準ユーザーはアクセストークンを作成できません。以下の権限を持つカスタムOAuth 2管理者ロールを使用してください。

  • コントロールパネル → セキュリティ → OAuth 2 管理: OAuth2 アプリケーションエントリ → トークンの作成
  • コントロールパネル → セキュリティ → OAuth 2 管理: OAuth2 アプリケーションエントリ → 表示

PKCE拡張認証コードフロー

このフローは、コード交換用証明鍵(PKCE)が追加されている点を除いて、上記と同じです。別のリクエストパラメータが必要です: code_challenge。このフローは、ユーザー認証後に認証サーバーによってリダイレクトされるURL(およびリクエストパラメータ)への単独アクセス権を持たない可能性のあるスマートフォンアプリケーションなどのクライアント向けです。これは、同じシステム上の悪意のあるアプリケーションが応答コードを読み取ることで自身を認証するのを防ぎます。これを行うために、クライアント アプリケーションは、認証要求とともに コード チャレンジ を送信します。これは、クライアント アプリケーションが生成し、クライアント アプリケーションのみが知っている文字列です。この文字列を生成するには、まず コード検証器と呼ばれる別の秘密の文字列を作成し、次にそれに変換を適用する必要があります。認証後、認証コードとともにコード検証ツールが送信され、クライアントの認証が行われます。

これを行う方法の詳細は、PKCE仕様を参照してください。

このフローをサポートするには、アプリケーション作成時にPKCEを許可された認証タイプとして定義しておく必要があります。これは、ネイティブアプリケーションおよびユーザーエージェントアプリケーションのクライアントプロファイルの一部です。 PKCEを使用して認証コードを要求するには、 code_challenge リクエストパラメータを含むURLを使用します。

https://[hostname]/o/oauth2/authorize?response_type=code&client_id=[client ID]&code_challenge=[PKCE code challenge]

残りのプロセスは認可コードフローと全く同じですが、アクセストークンを取得するための最終リクエストを行う際に、以下のパラメータも指定する必要があります。

code_verifier=[Code Verifier that was transformed and sent as code_challenge previously]

クライアント認証情報とリソース所有者のフロー

他に、あまり利用されていない2つのフローが存在する。 2つのサーバーが合意された、ユーザー中心でないデータを交換するシナリオがある場合は、ユーザーの[Allow/Deny]画面をバイパスして、クライアントを承認できます。これはクライアント認証情報フローと呼ばれ、次のURLパターンを使用します。

https://[hostname]/o/oauth2/token?grant_type=client_credentials&client_id=[client ID]&client_secret=[client secret]

ユーザーがアプリケーションにパスワードを預けるという最終フローは稀ではあるが、あり得る。これはリソースオーナーパスワードフローと呼ばれ、そのURLパターンは次のようになります。

https://[hostname]/o/oauth2/token?grant_type=password&client_id=[client ID]&client_secret=[client secret]&username=[user@emailaddress.com]&password=

ユーザーはパスワードの入力を求められ、ログインに成功すると認証コードを受け取ります。

トークンの使用

上記のすべてのフローの結果、認証サーバー(Liferay)からクライアントアプリケーションに送信されるアクセストークンが生成されます。このトークンは、クライアントアプリケーションが保存し、今後のデータ要求とともに送信するために、レスポンスに含めて送信されます。

例えば、認証コード 946856e2b5ddf0928f6fc55f657bab73 がクライアントアプリケーションに送信されたとします。クライアントがデータを要求する際、このコードは各リクエストヘッダーに含めて送信する必要があります。 CurlなどのコマンドラインHTTPクライアントを使用すると、次のようなリクエストを送信できます。

curl -H 'Authorization: Bearer 946856e2b5ddf0928f6fc55f657bab73' 'https://[hostname]/o/api/sample2'

ユーザーは、認証情報を共有することなく、OAuthを使用してクライアントアプリケーションに特定のサービス(スコープ)へのアクセス権を付与できます。

アクセス権の取り消し

アクセス権が付与された後は、ユーザーまたは管理者はいつでも自由にアクセス権を取り消すことができます。クライアント側でこのような事態が発生した場合、トークンは無効となり、クライアントはユーザーに再度認証を求める必要があります。これにより、ユーザーは自分のデータにアクセスできるものを制御できるようになり、いつでもその制御を行使できます。

ユーザーは、自分のアカウントプロファイル内のデータにアクセスできるアプリケーションを完全に制御できます。

アカウントエリアでは、ユーザーは マイ接続アプリケーション をクリックすると、アカウントへのアクセスを許可したアプリケーションのリストが表示されます。ここから、アクション メニューの アクセスの削除 項目をクリックするか、アプリケーションの詳細画面の アクセスの削除 ボタンをクリックすることで、アクセスを取り消すことができます。

[接続済みのアプリケーション]では、ユーザーは承認されたアプリを表示してアクセスを取り消すことができます。

グローバルメニュー (Global Menu) → コントロールパネル → OAuth 2 管理 の任意のアプリの [認証] タブで認証を表示できます。アプリが信頼されている場合、または デバイス のチェックボックスがオンになっている場合は、その情報が表示されます。

アプリのすべての権限は、アプリの[権限]タブに表示されます。

リストされているいずれかの承認の 取り消し ボタンをクリックすると、そのアプリケーションのそのユーザーのアカウントへのアクセスが取り消されます。

まとめ

ユーザーは、認証情報を共有する必要なく、OAuth 2.0による完全かつ安全な認証フローを利用できます。システム内でアプリケーションを作成すると、セキュアトークンによって特定の範囲の情報へのアクセスが可能になります。このアクセス権はいつでも取り消すことができるため、OAuth 2.0はユーザーと開発者の両方にとって、必要な情報にアクセスするための便利な方法となっている。