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

サポートカテゴリ: 選択

OAuth プロバイダモジュール v1.0

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

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

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

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

POM ファイル情報

<dependency>
<groupId>com.mulesoft.modules</groupId>
<artifactId>mule-oauth2-provider-module</artifactId>
<version>RELEASE</version>
<classifier>mule-plugin</classifier>
</dependency>

Mule は、RELEASE を現在のバージョンに変換します。バージョンを指定するには、Anypoint Exchange で OAuth プロバイダモジュール​を表示し、[Dependency Snippets (連動関係スニペット)]​ をクリックします。

設定


デフォルト設定

OAuth2 プロバイダモジュール設定

パラメータ

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

Name (名前)

String (文字列)

この設定の名前。コネクタはこの名前の設定を参照します。

x

Provider Name (プロバイダ名)

String (文字列)

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

リスナ設定

String (文字列)

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

x

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

特定の操作へのアクセスを制御するために使用されるレートリミッタ。指定されていない場合、PeriodRateLimiter がデフォルトとして使用されます。

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

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

シークレットなどのクライアント設定情報を取得できるストア。クライアントストアが指定されていない場合は、デフォルトのメモリ内オブジェクトストアが設定されます。

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

String (文字列)

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

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

String (文字列)

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

Token Generator Strategy (トークンジェネレータ戦略)

TokenGeneratorStrategy

アクセストークンを生成するために使用される戦略。TokenGeneratorStrategy を実装するクラスを参照する必要があります。

Supported Grant Types (サポートされる付与種別)

String (文字列)

このプロバイダでサポートするカンマ区切りの許可種別。何も指定されていない場合、認証コード許可種別のみがサポートされます。

AUTHORIZATION_CODE

スコープ

String (文字列)

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

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

String (文字列)

何も定義されていない場合にクライアントに設定されるデフォルトスコープのカンマ区切りリスト。

Token Config (トークン設定)

トークン関連の動作を設定するための情報。

Authorization Config (認証設定)

認証処理動作を設定するための情報

クライアント

クライアントのリスト。

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

Enumeration (列挙)。次のいずれかになります。

  • CONFIDENTIAL

  • PUBLIC

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

PUBLIC

Secret (シークレット)

String (文字列)

Client Name (クライアント名)

String (文字列)

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

説明

String (文字列)

クライアントの簡単な説明。

Principal (プリンシパル)

String (文字列)

セキュリティプロバイダで ID を使用できない場合に使用する省略可能なプリンシパル。

Redirect Uris (リダイレクト URI)

Array of String (文字列の配列)

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

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

Array of Enumeration (列挙の配列)。次のいずれかになります。

  • AUTHORIZATION_CODE​

  • REFRESH_TOKEN​

  • TOKEN

  • PASSWORD

  • CLIENT_CREDENTIALS

クライアントがトークンを要求するために使用できる認証済みの許可種別のリストに解決される式。

スコープ

Array of String (文字列の配列)

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

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

Boolean (ブール)

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

false

次の設定の場合

スロー

  • OAUTH2-PROVIDER:​CLIENT_ALREADY_EXISTS​ - 同じクライアント ID のクライアントがすでに存在し、[Fail If Present (存在する場合は失敗)]​ が true​ に設定されている場合。

  • OAUTH2-PROVIDER:​INVALID_CONFIGURATION​ - 指定したパラメータが有効でない場合。[Authorized Grant Types (認証済み許可種別)]​ が AUTHORIZATION_CODE​ だが、リダイレクト URI がないなど。

Delete Client

<oauth2-provider:delete-client>

ストアからクライアントを削除します。

パラメータ

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

Configuration (設定)

String (文字列)

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

x

Client Id (クライアント ID)

String (文字列)

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

x

次の設定の場合

スロー

OAUTH2-PROVIDER:​NO_SUCH_CLIENT​ - 削除されるクライアントが存在しない。

Revoke Token

<oauth2-provider:revoke-token>

アクセストークンまたは更新トークンを失効させ、関連する更新トークンまたはアクセストークンも無効化します。クライアントログイン情報を検証する必要がある場合、トークンを失効させる前に validateClient ログイン情報を使用します。

パラメータ

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

Configuration (設定)

String (文字列)

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

x

Token (トークン)

String (文字列)

失効させるトークン (アクセストークンまたは更新トークン)。

x

次の設定の場合

スロー

OAUTH2-PROVIDER:​INVALID_TOKEN​ - 失効させるトークンが有効でない。

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

