OAuth2 プロバイダモジュールリファレンス

OAuth2 プロバイダモジュールを使用すると、Mule アプリケーションを OAuth2 ダンスの認証マネージャとして設定できます。 この役割を持つことで、アプリケーションは、既に登録済みのクライアントの認証、トークンの付与、トークンの検証、クライアントの登録と削除のすべてをフローの実行中に行うことができます。

  • 次のドキュメントは、読者が OAuth2 認証プロトコルに関する基本的な知識を持っていることを前提としています。このプロトコルについてよく知らない場合は、 RFC-6749 で RFC 仕様を参照できます。

  • アプリケーションを OAuth2 ダンスのクライアント​として動作させる必要がある場合は、OAuth モジュールを使用する必要があります。

  • この製品の API は、テスト目的のみで提供され、サービスレベル契約によって保証されません。

OAuth ダンスは HTTP を使用して実行されるため、OAuth2 プロバイダは Mule HTTP コネクタを使用します。

そのため、Mule アプリケーションには、OAuth2 プロバイダ設定の定義以外に、プロバイダが使用する HTTP リスナ設定も必要です。

設定が完了すると、プロバイダは次のように動作します。

認証コードとトークン要求をリスンするために 2 つの HTTP エンドポイントが OAuth2 定義に従って作成されます。これらは Mule アプリケーションとは独立して動作し、HTTP を使用して応答します。

それ以外に、プロバイダはトークンが認証済みかどうかを確認する Validate Token 操作を定義します。この操作は、フローの任意の場所に追加して実行を制御することができます。トークンが認証済みであればフローはペイロードのトークン情報を設定して実行を続行し、認証済みでない場合は TOKEN_UNAUTHORIZED エラーが発生します。アプリケーションでトークン認証が必要な部分には、この操作を追加する必要があります。

また、ほとんどの場合、トークン検証は HTTP リスナと併せて使用されるので、失敗した場合はリスナの応答メカニズムによってエラーを処理し、リクエスタに適切に応答することができます。この種類のエラーを処理するために追加ロジックを追加することができます。

最後に、必要に応じてクライアントの追加または削除やトークンの取り消しを行う追加操作が提供されます。

設定

全般設定

 <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>

パラメータ

名前 説明 デフォルト値 必須

Name (名前)

String (文字列)

OAuth2 プロバイダの名前

 

x 

Provider Name (プロバイダ名)

String (文字列)

API の顧客に提供される名前。これは、OAuth2 API の一部の応答に使用されます。

Name (名前) と同じ

 

Listener Config (リスナ設定)

String (文字列)

トークンエンドポイントと認証エンドポイントを処理する HTTP リスナ設定の参照用の名前。

 

x 

Resource Owner Security Provider (リソース所有者セキュリティプロバイダ)

String (文字列)

リソース所有者を認証するために使用されるセキュリティプロバイダへの参照。CLIENT_CREDENTIALS 許可種別のみが使用される場合は不要です。

 

 

Client Security Provider (クライアントセキュリティプロバイダ)

String (文字列)

クライアントを認証するために使用されるセキュリティプロバイダへの参照。公開クライアントまたは非公開クライアントとシークレットのみを使用する場合は不要です。

 

 

Token Generator Strategy (トークン生成戦略)

String (文字列)

アクセストークンとして付与されるトークンを作成するために使用されるトークン生成戦略への参照。

UUID エンコードされたトークンを生成するデフォルトの戦略。

 

Client Store (クライアントストア)

Object Store (オブジェクトストア)

グローバルに定義されたオブジェクトストアまたは非公開オブジェクトストアの定義への参照。登録されたクライアント情報を保存するために使用されます。

オブジェクトストアマネージャによって作成されるオブジェクトマネージャ

 

Grant Types (許可種別)

String (文字列)

サポートされる許可種別のカンマ区切りリスト。可能な値: AUTHORIZATION_CODE、IMPLICIT,RESOURCE_OWNER_PASSWORD_CREDENTIALS、CLIENT_CREDENTIALS

AUTHORIZATION_CODE

 

Scopes (スコープ)

String (文字列)

サポートされるスコープのカンマ区切りリスト。

 

 

Default Scopes (デフォルトスコープ)

String (文字列)

クライアントが独自のスコープ囲を定義しなかった場合に適用されるスコープのカンマ区切りリスト。

 

 

Client Validation Rate Limiter (クライアント検証レートリミッタ)

Client Validation Rate Limiter (クライアント検証レートリミッタ)

クライアント検証操作へのアクセスを制御するレートリミッタ。特定の期間内の失敗コールが最大数を超えないように制御します。失敗がその数に達すると、それ以降の要求は拒否されます。

時間 = 600 秒で最大失敗数 = 5 の期間レートリミッタ

 

