4.0
OAuth / OpenID Connect
Overview Getting Started Developer Guide API Reference EQL Reference Configuration Environment Samples Ver.3.2 Doc ↗

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名を指定します。初期から DEFAULT という名前のOAuthAuthorization定義が作成されています。テナント全体で共通の設定で問題ない場合はこの DEFAULT 定義に設定します。

Available Roles

OAuth2によるアクセスを許可するroleを指定します。 すべてのユーザーに許可する場合は、*を指定します。

Scopes

このAuthorization Serverで扱うscopeを定義します。 デフォルトでは、OpenID Connectで利用する profile 、 email スコープが定義されています。 Scopeの設定 を参照してください。

OpenID Connect仕様で定義される、 openid 、offline_access スコープはこの項目に未設定でも利用可能です。

Consent Template

ユーザーにスコープの承認を得る際の承認画面のTemplateを指定します。 未指定の場合は、OAuthAuthorizationServiceに定義されるデフォルトのTemplateが利用されます。

Client Policies

Client種別毎にポリシーを定義します。 Client Policyの設定 を参照してください。

Subject Identifier

ID Token、UserInfo Endpointから返却されるSubject Id（エンドユーザーの識別子）の種別を定義します。

Typeは以下のいずれかを指定します。

Public

すべてのclientに共通のsubjectIdを返します。 Subject Id Mapped User PropertyにsubjectIdが格納されているUserエンティティのプロパティ名を指定します。 subjectIdとしてUserのプロパティ（oidやaccountIdなど）を利用可能ですが、 外部にその値を公開したくない場合はその値をハッシュするように設定することも可能です。 ハッシュする場合は、HashingフラグをONにします。

Pairwise

client毎に異なるsubjectIdを返します。 Subject Id Mapped User Propertyに指定されるUserエンティティのプロパティ名を元にclient毎にそのハッシュ値を返却します。

Issuer Uri

issuerのuriを指定します。 未指定の場合は、Host名などを元に自動で生成しますが、 その自動生成される値ではなく特定の値としたい場合に指定します。
Scopeの設定

スコープは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マッピングでは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 Policyの設定

Client種別毎にポリシーを定義します。 Client種別は次の2種類です。

  • PUBLIC

  • CONFIDENTIAL

項目 内容

Client Type

Client種別を指定します。

Access Token Lifetime Seconds

AccessTokenの有効期限（秒）を設定します。

Support Refresh Token

RefreshTokenの発行許可するか否かを設定します。

Refresh Token Lifetime Seconds

RefreshTokenの有効期限（秒）を設定します。

Consent Type

承認画面を出すタイミングについての定義をします。

Always

AccessToken要求の都度承認画面を表示します。

Once

一度承認済みのscopeに関しては承認画面をだしません。
ただし、scopeにoffline_accessを含む場合（RefreshTokenの発行）は、承認画面を表示します。

Scripting

承認画面表示有無をカスタムロジック（GroovyScript）で設定します。 GroovyScriptでは、表示有無をbooleanで返却するように実装します。 次の変数がバインドされます。

  • request: RequestContextBinding

  • session: SessionBinding

  • user: UserBinding

  • auth: AuthContext

  • requiredScopes: 承認要求されたスコープのList

  • grantedScopes: 既に承認済みのスコープのList

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 を参照ください。

Custom Token Introspector

CustomTokenIntrospectorでは、TokenのIntrospection処理にカスタムのバリデーション、レスポンスパラメータを追加することが可能です。

CustomTokenIntrospectorの処理は、JavaもしくはGroovy Scriptにて記述します。

Javaクラス形式による実装

org.iplass.mtp.auth.oauth.CustomTokenIntrospector インターフェースを実装するクラスを作成します。

実装例(Java)
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形式による実装
実装例(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のインスタンス
参照専用のアクセスに限定したRequestContextのラッパークラスです。 attribute、HTTPパラメータへのアクセスが可能です。

attributeの取得

request.attrX のように、インスタンスのプロパティとして取得可能です。

paramの取得

request.param.paramA のように、paramで取得されるMapインスタンス経由で取得可能です。

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

https://localhost/app/tenantA/oauth/authorize

  • response_typeは code のみサポートします

  • request、request_uriパラメータは現時点で未サポートです

  • PKCEをサポートします

  • promptは none login consent をサポートします

  • response_modeは query fragment form_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

https://localhost/app/tenantA/api/oauth/token

  • grant_typeは authorization_code refresh_token のみサポートします

  • Client Authenticationは client_secret_basic client_secret_post をサポートします

  • redirect_uriパラメータは必須です

OAuth2.0 Introspection Endpoint

http(s)://[server]/[appContext]/[tenantName]/api/oauth/introspect

https://localhost/app/tenantA/api/oauth/introspect

  • Client Authenticationは client_secret_basic client_secret_post をサポートします

  • token_type_hintパラメータは無視されます

OAuth2.0 Token Revocation Endpoint

http(s)://[server]/[appContext]/[tenantName]/api/oauth/revoke

https://localhost/app/tenantA/api/oauth/revoke

  • Client Authenticationは client_secret_basic client_secret_post をサポートします

  • token_type_hintパラメータは無視されます

JWKS Endpoint

http(s)://[server]/[appContext]/[tenantName]/oauth/jwks

https://localhost/app/tenantA/oauth/jwks

OpenIDConnect1.0 UserInfo Endpoint

http(s)://[server]/[appContext]/[tenantName]/api/oauth/userinfo

https://localhost/app/tenantA/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 Endpoint と Jwks Contents のいずれかを設定する必要があります。

Jwks Contents

Jwks ContentsをJson形式で指定します。JWTの署名を検証する場合、Jwks Endpoint と Jwks Contents のいずれかを設定する必要があります。

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として利用するクレームを指定します。デフォルト値は preferred_username です。

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]

https://localhost/app/tenantA/oidc/auth/Google

また、IdP側にリダイレクト先として以下のURLを設定してください。

http(s)://[server]/[appContext]/[tenantName]/oidc/authcb/[OpenIDConnect definitionName]

アカウント紐付けを起動する

ユーザーとOpenIDConnect定義を紐付けるURLは以下です。

http(s)://[server]/[appContext]/[tenantName]/oidc/connect/[OpenIDConnect definitionName]

https://localhost/app/tenantA/oidc/connect/Google

  • 呼び出す場合、CSRF対策用の固定トークンをパラメータに設定する必要があります。 詳細は Action定義（AdminConsole） のToken Checkの項を参照ください。

また、IdP側にリダイレクト先として以下のURLを設定してください。

http(s)://[server]/[appContext]/[tenantName]/oidc/connectcb/[OpenIDConnect definitionName]

アカウント紐付けを解除する

ユーザーとOpenIDConnect定義の紐付けを解除するWebAPIは以下です。

DELETE http(s)://[server]/[appContext]/[tenantName]/oidc/disconnect/[OpenIDConnect definitionName]

DELETE https://localhost/app/tenantA/oidc/disconnect/Google

  • 呼び出す場合、CSRF対策用の固定トークンをパラメータに設定する必要があります。 詳細は Tokenチェック を参照ください。

go to Top