スコープ

Array of String (文字列の配列)

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

Resource Owner Roles (リソースオーナーロール)

Array of String (文字列の配列)

トークンを検証するときに適用するリソースオーナーロール。これは、トークンを検証するときに適用するリソースオーナーロールのリストに解決される式です。

Target Variable (対象変数)

String (文字列)

操作の出力を保存する変数の名前。

Target Value (対象値)

String (文字列)

操作の出力に対して評価される式。この式の結果が対象変数に保存されます。

#[payload]

出力

String (文字列)

次の設定の場合

スロー

OAUTH2-PROVIDER:​TOKEN_UNAUTHORIZED​ - 検証されるトークンが有効でない。

トークンの設定

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

項目 説明 デフォルト値 必須

Path (パス)

String (文字列)

新しいトークンを要求するときにコールするエンドポイント。

/token

Token Store (トークンストア)

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

トークン関連のデータを保存するための ObjectStore 設定情報。

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

使用する更新トークン戦略。デフォルトでは、更新トークンは生成されません。

Token Ttl (トークン TTL)

Number (数値)

アクセストークンコードの有効期限が切れるまでの秒数。

86400

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

Enumeration (列挙)。次のいずれかになります。

  • NANOSECONDS (ナノ秒)

  • MICROSECONDS (マイクロ秒)

  • MILLISECONDS (ミリ秒)

  • SECONDS (秒)

  • MINUTES (分)

  • HOURS (時間)

  • DAYS (日)

トークン TTL の時間単位。

SECONDS (秒)

Authorization Config (認証設定)

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

項目 説明 デフォルト値 必須

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 から作成された永続的なオブジェクトストア。

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 (文字列)

クライアントの名前。

説明

String (文字列)

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

Secret (シークレット)

String (文字列)

クライアントを認証するために使用されるクライアントシークレット。[Type (種別)]​ が CONFIDENTIAL の場合のみ必要です。

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

Array of String (文字列の配列)

要求の処理後にクライアントに応答するために使用する登録済みリダイレクト URI のリスト。

大部分の要求では、新しいリダイレクト URI を定義できるため、これらが常に考慮されるわけではありません。​新しい値の処理​も参照してください。

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

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

Array of Enumeration (列挙の配列)。次のいずれかになります。

  • AUTHORIZATION_CODE​

  • REFRESH_TOKEN​

  • TOKEN

  • PASSWORD

  • CLIENT_CREDENTIALS

このクライアントがトークンを取得するために正常に実行できる OAuth フローを定義する許可種別。​新しい値の処理​も参照してください。.

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

Array of String (文字列の配列)

このクライアントに一致するスコープ。クライアント ID は一致するが、スコープが異なる要求を受信した場合、その要求は処理されません。​新しい値の処理​も参照してください。.

Enumeration (列挙)。次のいずれかになります。

  • CONFIDENTIAL

  • PUBLIC

クライアント種別は、クライアントがそのログイン情報の機密性を維持できるかどうかを定義します。有効な値は、PUBLIC​ (公開) (クライアントはログイン情報の機密性を維持できない) または CONFIDENTIAL​ (機密) (クライアントはログイン情報の機密性を維持できる) です。

PUBLIC

クライアントリダイレクト 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 (列挙)。次のいずれかになります。

  • NANOSECONDS (ナノ秒)

  • MICROSECONDS (マイクロ秒)

  • MILLISECONDS (ミリ秒)

  • SECONDS (秒)

  • MINUTES (分)

  • HOURS (時間)

  • DAYS (日)

maxIdleTime 属性の時間単位

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

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

項目 説明 デフォルト値 必須

Token Generator Strategy (トークンジェネレータ戦略)

TokenGeneratorStrategy

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

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

項目 説明 デフォルト値 必須

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

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

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

エントリ TTL を 86400 SECONDS (600 秒) に設定して 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 (列挙)。次のいずれかになります。

  • NANOSECONDS (ナノ秒)

  • MICROSECONDS (マイクロ秒)

  • MILLISECONDS (ミリ秒)

  • SECONDS (秒)

  • MINUTES (分)

  • HOURS (時間)

  • DAYS (日)

SECONDS (秒)

Maximum Failure Count (最大失敗数)

Number (数値)

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

5

OAuth ダンス

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

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

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

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

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

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

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

セキュリティプロバイダ

全般設定​ で前述したように、アプリケーション内で 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>

全般設定

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

Was this article helpful?

💙 Thanks for your feedback!