OAuth2 Provider Module 1.2 リファレンス
OAuth2 Provider Module を使用すると、Mule Runtime Engine (Mule) アプリケーションを OAuth2 ダンスの認証マネージャーとして設定できます。 この役割を持つことで、アプリケーションは、既に登録済みのクライアントの認証、トークンの付与、トークンの検証、クライアントの登録と削除のすべてをフローの実行中に行うことができます。
設定
デフォルト設定
OAuth2 Provider Module 設定
パラメーター
| 名前 | 型 | 説明 | デフォルト値 | 必須 |
|---|---|---|---|---|
Name (名前) |
String (文字列) |
この設定の名前。コネクタはこの名前の設定を参照します。 |
x |
|
Provider Name (プロバイダー名) |
String (文字列) |
API の顧客に提供されるプロバイダー名。これは、OAuth2 API の一部の応答に使用されます。 |
||
リスナー設定 |
String (文字列) |
トークンエンドポイントと認証エンドポイントを処理する HTTP リスナー設定の参照用の名前。 |
x |
|
クライアント検証レートリミッター |
特定の操作へのアクセスを制御するために使用されるレートリミッター。指定されていない場合、PeriodRateLimiter がデフォルトとして使用されます。 |
|||
Client Store (クライアントストア) |
Object Store (オブジェクトストア) |
シークレットなどのクライアント設定情報を取得できるストア。クライアントストアが指定されていない場合は、デフォルトのメモリ内オブジェクトストアが設定されます。 |
||
Resource Owner Security Provider (リソースオーナーセキュリティプロバイダー) |
String (文字列) |
リソースオーナーを認証するために使用されるセキュリティプロバイダー。CLIENT_CREDENTIALS 許可種別のみが使用される場合は不要です。Spring Module の例は、「OAuth2 プロバイダーの移行」を参照してください。 |
||
Client Security Provider (クライアントセキュリティプロバイダー) |
String (文字列) |
クライアントを認証するために使用されるセキュリティプロバイダー。公開クライアントまたは非公開クライアントとシークレットのみを使用する場合は不要です。 |
||
Token Generator Strategy (トークンジェネレーター戦略) |
TokenGeneratorStrategy |
アクセストークンを生成するために使用される戦略。TokenGeneratorStrategy を実装するクラスを参照する必要があります。 |
||
Supported Grant Types (サポートされる付与種別) |
Enumeration (列挙)。次のいずれかになります。
|
このプロバイダーでサポートするカンマ区切りの許可種別。何も指定されていない場合、認証コード許可種別のみがサポートされます。 |
AUTHORIZATION_CODE |
|
Scopes (スコープ) |
String (文字列) |
サポートされるスコープのカンマ区切りリスト。 |
||
Default Scopes (デフォルトスコープ) |
String (文字列) |
何も定義されていない場合にクライアントに設定されるデフォルトスコープのカンマ区切りリスト。 |
||
Token Config (トークン設定) |
トークン関連の動作を設定するための情報。 |
|||
Authorization Config (認証設定) |
認証処理動作を設定するための情報 |
|||
Clients (クライアント) |
Client (クライアント) の配列 |
クライアントのリスト。 |
||
Expiration Policy (有効期限ポリシー) |
動的設定インスタンスがアイドル状態を続けられる最小時間を設定します。この時間が経過すると、Mule Runtime で期限切れに相当するとみなされます。これは、インスタンスが有効期限の対象となった瞬間にプラットフォームでそのインスタンスが期限切れになるということではありません。必要に応じて、インスタンスがパージされます。 |
操作
Create Client
<oauth2-provider:create-client>
新しいクライアントを作成して、設定したクライアントストアに保存します。
<oauth2-provider:create-client
doc:name="Create client"
config-ref="OAuth2_Provider_Config"
clientId="#[payload.clientId]"
secret="#[payload.clientSecret]"
clientName="#[payload.clientName]"
description="#[payload.clientDescription]"
principal="#[payload.clientPrincipal]"
redirectUris="#[payload.redirectUris]"
authorizedGrantTypes="#[payload.authorizedGrantTypes]"
scopes="#[payload.scopes]"
type="PUBLIC"
failIfPresent="false"/>パラメーター
| 名前 | 型 | 説明 | デフォルト値 | 必須 |
|---|---|---|---|---|
Configuration (設定) |
String (文字列) |
トークン検証に使用するグローバルに定義された OAuth プロバイダーの名前。 |
x |
|
Client Id (クライアント ID) |
String (文字列) |
作成されたクライアントに割り当てる ID。 |
x |
|
Type (種別) |
Enumeration (列挙)。次のいずれかになります。
|
クライアントの種類。有効な値は、PUBLIC (公開) (クライアントはログイン情報の機密性を維持できない) または CONFIDENTIAL (機密) (クライアントはログイン情報の機密性を維持できる) です。 |
PUBLIC |
|
Secret (シークレット) |
String (文字列) |
|||
Client Name (クライアント名) |
String (文字列) |
クライアントのわかりやすい名前。 |
||
Description (説明) |
String (文字列) |
クライアントの簡単な説明。 |
||
Principal (プリンシパル) |
String (文字列) |
セキュリティプロバイダーで ID を使用できない場合に使用する省略可能なプリンシパル。 |
||
Redirect Uris (リダイレクト URI) |
Array of String (文字列の配列) |
クライアントが OAuth プロバイダーに要求を実行するときに使用されるリダイレクト URI のリストに解決される式。 |
||
Authorized Grant Types (認証済み許可種別) |
Array of Enumeration (列挙の配列)。次のいずれかになります。
|
クライアントがトークンを要求するために使用できる認証済みの許可種別のリストに解決される式。 |
||
Scopes (スコープ) |
Array of String (文字列の配列) |
クライアントがサポートするスコープのリストに解決される式。何も指定しないと、全般設定 のデフォルトスコープが使用されます。 |
||
Fail If Present (存在する場合は失敗) |
Boolean (ブール) |
同じ ID のクライアントがすでに登録されている場合の処理を定義します。 |
|
Revoke Token
<oauth2-provider:revoke-token>
アクセストークンまたは更新トークンを失効させ、関連する更新トークンまたはアクセストークンも無効化します。クライアントログイン情報を検証する必要がある場合、トークンを失効させる前に validateClient ログイン情報を使用します。
Validate Token
<oauth2-provider:validate-token>
有効なアクセストークンが指定されているかどうかをチェックします。指定したトークンが付与済みで有効な状態であることを検証します。また、定義されている場合は、トークンスコープやリソースオーナーロールが指定されたものと一致しているかどうかもチェックします。
指定したトークンが有効であれば、次の情報を含むペイロードが JSON として設定されます。
-
expires_in:
トークンが無効とみなされるまでの残り時間 (秒)。
-
scope:
トークンに関連付けられたスコープ (スペース区切り)。
-
client_id:
このトークンを要求したクライアントの ID。
-
username:
このトークンが要求されることを認証したリソースオーナーのユーザー名。
操作を実行する前にペイロードセットを保持するには、ペイロードを上書きせずに、target および targetValue 属性を使用して、JSON 情報を変数に設定します。
Validate Token のパラメーターを次に示します。
パラメーター
| 名前 | 型 | 説明 | デフォルト値 | 必須 |
|---|---|---|---|---|
Configuration (設定) |
String (文字列) |
使用する設定の名前。 |
x |
|
Access Token (アクセストークン) |
String (文字列) |
#[(attributes.headers['authorization'] splitBy ' ')[1]] |
||
Scopes (スコープ) |
Array of String (文字列の配列) |
トークンを検証するときに適用するスコープのリストに解決される式。 |
||
Resource Owner Roles (リソースオーナーロール) |
Array of String (文字列の配列) |
トークンを検証するときに適用するリソースオーナーロール。これは、トークンを検証するときに適用するリソースオーナーロールのリストに解決される式です。 |
||
Target Variable (対象変数) |
String (文字列) |
操作の出力を保存する変数の名前。 |
||
Target Value (対象値) |
String (文字列) |
操作の出力に対して評価される式。この式の結果が対象変数に保存されます。 |
#[payload] |
型
トークンの設定
トークン処理とトークンエンドポイントに関連する設定です。
| 項目 | 型 | 説明 | デフォルト値 | 必須 |
|---|---|---|---|---|
Path (パス) |
String (文字列) |
新しいトークンを要求するときにコールするエンドポイント。 |
/token |
|
Token Store (トークンストア) |
Object Store (オブジェクトストア) |
トークン関連のデータを保存するための ObjectStore 設定情報。 |
||
Refresh Token Strategy (更新トークン戦略) |
使用する更新トークン戦略。デフォルトでは、更新トークンは生成されません。 |
|||
Token Ttl (トークン TTL) |
Number (数値) |
アクセストークンコードの有効期限が切れるまでの秒数。 |
86400 |
|
Token Ttl Time Unit (トークン TTL 時間単位) |
Enumeration (列挙)。次のいずれかになります。
|
トークン TTL の時間単位。 |
SECONDS |
Authorization Config (認証設定)
認証コード処理と認証エンドポイントに関連する設定です。
| 項目 | 型 | 説明 | デフォルト値 | 必須 |
|---|---|---|---|---|
Login Page (ログインページ) |
String (文字列) |
リソースオーナーがログイン情報を提供するための Web ページへの相対ファイルパス。 |
www-static/auth.html |
|
Path (パス) |
String (文字列) |
認証要求をリスンするための HTTP サーバーの認証エンドポイントへの URL の相対パス。 |
/authorize |
|
Authorization Code Store (認証コードストア) |
Object Store (オブジェクトストア) |
グローバルに定義されたオブジェクトストアまたは非公開オブジェクトストアの定義への参照。生成された認証コードを保存するために使用されます。 |
エントリ TTL を 600 SECONDS (600 秒) に設定して ObjectStoreManager から作成された永続的なオブジェクトストア。 |
Client (クライアント)
トークンを要求する権限があるすべての登録済みクライアント。リストは、実行時に Create Client 操作と Delete Client 操作によって変更できます。
<oauth2-provider:clients>
<oauth2-provider:client
clientId="clientId1"
clientName="someClient"
secret="clientSecret1"
principal="clusr"
description="Some test client"
type="CONFIDENTIAL">
<oauth2-provider:client-redirect-uris>
<oauth2-provider:client-redirect-uri
value="http://fake/redirect"/>
</oauth2-provider:client-redirect-uris>
<oauth2-provider:client-authorized-grant-types>
<oauth2-provider:client-authorized-grant-type
value="AUTHORIZATION_CODE"/>
</oauth2-provider:client-authorized-grant-types>
<oauth2-provider:client-scopes>
<oauth2-provider:client-scope value="USER"/>
</oauth2-provider:client-scopes>
</oauth2-provider:client>
</oauth2-provider:clients>各登録済みクライアントには、次の情報が設定されたエントリがあります。
| 項目 | 型 | 説明 | デフォルト値 | 必須 |
|---|---|---|---|---|
Client Id (クライアント ID) |
String (文字列) |
クライアントを参照するために使用される一意の ID。 |
x |
|
Principal (プリンシパル) |
String (文字列) |
セキュリティプロバイダーで ID を使用できない場合に使用する省略可能なプリンシパル。一部のセキュリティプロバイダーではクライアントユーザー名に clientId を使用できません。そのような場合は、認証にクライアントのプリンシパルが使用されます。 |
||
Client Name (クライアント名) |
String (文字列) |
クライアントの名前。 |
||
Description (説明) |
String (文字列) |
クライアントの短い説明。 |
||
Secret (シークレット) |
String (文字列) |
クライアントを認証するために使用されるクライアントシークレット。[Type (種別)] が CONFIDENTIAL の場合のみ必要です。 |
||
Client Redirect Uris (クライアントリダイレクト URI) |
Array of String (文字列の配列) |
要求の処理後にクライアントに応答するために使用する登録済みリダイレクト URI のリスト。 大部分の要求では、新しいリダイレクト URI を定義できるため、これらが常に考慮されるわけではありません。「新しい値の処理」も参照してください。
|
||
Client Authorized Grant Types (クライアント認証済み許可種別) |
Array of Enumeration (列挙の配列)。次のいずれかになります。
|
このクライアントがトークンを取得するために正常に実行できる OAuth フローを定義する許可種別。「新しい値の処理」も参照してください。 |
||
Client Scopes (クライアントスコープ) |
Array of String (文字列の配列) |
このクライアントに一致するスコープ。クライアント ID は一致するが、スコープが異なる要求を受信した場合、その要求は処理されません。「新しい値の処理」も参照してください。 |
||
Type (種別) |
Enumeration (列挙)。次のいずれかになります。
|
クライアント種別は、クライアントがそのログイン情報の機密性を維持できるかどうかを定義します。有効な値は、 |
|
クライアントリダイレクト URI、クライアント認証済み許可種別、クライアントスコープの場合、新しい XML タグにそれぞれの新しい値を指定します。
<oauth2-provider:client-redirect-uri value="http://fake/redirect"/>
<oauth2-provider:client-authorized-grant-type value="AUTHORIZATION_CODE"/>
Expiration Policy (有効期限ポリシー)
| 項目 | 型 | 説明 | デフォルト値 | 必須 |
|---|---|---|---|---|
Max Idle Time (最大アイドル時間) |
Number (数値) |
有効期限の対象とみなされるまで、動的設定インスタンスがアイドル状態を維持できる最大時間のスカラー時間値 |
||
Time Unit (時間単位) |
Enumeration (列挙)。次のいずれかになります。
|
maxIdleTime 属性の時間単位 |
No Refresh Token (更新トークンなし)
すべてのアクセストークンに更新トークンが付与されません。その結果、更新トークン要求を受信すると、それは常に拒否されます。
| 項目 | 型 | 説明 | デフォルト値 | 必須 |
|---|---|---|---|---|
Token Generator Strategy (トークンジェネレーター戦略) |
TokenGeneratorStrategy |
Single Refresh Token (単一更新トークン)
新しいアクセストークンが付与されるたびに、1 つの更新トークンがそれに関連付けられます。アクセストークンを更新するたびに同じ更新トークンを使用できます。
| 項目 | 型 | 説明 | デフォルト値 | 必須 |
|---|---|---|---|---|
Object Store (オブジェクトストア) |
Object Store (オブジェクトストア) |
生成された更新トークンを保存するためのグローバルに定義されたオブジェクトストアまたは非公開オブジェクトストアの定義への参照。オブジェクトストアはアクセストークンオブジェクトスコアとは異なる必要があります。 |
エントリ TTL を 86400 SECONDS (86400 秒) に設定して ObjectStoreManager から作成された永続的なオブジェクトストア。 |
Multiple Refresh Tokens (複数更新トークン)
更新トークン要求が実行されるたびに新しい更新トークンが生成されます。その後、以前の更新トークンは無効になります。
| 項目 | 型 | 説明 | デフォルト値 | 必須 |
|---|---|---|---|---|
Object Store (オブジェクトストア) |
Object Store (オブジェクトストア) |
生成された更新トークンを保存するためのグローバルに定義されたオブジェクトストアまたは非公開オブジェクトストアの定義への参照。オブジェクトストアはアクセストークンオブジェクトスコアとは異なる必要があります。 |
エントリ TTL を 86400 SECONDS (86400 秒) に設定して ObjectStoreManager から作成された永続的なオブジェクトストア。 |
Period Rate Limiter (期間レートリミッター)
[Period Rate Limiter (期間レートリミッター)] では、期間に基づいてレート制限を処理します。
無効なログイン情報を使用している場合にクライアントが連続して検証することを防ぐメカニズムを設定できます。
| 項目 | 型 | 説明 | デフォルト値 | 必須 |
|---|---|---|---|---|
Duration (所要時間) |
Number (数値) |
レートリミッターをリセットするまでに待機する時間。つまり、duration (時間) の長さの間は、クライアント検証が失敗するたびに、それが失敗数に追加されます。 |
600 |
|
Duration Time Unit (期間の時間単位) |
Enumeration (列挙)。次のいずれかになります。
|
SECONDS |
||
Maximum Failure Count (最大失敗数) |
Number (数値) |
要求が先制的に拒否されるまでに、時間内に許容される最大失敗数。 |
5 |
OAuth ダンス
OAuth ダンスは HTTP を使用して実行されるため、OAuth2 プロバイダーは Mule HTTP Connector を使用します。
そのため、Mule アプリケーションには、OAuth2 プロバイダー設定の定義以外に、プロバイダーが使用する HTTP リスナー設定も必要です。
設定が完了すると、プロバイダーは次のように動作します。
認証コードとトークン要求をリスンするために 2 つの HTTP エンドポイントが OAuth2 定義に従って作成されます。これらは Mule アプリケーションとは独立して動作し、HTTP を使用して応答します。
プロバイダーはトークンが認証済みかどうかを確認する Validate Token 操作を定義します。この操作は、フローの任意の場所に追加して実行を制御することができます。トークンが認証済みであれば、フローはペイロードのトークン情報を設定して実行を続行し、認証済みでない場合は TOKEN_UNAUTHORIZED エラーが発生します。アプリケーションでトークン認証が必要な部分には、この操作を追加する必要があります。
ほとんどの場合、トークン検証は HTTP リスナーと併せて使用されるので、失敗した場合はリスナーの応答メカニズムによってエラーを処理し、リクエスターに適切に応答することができます。この種類のエラーを処理するために追加ロジックを追加することができます。
最後に、必要に応じてクライアントの追加または削除やトークンの取り消しを行う追加操作が提供されます。
セキュリティプロバイダー
全般設定で前述したように、アプリケーション内で 2 つのセキュリティプロバイダーを定義して、後で OAuth2 設定要素によって参照されるようにする必要があります。
これを実行する方法の 1 つは、Spring Framework を使用して両方のセキュリティプロバイダーを定義し、Spring Module を使用して Mule セキュリティマネージャーにプロバイダーを追加することです。
<spring:security-manager>
<spring:delegate-security-provider
name="clientSecurityProvider"
delegate-ref="clientAuthenticationManager"/>
<spring:delegate-security-provider
name="resourceOwnerSecurityProvider"
delegate-ref="resourceOwnerAuthenticationManager"/>
</spring:security-manager>全般設定
<oauth2-provider:config
name="OAuth2Provider"
listenerConfig="httpListenerConfig"
resourceOwnerSecurityProvider="resourceOwnerSecurityProvider"
clientSecurityProvider="clientSecurityProvider"
supportedGrantTypes="AUTHORIZATION_CODE"
scopes="USER,ADMIN"
defaultScopes="USER"
clientStore="clientObjectStore">
<oauth2-provider:client-validation-rate-limiter>
<oauth2-provider:period-rate-limiter
duration="600"
durationTimeUnit="SECONDS"
maximumFailureCount="5"/>
</oauth2-provider:client-validation-rate-limiter>
<oauth2-provider:token-config
path="/token"
tokenStore="tokenObjectStore"
tokenTtl="86400"
tokenTtlTimeUnit="SECONDS">
<oauth2-provider:refresh-token-strategy>
<oauth2-single-refresh-token
objectStore="refreshTokenObjectStore"/>
</oauth2-provider:refresh-token-strategy>
</oauth2-provider:token-config>
<oauth2-provider:authorization-config
loginPage="static/auth.html"
path="/authorize"
objectStore="authorizationCodeObjectStore"/>
<oauth2-provider:clients>
<oauth2-provider:client
clientId="clientId1"
clientName="someClient"
secret="clientSecret1"
principal="clusr"
description="Some test client"
type="CONFIDENTIAL">
<oauth2-provider:client-redirect-uris>
<oauth2-provider:client-redirect-uri
value="http://fake/redirect"/>
</oauth2-provider:client-redirect-uris>
<oauth2-provider:client-authorized-grant-types>
<oauth2-provider:client-authorized-grant-type
value="AUTHORIZATION_CODE"/>
</oauth2-provider:client-authorized-grant-types>
<oauth2-provider:client-scopes>
<oauth2-provider:client-scope value="USER"/>
</oauth2-provider:client-scopes>
</oauth2-provider:client>
</oauth2-provider:clients>
</oauth2-provider:config>