Authorization Config (認証設定)

Authorization Config (認証設定)

認証コード処理に関する設定。

 

 

Token Config (トークン設定)

Token Config (トークン設定)

トークン処理に関する設定。

 

 

セキュリティプロバイダ

全般設定 で前述したように、アプリケーション内で 2 つのセキュリティプロバイダを定義して、後で OAuth2 設定要素によって参照されるようにする必要があります。

これを実行する方法の 1 つは、Spring Framework を使用して両方のセキュリティプロバイダを定義し、次のように Spring モジュールを使用して 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>

クライアント検証レートリミッタ

無効なログイン情報を使用している場合にクライアントが連続して検証することを防ぐメカニズムを設定できます。

現時点では、期間に基づいてレート制限を処理する period-rate-limiter のみが実装されています。

パラメータ

名前 説明 デフォルト値 必須

Duration (時間)

Number (数値)

レートリミッタをリセットするまでに待機する時間。つまり、 duration (時間) の長さの間は、クライアント検証が失敗するたびに、それが失敗数に追加されます。

600

 

Duration Time Unit (時間単位)

Time Unit (時間単位)

duration (時間) 属性の時間単位。

SECONDS (秒)

 

Maximum Failure Count (最大失敗数)

Number (数値)

要求が先制的に拒否されるまでに、時間内に許容される最大失敗数。

5

 

認証コードの設定

認証コード処理と認証エンドポイントに関連する設定です。

パラメータ

名前 説明 デフォルト値 必須

Login Page (ログインページ)

String (文字列)

リソース所有者がログイン情報を提供するための Web ページへの相対ファイルパス。
デフォルトページを使用しない場合は、設定した HTML 内で参照される外部ファイルを処理する必要があります。それらは OAuth プロバイダでは処理されません。
たとえば、ログインページの HTML が外部の .css スタイルファイルを参照する場合、そのファイルを提供するエンドポイントが存在する必要があります。「http:load-static-resource」 を参照してください。

www-static/auth.html

 

Path (パス)

String (文字列)

認証要求をリスンするための HTTP サーバの認証エンドポイントへの URL の相対パス。

/authorize

 

Authorization Code Store (認証コードストア)

Object Store (オブジェクトストア)

グローバルに定義されたオブジェクトストアまたは非公開オブジェクトストアの定義への参照。生成された認証コードを保存するために使用されます。

エントリ TTL を 600 SECONDS (600 秒) に設定して ObjectStoreManager から作成された永続的なオブジェクトストア。

 

トークンの設定

トークン処理とトークンエンドポイントに関連する設定です。

パラメータ

名前 説明 デフォルト値 必須

Path (パス)

String (文字列)

トークン要求をリスンするための HTTP サーバのトークンエンドポイントへの URL の相対パス。

/token

 

Token Store (トークンストア)

Object Store (オブジェクトストア)

生成されたトークンを保存するためのグローバルに定義されたオブジェクトストアまたは非公開オブジェクトストアの定義への参照。

エントリ TTL を 86400 SECONDS (86400 秒) に設定した永続的なオブジェクトストア。

 

Token Ttl (トークン TTL)

Number (数値)

付与されたトークンが付与後に有効とみなされる時間。トークンストアのカスタム entryTtl が設定されている場合は、この値を同じにする必要があります。

86400

 

Token Ttl Time Unit (トークン TTL 時間単位)

Time Unit (時間単位)

トークン TTL に使用する時間単位。トークンストアのカスタム entryTtlTimeUnit が設定されている場合は、この値を同じにする必要があります。

SECONDS (秒)

 

Refresh Token Strategy (更新トークン戦略)

Refresh Token Strategy (更新トークン戦略)

すべてのトークン要求での更新トークンの処理方法を設定します。

No Refresh Token (更新トークンなし)

 

Refresh Token Strategy (更新トークン戦略)

更新トークン戦略では、更新トークンを付与する方法と、更新トークン要求が実行されるたびに更新トークンを処理する方法を設定します。

No Refresh Token (更新トークンなし)

すべてのアクセストークンに更新トークンが付与されません。その結果、更新トークン要求を受信すると、それは常に拒否されます。

Single Refresh Token (単一更新トークン)

新しいアクセストークンが付与されるたびに、1 つの更新トークンがそれに関連付けられます。アクセストークンを更新するたびに同じ更新トークンを使用する必要があります。

パラメータ
名前 説明 デフォルト値 必須

Object Store (オブジェクトストア)

Object Store (オブジェクトストア)

生成された更新トークンを保存するためのグローバルに定義されたオブジェクトストアまたは非公開オブジェクトストアの定義への参照。

エントリ TTL を 86400 SECONDS (86400 秒) に設定して ObjectStoreManager から作成された永続的なオブジェクトストア。

 

