1. OAuth
iPLAssはOAuth2.0のAuthorization Server(およびResource Server)の機能を提供します。 OAuthとはサードパーティのアプリケーション(Client)に対して、ユーザー(Resource Owner)のパスワード等の認証情報を渡すことなく、WebApi(Resource Server)へのアクセスを認可するための標準規格です。
次の仕様をサポートします。
Authorization Code Grant
Refresh Token
PKCE (Proof Key for Code Exchange)
Token Introspection
Token Revocation
JWKS (JSON Web Key Set)
2. OpenID Connect
iPLAssはOpenID ConnectのOpenID Providerの機能を提供します。 OpenID ConnectとはOAuth2.0プロトコル上にサードパーティのアプリケーション(Relying Party)に対してユーザー認証機能と属性(Claim)の提供をするための標準規格です。
次の仕様をサポートします。
Authorization Code Flow
UserInfo Endpoint
OAuth / OpenID Connectを有効化するためには、OAuthAuthorizationServiceでOAuth機能全体に対する設定を行ったうえで、adminConsole等にてテナント単位のOAuthAuthorization、OAuthClient、OAuthResourceServerのメタデータ定義を行います。
3. Authorization Server/OpenID Providerとしての設定
3.1. OAuthAuthorizationServiceの設定
OAuth / OpenID Connectに関する共通の設定をOAuthAuthorizationServiceに設定します。 AccessToken発行方法、Client種別毎のポリシー、JWT署名するための鍵に関する設定などを行います。 詳細は OAuthAuthorizationService を参照してください。
3.2. OAuthAuthorization定義の設定
OAuthAuthorization定義は、Authorization Server に関する設定です。 AdminConsoleなどを介して次の項目を設定します。
| 項目 | 内容 | ||
|---|---|---|---|
Name | Authorization Server名を指定します。初期から | ||
Available Roles | OAuth2によるアクセスを許可するroleを指定します。 すべてのユーザーに許可する場合は、*を指定します。 | ||
Scopes | このAuthorization Serverで扱うscopeを定義します。
デフォルトでは、OpenID Connectで利用する
| ||
Consent Template | ユーザーにスコープの承認を得る際の承認画面のTemplateを指定します。 未指定の場合は、OAuthAuthorizationServiceに定義されるデフォルトのTemplateが利用されます。 | ||
Client Policies | Client種別毎にポリシーを定義します。 Client Policyの設定 を参照してください。 | ||
Subject Identifier | ID Token、UserInfo Endpointから返却されるSubject Id(エンドユーザーの識別子)の種別を定義します。 Typeは以下のいずれかを指定します。
| ||
Issuer Uri | issuerのuriを指定します。 未指定の場合は、Host名などを元に自動で生成しますが、 その自動生成される値ではなく特定の値としたい場合に指定します。 |
スコープは2種類存在します。
OAuth2のScope
OpenID ConnectのclaimとマップされるScope
OpenID ConnectのclaimとマップされるScopeは、ID Tokenを取得する際、またUserInfo Endpointからユーザー情報を取得する際の取得可能なClaim値を定義します。
| 項目 | 内容 |
|---|---|
Name | Scopeの名前を設定します。 |
Display Name | Scopeの表示名を設定します。 |
Description | Scopeの説明を設定します。 |
Claims | このScopeをClaimとマップする場合、その定義を行います。 Claimマッピングの定義 を参照してください。 |
Claimマッピングではclaim名とそれがマップされる値(Userエンティティのプロパティ、カスタム値)を定義します。
| 項目 | 内容 |
|---|---|
Claim Name | Claimの名前を設定します。 |
User Property Name | このClaimがマップされるUserエンティティのプロパティ名を設定します。 |
Custom Value Script | 単純にUserエンティティのプロパティとClaimの値をマップできない場合、Claim値を取得するためのGroovy Scriptを記述可能です。 Custom Value Scriptを利用する場合は、User Property Nameは未設定である必要があります。 |
Client種別毎にポリシーを定義します。 Client種別は次の2種類です。
PUBLIC
CONFIDENTIAL
| 項目 | 内容 |
|---|---|
Client Type | Client種別を指定します。 |
Access Token Lifetime Seconds | AccessTokenの有効期限(秒)を設定します。 |
Support Refresh Token | RefreshTokenの発行許可するか否かを設定します。 |
Refresh Token Lifetime Seconds | RefreshTokenの有効期限(秒)を設定します。 |
Consent Type | 承認画面を出すタイミングについての定義をします。
|
Scopes | Autorization Serverに定義されるScopeをClient種別により絞り込みたい場合に指定します。 |
Support OpenID Connect | OpenID Connectによるユーザー認証情報連携を有効化する場合はONにします。 |
3.3. OAuthClient定義の設定
OAuthClient定義は、OAuth2 Clientに関する設定です。 AdminConsoleなどを介して次の項目を設定します。
| 項目 | 内容 |
|---|---|
Name | Client名を指定します。このnameはclient_idとなります。 |
OAuth Authorization | このClientを紐づけるAuthorization Serverを指定します。 |
Client Type | Client種別を指定します。 |
Redirect Uris | このClientが利用するRedirect Uriを定義します。 |
Sector Identifier Uri | 必要に応じてOpenID Connect仕様に定義されるSector Identifier Uriを指定します。 |
Grant Types | このClientで利用するGrant Typeを指定します。 |
Client Uri | このClientのURLを指定します。 承認画面においてClient情報をエンドユーザーに提示するための項目です。 |
Logo Uri | このClientのLog URLを指定します。 承認画面においてClient情報をエンドユーザーに提示するための項目です。 |
Contacts | このClientの連絡先を指定します。 承認画面においてClient情報をエンドユーザーに提示するための項目です。 |
Terms of Service Uri | このClientのTerms of ServiceのURLをを指定します。 承認画面においてClient情報をエンドユーザーに提示するための項目です。 |
Policy Uri | このClientのPolicyのURLを指定します。 承認画面においてClient情報をエンドユーザーに提示するための項目です。 |
Client Secretの発行と破棄
CONFIDENTIALなClientの場合、Client SecretをadminConsoleのOAuthClient定義画面から発行可能です。
| Client Secretの表示は発行操作時のみとなります。 |
新規のClient Secretが発行された場合、過去のClient Secretは、OAuthAuthorizationServiceに定義される有効期間の間は引き続き利用可能です。 adminConsoleから、過去のClient Secretを明示的に削除することも可能です。
3.4. OAuthResourceServer定義の設定
OAuthResourceServer定義は、iPLAss外部のOAuth2 Resource Serverに関する設定です。 iPLAss以外で実装されたResource Serverを識別し、OAuth2.0 Introspection Endpointへのアクセスを許可します。 AdminConsoleなどを介して次の項目を設定します。
| 項目 | 内容 |
|---|---|
Name | Resource Server名を指定します。このnameはResource Serverのclient_idとなります。 |
Custom Token Introspector | Introspection処理にてカスタムの処理を追加する場合、設定します。
CustomTokenIntrospectorは、JavaもしくはGroovy Scriptにて実装します。 |
Custom Token Introspector
CustomTokenIntrospectorでは、TokenのIntrospection処理にカスタムのバリデーション、レスポンスパラメータを追加することが可能です。
CustomTokenIntrospectorの処理は、JavaもしくはGroovy Scriptにて記述します。
Javaクラス形式による実装
org.iplass.mtp.auth.oauth.CustomTokenIntrospector インターフェースを実装するクラスを作成します。
import java.util.Map;
import org.iplass.mtp.auth.User;
import org.iplass.mtp.auth.oauth.CustomTokenIntrospector;
import org.iplass.mtp.command.RequestContext;
public class SampleTokenIntrospector implements CustomTokenIntrospector {
@Override
public boolean handle(Map<String, Object> response, RequestContext request, User resourceOwner) {
//do some additional validation
if (!someValidation()) {
return false;
}
//add custom value to response
response.put("customValue", resourceOwner.getValue("customValue"));
return true;
}
}responseオブジェクトはResource Serverへ返却されるJSONオブジェクトのMap表現です。 カスタム値を返却する場合、responseオブジェクトへputします。 handleメソッドの返却値がfalseの場合、Introspection EndpointはResource Serverへactive=falseのみを返却します。
Groovy Script形式による実装
//do some additional validation
if (!SomeClass.someValidation()) {
return false;
}
//add custom value to response
response['customValue'] = resourceOwner.customValue;
return true;Groovy Scriptにはあらかじめ次の変数名でそれぞれのインスタンスがバインドされています。
| 変数名 | インスタンス |
|---|---|
request | RequestContextBindingのインスタンス
|
response | 返却するJSONを表現するMap のインスタンス |
resourceOwner | AccessTokenの所有者を表すUserエンティティ のインスタンス |
ResourceOwnerTokenIntrospector
iPLAssは次のCustomTokenIntrospectorの実装を提供します。
org.iplass.mtp.auth.oauth.introspectors.ResourceOwnerTokenIntrospector
AccessTokenを所有するUserの情報を返却するCustomTokenIntrospectorです。 レスポンスに"resource_owner"をキー名にUserエンティティを返却します。 また、"tenant_id"でテナントID、"tenant_name"でテナント名を返却します。
RemoteOAuthAccessTokenStore を利用し、iPLAssベースで別インスタンスのResource Serverを構築する場合、そのResource Serverにユーザー情報、テナント情報を連携するために利用可能です。
Client Secretの発行と破棄
Resource ServerのClient SecretをadminConsoleのOAuthResourceServer定義画面から発行可能です。
| Client Secretの表示は発行操作時のみとなります。 |
新規のClient Secretが発行された場合、過去のClient Secretは、OAuthAuthorizationServiceに定義される有効期間の間は引き続き利用可能です。 adminConsoleから、過去のClient Secretを明示的に削除することも可能です。
3.5. Endpoint
各エンドポイントを以下に示します。
OAuth2.0 Authorization Endpoint
http(s)://[server]/[appContext]/[tenantName]/oauth/authorize
response_typeは
codeのみサポートしますrequest、request_uriパラメータは現時点で未サポートです
PKCEをサポートします
promptは
noneloginconsentをサポートしますresponse_modeは
queryfragmentform_postをサポートしますdisplay、ui_locales、id_token_hint、login_hint、acr_values、claims_locales、claims、registrationパラメータは無視されます
RefreshTokenを必要とする場合、scopeに
offline_accessを指定します
OAuth2.0 Token Endpoint
http(s)://[server]/[appContext]/[tenantName]/api/oauth/token
grant_typeは
authorization_coderefresh_tokenのみサポートしますClient Authenticationは
client_secret_basicclient_secret_postをサポートしますredirect_uriパラメータは必須です
OAuth2.0 Introspection Endpoint
http(s)://[server]/[appContext]/[tenantName]/api/oauth/introspect
Client Authenticationは
client_secret_basicclient_secret_postをサポートしますtoken_type_hintパラメータは無視されます
OAuth2.0 Token Revocation Endpoint
http(s)://[server]/[appContext]/[tenantName]/api/oauth/revoke
Client Authenticationは
client_secret_basicclient_secret_postをサポートしますtoken_type_hintパラメータは無視されます
JWKS Endpoint
http(s)://[server]/[appContext]/[tenantName]/oauth/jwks
OpenIDConnect1.0 UserInfo Endpoint
http(s)://[server]/[appContext]/[tenantName]/api/oauth/userinfo
4. Relying Partyとしての設定
4.1. OpenIdConnectServiceの設定
OpenID ConnectのRelying Partyに関する共通の設定をOpenIdConnectServiceに設定します。 許容されるクロックスキュー時間、jwksのキャッシュ時間、HttpClientConfigに関する設定などを行います。 詳細は OpenIdConnectService を参照してください。
4.2. OpenIDConnect定義の設定
OpenIDConnect定義は、OpenIDConnectのRelying Partyに関する設定です。 AdminConsoleなどを介して次の項目を設定します。
| 項目 | 内容 |
|---|---|
Issuer | Issuerを指定します。 |
Authorization Endpoint | Authorization Endpointを指定します。 |
Token Endpoint | Token Endpointを指定します。 |
UserInfo Endpoint | UserInfo Endpointを指定します。 |
Jwks Endpoint | Jwks Endpointを指定します。JWTの署名を検証する場合、 |
Jwks Contents | Jwks ContentsをJson形式で指定します。JWTの署名を検証する場合、 |
Client Id | OpenID Providerで発行されたクライアントIDを指定します。 |
Scopes | OpenID Providerに要求するスコープを指定します。 |
Client Authentication Type | クライアント認証方式を指定します。 |
Use Nonce | nonceを利用するか指定します。 |
Enable PKCE | PKCEを適用するか指定します。 |
Iss Parameter Supported | issパラメーターをサポートするか指定します。trueの場合、issパラメーターの値がIssuerの設定値と一致しているか検証します。 |
Validate Sign | IDトークンの署名を検証するか指定します。trueにする場合、Jwks EndpointかJwks Contentsのどちらかを指定する必要があります。 |
Response Mode | レスポンスモードを指定します。 |
Subject Name Claim | Subject Nameとして利用するクレームを指定します。デフォルト値は |
AutoUserProvisioningHandler | org.iplass.mtp.auth.oidc.AutoUserProvisioningHandlerを実装したクラス名を指定します。iPLAss内に存在しないユーザーを自動的に作成する場合に指定します。 |
Enable Transient User | 仮のユーザーを利用するか指定します。trueの場合、iPLAss内に存在しない仮のユーザーで一時的なログインを許可します。 |
Back Url After Auth | ログイン後、リダイレクトするURLをGroovyTemplate形式で指定します。未設定の場合、テナントのTOP画面へリダイレクトされます。 |
Back Url After Connect | アカウント接続後、リダイレクトするURLをGroovyTemplate形式で指定します。未設定の場合、テナントのTOP画面へリダイレクトされます。 |
Client Secretの設定
OpenID Providerで発行されたClient SecretをadminConsoleのOpenIDConnect定義画面から登録します。
4.3. Endpoint
各エンドポイントを以下に示します。
Relying Partyとしての認証を起動する
Relying Partyとしての認証を起動するURLは以下です。
http(s)://[server]/[appContext]/[tenantName]/oidc/auth/[OpenIDConnect definitionName]
また、IdP側にリダイレクト先として以下のURLを設定してください。
http(s)://[server]/[appContext]/[tenantName]/oidc/authcb/[OpenIDConnect definitionName]
アカウント紐付けを起動する
ユーザーとOpenIDConnect定義を紐付けるURLは以下です。
http(s)://[server]/[appContext]/[tenantName]/oidc/connect/[OpenIDConnect definitionName]
また、IdP側にリダイレクト先として以下のURLを設定してください。
http(s)://[server]/[appContext]/[tenantName]/oidc/connectcb/[OpenIDConnect definitionName]
アカウント紐付けを解除する
ユーザーとOpenIDConnect定義の紐付けを解除するWebAPIは以下です。
DELETE http(s)://[server]/[appContext]/[tenantName]/oidc/disconnect/[OpenIDConnect definitionName]