Multiple Refresh Token (複数更新トークン)

更新トークン要求が実行されるたびに新しい更新トークンが生成されます。その後、以前の更新トークンは無効になります。

パラメータ
名前 説明 デフォルト値 必須

Object Store (オブジェクトストア)

Object Store (オブジェクトストア)

生成された更新トークンを保存するためのグローバルに定義されたオブジェクトストアまたは非公開オブジェクトストアの定義への参照。

エントリ TTL を 86400 SECONDS (86400 秒) に設定して ObjectStoreManager から作成された永続的なオブジェクトストア。

 

クライアント

<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>

トークンを要求する権限があるすべての登録済みクライアント。リストは、実行時に Create Client 操作と Delete Client 操作によって変更できます。

各登録済みクライアントには、次の情報が設定されたエントリがあります。

パラメータ

名前 説明 デフォルト値 必須

Config (設定)

String (文字列)

トークン検証に使用するグローバルに定義された OAuth プロバイダの名前。

 

x 

Client Id (クライアント ID)

String (文字列)

作成されたクライアントに割り当てる ID

 

x 

Client Name (クライアント名)

String (文字列)

クライアントのわかりやすい名前

 

 

Principal (プリンシパル)

String (文字列)

一部のセキュリティプロバイダではクライアントユーザ名に clientId を使用できません。そのような場合は、認証にクライアントのプリンシパルが使用されます。

 

 

Description (説明)

String (文字列)

クライアントの短い説明。

 

 

Type (種類)

Client Type (クライアントの種類)

クライアントの種類。有効な値は、PUBLIC (公開) (クライアントはログイン情報の機密性を維持できない) または CONFIDENTIAL (機密) (クライアントはログイン情報の機密性を維持できる) です。

PUBLIC (公開)

 

Secret (シークレット)

String (文字列)

認証に使用されるクライアントのシークレット (パスワード)。

 

クライアントの種類が CONFIDENTIAL の場合のみ。

Client Redirect Uris (クライアントリダイレクト URI)

Redirect Uri (リダイレクト URI)

クライアントの要求に使用する 1 つまたは複数のリダイレクト URI

空のリスト

 

Client Authorized Grant Types (クライアント承認済み許可種別)

Authorized Grant Type (承認済み許可種別)

クライアントに承認された許可種別。可能な値: AUTHORIZATION_CODE、REFRESH_TOKEN、TOKEN、PASSWORD、CLIENT_CREDENTIALS。

空のリスト

 

Client Scopes (クライアントスコープ)

Client Scope (クライアントスコープ)

クライアントがトークンを要求する 1 つまたは複数のクライアントスコープ。何も指定しないと、全般設定 のデフォルトスコープが使用されます。

空のリスト

 

Client Redirect Uris (クライアントリダイレクト URI)、Client Authorized Grant Types (クライアント認証許可種別)、または Client Scopes (クライアントスコープ) の新しい値ごとに、次の例のように新しい XML タグで指定する必要があります。

<oauth2-provider:client-redirect-uri value="http://fake/redirect"/>

<oauth2-provider:client-authorized-grant-type value="AUTHORIZATION_CODE"/>

<oauth2-provider:client-scope value="USER"/>

操作

Validate Token

<oauth2-provider:validate-token config="OAuthProviderConfiguration"
                                token="#[vars.accessToken]"
                                scopes="#[vars.scopes]"
                                resourceOwnerRoles=#[vars.resourceOwnerRoles]/>

指定したトークンが付与済みで有効な状態であることを検証します。また、定義されている場合は、トークンスコープやリソース所有者ロールが指定されたものと一致しているかどうかもチェックします。

指定したトークンが有効であれば、次の情報を含むペイロードが JSON として設定されます。

キー 常時

expires_in

トークンが無効とみなされるまでの残り時間 (秒)。

はい

scope

トークンに関連付けられたスコープ (スペース区切り)。

はい

client_id

このトークンを要求したクライアントの ID。

存在する場合のみ

username

このトークンが要求されることを承認したリソース所有者のユーザ名。

存在する場合のみ

操作を実行する前にペイロードセットを保持するには、ペイロードを上書きせずに、属性 targettargetValue を使用して、この JSON 情報を変数に設定できます。

パラメータ

名前 説明 デフォルト値 必須

Config (設定)

String (文字列)

トークン検証に使用するグローバルに定義された OAuth プロバイダの名前。

 

x 

Token (トークン)

Expression (式)

検証するトークンに解決される式。トークンを探すデフォルトの場所は 'authorization' HTTP の最初の値にあります。

#[(attributes.headers['authorization'] splitBy ' ')[1]]

 

Scopes (スコープ)

Expression (式)

トークンを検証するときに適用するスコープのリストに解決される式。

空のリスト

 

Resource Owner Roles (リソース所有者ロール)

Expression (式)

トークンを検証するときに適用するリソース所有者ロールのリストに解決される式。

空のリスト

 

発生

OAUTH2-PROVIDER:TOKEN_UNAUTHORIZED(OAUTH_SERVER_SECURITY)

  検証されるトークンが有効でない場合。

Revoke Token

<oauth2-provider:revoke-token  config="OAuthProviderConfiguration"
                               token="#[vars.token]"/>

既存のアクセストークンとそれに関連する更新トークンを取り消します。いずれかを指定して両方を取り消すことができます。

パラメータ

名前 説明 デフォルト値 必須

Config (設定)

String (文字列)

トークン検証に使用するグローバルに定義された OAuth プロバイダの名前。

 

x 

Token (トークン)

String (文字列)

取り消されるトークン

 

x 

発生

OAUTH2-PROVIDER:INVALID_TOKEN(OAUTH_SERVER_SECURITY)

  取り消されるトークンが有効でない場合。

Create Client

<oauth2-provider:create-client config="OAuthProviderConfiguration"
                               clientId="#[payload.clientId]"
                               clientName="#[payload.clientName]"
                               principal="#[payload.clientPrincipal]"
                               description="#[payload.clientDescription]"
                               type="#[payload.clientType]"
                               secret="#[payload.clientSecret]"
                               redirectUris="#[payload.redirectUris]"
                               authorizedGrantType="#[payload.authorizedGrantTypes]"
                               scopes="#[payload.scopes]"
                               failIfPresent="false"/>

パラメータ

名前 説明 デフォルト値 必須

Config (設定)

String (文字列)

トークン検証に使用するグローバルに定義された OAuth プロバイダの名前。

 

x 

Client Id (クライアント ID)

String (文字列)

作成されたクライアントに割り当てる ID

 

x 

Client Name (クライアント名)

String (文字列)

クライアントのわかりやすい名前

 

 

Principal (プリンシパル)

String (文字列)

一部のセキュリティプロバイダではクライアントユーザ名に clientId を使用できません。そのような場合は、認証にクライアントのプリンシパルが使用されます。

 

 

Description (説明)

String (文字列)

クライアントの短い説明。

 

 

Type (種類)

Client Type (クライアントの種類)

クライアントの種類。有効な値は、PUBLIC (公開) (クライアントはログイン情報の機密性を維持できない) または CONFIDENTIAL (機密) (クライアントはログイン情報の機密性を維持できる) です。

PUBLIC (公開)

 

Secret (シークレット)

String (文字列)

認証に使用されるクライアントのシークレット (パスワード)。

 

クライアントの種類が CONFIDENTIAL の場合のみ。

Redirect Uris (リダイレクト URI)

Expression (式)

クライアントが OAuth プロバイダに要求を実行するときに使用されるリダイレクト URI のリストに解決される式。

空のリスト

 

Authorized Grant Types (承認済み許可種別)

Expression (式)

クライアントがトークンを要求するために使用できる承認済みの許可種別のリストに解決される式。可能な値: AUTHORIZATION_CODE、REFRESH_TOKEN、TOKEN、PASSWORD、CLIENT_CREDENTIALS。

空のリスト

 

Scopes (スコープ)

Expression (式)

クライアントがサポートするスコープのリストに解決される式。何も指定しないと、全般設定 のデフォルトスコープが使用されます。

空のリスト

 

Fail if Present (存在する場合は失敗)

Boolean (ブール)

同じ ID のクライアントがすでに登録されている場合の処理を定義します。true の場合はエラーが発生します。そうでない場合は、クライアントが更新されます。

false

 

発生

  • OAUTH2-PROVIDER:CLIENT_ALREADY_EXISTS(OAUTH_SERVER_SECURITY)

      同じクライアント ID のクライアントがすでに存在する場合、フラグ failIfPresent が true に設定されます。

  • INVALID_CONFIGURATION

      指定したパラメータが有効でない場合。authorizationGrantType が AUTHORIZATION_CODE で、リダイレクト URI がないなど。

Delete Client

指定した ID のクライアントを削除します。その結果、削除されたクライアントからの新しい要求は拒否され、そのクライアントに付与されたトークンは無効になります。

パラメータ

名前 説明 デフォルト値 必須

Config (設定)

String (文字列)

トークン検証に使用するグローバルに定義された OAuth プロバイダの名前。

 

x 

Client Id (クライアント ID)

String (文字列)

削除するクライアントの ID。

 

x  

発生

OAUTH2-PROVIDER:NO_SUCH_CLIENT(OAUTH_SERVER_SECURITY)

  削除されるクライアントが存在しない場合。

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub