1. Oracle Access Management管理者ガイド
  2. Oracle Access Management OAuthサービスおよびOpenIDConnectの管理
  3. OpenIDConnectの理解

40 OpenIDConnectの理解

OpenIDConnectは、OAuth 2.0認可プロセスの拡張機能として認証を実装します。認可リクエストにopenidスコープ値を含めて、クライアントがこの拡張機能の使用をリクエストします。

ノート:

OpenIDConnectでは外部資格証明コレクタ(DCC)の使用がサポートされていません。「Access Manager資格証明コレクションの概要」も参照してください。

OpenIDConnectはid_tokenの形でエンドユーザーに関する情報を提供します。このトークンでユーザーのアイデンティティを検証し、エンドユーザーに関する基本的なプロファイル情報を提供します。OpenIDConnectはOAM 12cBP01インストール・プロセス中にデフォルトで有効になります。

この節では、以下のトピックについて説明します。

関連項目:

40.1 OpenIDConnectトークンについて

OpenIDConnectではトークン(OpenIDConnect IDトークン)が生成されます。

OAuthのアクセス・トークンとリフレッシュ・トークンに加え、OpenIDConnectではアイデンティティ・トークン(IDトークン)が考慮されます。OAuth 2.0でエンドユーザーを認証するために、OpenIDConnectにより拡張されたのがIDトークンのデータ構造です。

参照

40.1.1 OpenIDConnectのIDトークン

IDトークンはセキュリティ・トークンです。クライアントを使用するときの認可サーバーによるエンドユーザー認証に関するクレーム(および場合によっては他のリクエストされたクレーム)が含まれます。

IDトークンのクレームにはサブジェクト、発行者、オーディエンスおよびタイムスタンプが含まれます。次の表に、OpenIDConnectで使用されるすべてのOAuth 2.0フローにおけるIDトークン内のクレームを示します。

表40-1 OpenIDConnectで使用されるIDトークン内のクレーム

フィールド 説明 タイプ 必須/オプション

iss

レスポンスの発行者の発行者識別子。

文字列

必須

sub

サブジェクト識別子。

文字列

必須

aud

このIDトークンの対象となるオーディエンス。

文字列

必須

exp

有効期限。この時刻以降はIDトークンを処理のために受け入れることはできません。

文字列

必須

iat

JWTが発行された時刻。

文字列

必須

auth_time

エンドユーザーの認証が発生した時刻。

文字列

必須

Nonce

クライアント・セッションとIDトークンの関連付け、およびリプレイ攻撃の軽減のための値。

文字列(大/小文字が区別される)

必須

acr

認証レベルの値。

文字列(大/小文字が区別される)

オプション。

amr

密接な関係がある認証方式のファミリの識別子。認証方式の参照値に関する項を参照。

文字列の配列(大/小文字が区別される)

オプション。

azp

アクセス・トークンを使用してリソースをリクエストする対象パーティの識別子。

文字列(大/小文字が区別される)

オプション。

sid

セッション識別子と詳細を含む暗号化されたトークンの値。

文字列(大/小文字が区別される)

オプション。

ノート:

nonce値は変更されずに認証リクエストからIDトークンに渡されます。IDトークン内に存在する場合、nonceクレーム値が、認証リクエストで送信されるnonceパラメータ値と等しいことをクライアントで検証する必要があります。認証リクエストに存在する場合、認可サーバーはnonceクレームをIDトークンに含める必要があります。その際、クレーム値は認証リクエストで送信されるnonce値と同一の必要があります。認可サーバーは、使用されるnonce値に対してこれ以外の処理は実行できません。

IDトークンのクレーム・セットのサンプル: 

{
"iss": "http://host1:14100/oauth2",
"sub": "weblogic",
"aud": ["MDCClient19","http://host1:14100/oauth2"],
"exp": 1509626702,
"iat": 1509623102,
"auth_time": "1509623099159",
"jti": "_UC4Ew-NUTYQsMOXCoMo0g",
"at_hash": "5CnkOBb_Mk28GYJlhC_Srg",
"azp": "MDCClient19",
"acr": "2",
"sid": "gO5pDtJFt+7bH/YQC8QpUQ==~teJOlstvBcUXT8xXcmaIG1ppGMAmBLKqPuJUKnzLyX3spmDtWwgDm/qj5hhoyPhSiqAghOgFmE+kpsm8esEEsbZht+L5dkL27JUSUbAGBBmwlR/8QlxLTE0cEoNJ+9aJ",
"amr": ["pwd"]
}

40.2 クレーム

クライアントはエンドユーザーおよび認証イベントに関するクレームを取得します。標準的なクレームは、ユーザー情報レスポンスまたはIDトークンで返されるようリクエストできます。

次に、OpenIDConnectで使用される標準クレームの一部を示します。サポートされている標準クレームの完全なリストは、https://openid.net/specs/openid-connect-basic-1_0.html#StandardClaimsを参照してください

表40-2 OpenIDConnectで使用されるクレーム

フィールド 説明 タイプ 必須/オプション

sub

発行者におけるエンドユーザーの識別子。

string

必須

name

エンドユーザーの名前全体は表示可能な形式で、すべての名前部分(場合によっては役職と接尾辞)が含まれ、エンドユーザーのロケールとプリファレンスに従った順序になります。

string

必須

given_name

エンドユーザーの名。文化によって、複数の名がある場合はスペース文字で区切られます。

string

必須

family_name

エンドユーザーの姓。

文化によって、複数の姓がある場合はスペース文字で区切られます。

string

必須

preferred_username

エンドユーザーがクライアントでの使用を希望する短縮名(janedoeまたはj.doeなど)。

string

必須

email

エンドユーザーの優先電子メール・アドレス。

string

必須

email_verified

エンドユーザーの電子メール・アドレスが検証済の場合はTrue。

エンドユーザーの電子メール・アドレスが検証済の場合はFalse。

boolean

必須

gender

エンドユーザーの性別(男性、女性またはその他)。

string

必須

Locale

エンドユーザーの場所。

文字列

必須

phone_number

エンドユーザーの優先電話番号。

文字列

必須

phone_number_verified

エンドユーザーの電話番号が検証済の場合はTrue。

エンドユーザーの電話番号が検証済の場合はFalse。

boolean

必須

address

エンドユーザーの優先住所。

JSONオブジェクト

必須

updated_at

エンドユーザーの情報の最終更新時刻。値はJSON数値で、1970-01-01T0:0:0Zから指定された日時までの秒数で表します(UTC)。

数値

必須

40.3 カスタム・クレーム

トピック

OAMバンドル・パッチ12.2.1.4.210920以降のリリース。この内容は、OAMバンドル・パッチ12.2.1.4.210920以降のリリースにのみ適用されます。

この節では、以下のトピックについて説明します。

40.3.1 カスタム・クレームについて

OAMは、クライアント・レベルまたはドメイン・レベルで構成できるテンプレートを使用して、カスタム・クレームを定義する機能を拡張します。カスタム・クレームは、すべてのアクセス・トークン、IDトークンおよびユーザー情報に含めることができます。カスタム・クレームの値の変換や値のフィルタリングを実行することもできます。

カスタム・クレームはテンプレートを使用して定義され、使用の詳細はクライアント・レベルまたはドメイン・レベルで構成できます

ノート:

クライアント・レベルとドメイン・レベルの両方でカスタム・クレームが定義されている場合は、クライアント・レベルのクレームが優先されます。

特定のクライアントまたは特定のドメインのすべてのクライアントで、アクセス・トークン、IDトークン、ユーザー情報レスポンスのいずれかまたはすべてにカスタム・クレーム名を含める必要があるかどうかを指定できます。

クライアントまたはドメインの作成時に、次の属性を設定できます:

たとえば、アイデンティティ・ドメインの作成時に、アクセス・トークン("accessTokenCustomClaims":["ClientIP"])に"ClientIP"というカスタム・クレームを指定した場合、そのアイデンティティ・ドメイン内のいずれかのクライアントを使用して作成されるすべてのアクセス・トークンにClientIPカスタム・クレームが含まれます。

ノート:

クライアント・リクエストまたはドメイン・リクエストで使用する前に、カスタム・クレームを定義する必要があります。詳細は、「テンプレートを使用したカスタム・クレームの定義」を参照してください

40.3.2 テンプレートを使用したカスタム・クレームの定義

管理者は、クライアントまたはドメイン・リクエストで使用する必要があるカスタム要求を定義する必要があります。

<admin-host>:<admin-port>/oam/services/rest/ssa/api/v1/template/{name} REST APIを使用して、カスタム・クレームを作成します。APIには、作成する必要があるカスタム・クレームの名前が含まれている必要があります。たとえば、ClientIPというカスタム・クレームを作成するには、<admin-host>:<admin-port>/oam/services/rest/ssa/api/v1/template/ClientIPを使用する必要があります

ノート:

次の名前は、テンプレートの作成ではサポートされていません。それらの値は上書きできません。

カスタム・クレームは、次の属性で定義する必要があります:

表40-3 カスタム・クレーム定義の属性と値

カスタム・クレーム属性 値 説明
name <CustomClaim_Name>

カスタム・クレームの名前。たとえばClientIP
valueMapping <$namespace.var_name> クレーム値は、次のいずれかにマップできます:
  • 静的属性
  • $を使用したUserStore、セッションまたはリクエストの動的属性

    たとえば、$user.attr.<attributeName>を使用して、UserStore属性でクレームを動的値にマップできます

動的値マッピングの詳細は、「ポリシー・レスポンスのネームスペースおよび変数名」を参照してください
defaultValue <default_Claim_Value> オプション。このデフォルト値は、テンプレートの処理に失敗した場合に使用されます。

詳細は、「defaultValueについて」を参照してください
transformFirst falseまたはtrue

オプション。デフォルト値はfalseです

値がtrueに設定されている場合は、valueFilteringの前にvalueTransformationが適用されます
description   オプション。このテンプレートに関連する詳細。
dynamicParams   オプション。パラメータは、dynamicParamsのエントリのリストとして定義する必要があります

詳細は、「dynamicParamsについて」を参照してください
valueFiltering ブール値を返すJava文字列メソッド。

オプション。クレームの値をフィルタします。値フィルタは、戻り型がブールであるJavaメソッドを使用して定義する必要があります。

たとえば、startsWith、contains、endswithなどです。

詳細は、「valueFilteringについて」を参照してください

Java™ Platform, Standard Edition 8 API仕様のClass Stringも参照してください
valueTransformation Java文字列変換メソッド

カスタム・クレーム値に対する文字列変換。変換操作は、Javaメソッドを使用して定義する必要があります。

オプション。たとえば、concat、replace、splitなどです

詳細は、「valueTransformationについて」を参照してください

Java™ Platform, Standard Edition 8 API仕様のClass Stringも参照してください

カスタム・クレームの定義でサポートされている属性の完全なリストは、REST APIのドキュメントを参照してください。

カスタム・クレームJSONは、次の構造に類似している必要があります:
{
  "valueMapping": "value of claim",
  "defaultValue": "defaultValueForClaim",
  "tranformFirst": "true or false",
  "description": "string defining the template",
  "dynamicParams": [
    "$user.attr.userStoreattributeName"
  ],
  "valueFiltering": {
    "populateIf": "java string method with boolean return type",
    "params": [
      "param3",
      "param4"
    ],
    "type": [
      "param3_type",
      "param4_type"
    ]
  },
  "valueTransformation": [
    {
      "operation": "java String method name",
      "params": [
        "param1",
        "param2"
      ],
      "type": [
        "param1_type",
        "param2_type"
      ]
    },
    {
      "operation": "java String method name",
      "params": [
        "param1",
        "param2"
      ],
      "type": [
        "param1_type",
        "param2_type"
      ]
    }
  ]
}
40.3.2.1 valueTransformationについて

valueTransformationを使用して、クレームの値を変換できます。

カスタム・クレーム値に対して文字列変換を実行できます。変換操作は、Javaメソッドを使用して定義する必要があります。

Java™ Platform, Standard Edition 8 API仕様のClass Stringを参照してください

例

次の例は、カスタム・クレームでのvalueTransformationの使用を示しています。

例40-1

この例では、クレーム値sampleTextがsampleDataに変換されます

{
  "valueMapping": "sampleText",
  "valueTransformation": [
    {
      "operation": "replace",
      "params": [
        "Text",
        "Data"
      ],
      "type": [
        "CharSequence",
        "CharSequence"
      ]
    }
  ]
}

例40-2

すべてのパラメータが文字列型の場合、typeを指定する必要はありません。たとえば: 

{
  "valueMapping": "sampleText",
  "valueTransformation": [
    {
      "operation": "replaceFirst",
      "params": [
        "param1",
        "param2"
      ]
    }
  ]
}

例40-3

各変換の結果も文字列の場合は、変換を連鎖させることができます。最初の変換の結果は、次の変換の入力として取得されます。

次の例では、クレーム値sampleTextがSAMPLETEXT.STRING1.STRING2に変換されます

{
  "valueMapping": "sampleText",
  "valueTransformation": [
    {
      "operation": "concat",
      "params": [
        "string1"
      ]
    },
    {
      "operation": "concat",
      "params": [
        "string2"
      ]
    },
    {
      "operation": "toUpperCase"
    }
  ]
}

例40-4

次の例では、クレーム値sampleText1:sampleText2が["sampleText1", "sampleText2" ]に変換されます

ノート:

最初の操作の結果(split)が文字列ではないため、"operation":"toUpperCase"は適用されません。 
{
  "valueMapping": "sampleText1:sampleText2",
  "valueTransformation": [
    {
      "operation": "split",
      "params": [
        ":"
      ]
    },
    {
      "operation": "toUpperCase"
    }
  ]
}
40.3.2.2 valueFilteringについて

valueFilteringを使用して、クレームの値(1つまたは複数)をフィルタできます。

値フィルタは、戻り型がブールであるJavaメソッドを使用して定義する必要があります。

Java™ Platform, Standard Edition 8 API仕様のClass Stringを参照してください。

ノート:

フィルタには、populateIfタグまたはpopulateIfNotタグのいずれかを含めることができますが、両方を含めることはできません。
  • populateIf: このフィルタjavaメソッドの結果がtrueの場合にのみ、クレーム値を返します。
  • populateIfNot: このフィルタjavaメソッドの結果がfalseの場合にのみ、クレーム値を返します。

例

次の例は、カスタム・クレームでのvalueFilteringの使用を示しています。

例40-5

次の例では、フィルタ処理された値は、populateIfフィルタと一致しないためnullを返します 

{
  "valueMapping": "sampleText",
  "valueFiltering": {
    "populateIf": "contains",
    "params": [
      "orcl"
    ],
    "type": [
      "CharSequence"
    ]
  }
}

例40-6

すべてのパラメータが文字列型の場合、typeを指定する必要はありません。たとえば: 

{
  "valueMapping": "sampleText",
  "valueFiltering": {
    "populateIf": "endsWith",
    "params": [
      "Text"
    ]
  }
}
40.3.2.3 defaultValueについて

テンプレートの処理中にエラーが発生した場合、クレーム値はnullに設定され、クレームは戻されません。defaultValueを設定することで、エラーの場合に特定のクレーム値にデフォルトを選択できます。

例40-7

この例では、テンプレートの処理後のクレーム値はdefaultSampleTextです。

この場合、無効なフィルタは"populateIf": "invalidMethodName"として定義されます。したがって、クレームには構成されたデフォルト値が割り当てられ、変換などのそれ以上の処理は適用されません。 

{
  "valueMapping": "sampleText",
  "defaultValue": "defaultSampleText",
  "valueFiltering": {
    "populateIf": "invalidMethodName",
    "params": [
      "ingsss"
    ]
  },
  "valueTransformation": [
    {
      "operation": "toUpperCase"
    }
  ]
}
40.3.2.4 dynamicParamsについて

静的パラメータに加えて、valueTransformationおよびvalueFilteringの定義中に動的パラメータを使用できます。

動的パラメータを使用するには、パラメータをdynamicParamsのエントリのリストとして定義する必要があります

例40-8

次の例では、クレーム値はsampleTextで、dynamicParamsは"$user.attr.email" : email.comとして定義されています。したがって、テンプレートの処理後に返されるクレーム値はsampleTextemail.comです 

{
  "valueMapping": "sampleText",
  "dynamicParams": [
    "$user.attr.email"
  ],
  "valueTransformation": [
    {
      "operation": "concat",
      "params": [
        "$user.attr.email"
      ]
    }
  ]
}

40.3.3 認可リクエストでのClaimsパラメータの使用

認可リクエストにclaimsパラメータを追加して、個々のクレームをリクエストできます。 

http://<admin-host>:<admin-port>/oauth2/rest/authz?
response_type=<>&
client_id=<>&
domain=<>&
state=<>&
redirect_uri=<>&
scope=<>&
claims=New parameter

claims認証リクエスト・パラメータは、UserInfoエンドポイントから、またはIDトークン(あるいはその両方)で返される特定のクレームをリクエストします。

これは、クレームのリストを含むJSONオブジェクトとして表されます。

claims JSONサポート・キー 説明
userinfo オプション。スコープまたはクライアント/ドメイン構成を通じてリクエストされている他のクレームに加えて、リストされた個々のクレームをUserInfoエンドポイントから返すようリクエストします。
id_token オプション。スコープまたはクライアント/ドメイン構成を通じてリクエストされている他のクレームに加えて、リストされた個々のクレームをIDトークンで返すようリクエストします。

これらのキーの値は、次のいずれかである必要があります:

claims JSONサポート値 説明 サンプル
null このクレームがデフォルトの方法でリクエストされていることを示します 
claims = {
    "userinfo": {
        "nickname": null,
        "picture": null,
        "customClaim": null
    },
    "id_token": {
        "customClaim1": null,
        "email": null
    }
}
JSONオブジェクト オプション。リクエストされているクレームが必須クレームかどうかを示します。値がtrueの場合、これはクレームが必須クレームであることを示します。

ノート:

essentialのみがサポートされています。 
claims = {
    "userinfo": {
        "given_name": {
            "essential": true
        },
        "email": {
            "essential": true
        },
        "email_verified": {
            "essential": true
        },
    },
    "id_token": {
        "customClaim1": {
            "essential": true
        },
        "email": {
            "essential": true
        }
    }
}

詳細は、https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameterを参照してください

40.3.4 テンプレートベースのクレームの例

この項では、AccessToken、IDTokenおよびUserInfoでの値の変換、値のフィルタリングおよびカスタム・クレームの作成の例を示します。

例40-9 異なるユーザー・ストア属性を構成することによるクレーム値の変換

この例では、<users given name>.<users family name>@<users domain name>.comを使用してカスタム電子メールが構成されます。値を次に示します。
  • クレーム名はCustomEmailです
  • $user.attr.given_name: "user"
  • $user.attr.family_name: "lastname"
  • $user.attr.domain_name: "domainName"

テンプレート処理後のクレーム値はuser.lastname@domainName.comです

ノート:

可変長引数は配列として定義する必要があります。たとえば、CharSequence...はCharSequence[]として定義する必要があります。 
{
  "valueMapping": "$user.attr.given_name",
  "tranformFirst": "true",
  "dynamicParams": [
    "$user.attr.family_name",
    "$user.attr.domain_name"
  ],
  "valueTransformation": [
    {
      "operation": "join",
      "params": [
        ".",
        "$user.attr.given_name",
        "$user.attr.family_name"
      ],
      "type": [
        "CharSequence",
        "CharSequence[]"
      ]
    },
    {
      "operation": "concat",
      "params": [
        "@"
      ]
    },
    {
      "operation": "concat",
      "params": [
        "$user.attr.domain_name"
      ]
    },
    {
      "operation": "concat",
      "params": [
        ".com"
      ]
    }
  ]
}

例40-10 正規表現に基づく配列およびフィルタ・グループへのユーザー・グループ割当ての変換

この例では、ユーザー・グループ割当てがコロンで区切られた文字列から配列に変換され、管理セットに属するグループ値のリスト(adminまたはAdmin)が返されます

値を次に示します。
  • クレーム名はGroupsです
  • $user.groups: "HR:Finance:Admin:Manager:HRadmin:Testadmin"

テンプレート処理後のクレーム値は["Admin", "HRadmin", "Testadmin"]です

{
  "valueMapping": "$user.groups",
  "transformFirst": true,
  "valueTransformation": [
    {
      "operation": "split",
      "params": [
        ":"
      ]
    }
  ],
  "valueFiltering": {
    "populateIf": "matches",
    "params": [
      ".*[aA](dmin).*"
    ]
  }
}

例40-11 UserinfoのOIDC標準クレームのLDAP属性へのマッピング

この例では、email_verifiedはemailVerifiedというLDAP属性から読み取ります

これを行うには、
  1. テンプレートを使用してマッピングを作成します。テンプレート名は必要なクレーム名と一致する必要があります。
    {
   "valueMapping":"$user.attr.emailVerified"
}
  2. クライアントまたはドメインを更新して、テンプレートベースのクレームを読み取ります
    {
  "userInfoCustomClaims": [
    "email_verified"
  ]
}

    ノート:

    または、認可リクエストのclaimsパラメータでリクエストごとにこれを指定することもできます。詳細は、「認可リクエストでのClaimsパラメータの使用」を参照してください

例40-12 OIDC標準クレームへの変換およびフィルタの適用

この例では、websiteというクレームがフィルタ処理され、変換が適用されています。つまり、httpsで始まる場合にのみ、小文字に変換されます。

これを行うには、
  1. テンプレートを使用してマッピングを作成します。テンプレート名は必要なクレーム名と一致する必要があります。
    {
  "valueMapping": "$user.attr.website",
  "valueFiltering": {
    "populateIf": "startsWith",
    "params": [
      "https"
    ]
  },
  "valueTransformation": [
    {
      "operation": "toLowerCase"
    }
  ]
}
  2. クライアントまたはドメインを更新して、テンプレートベースのクレームを読み取ります。または、次のように、認可リクエスト・クレーム・パラメータの一部としてこのクレームをリクエストします:
    http://<admin-host>:<admin-port>/oauth2/rest/authz?
response_type=<>&
client_id=<>&
domain=<>&
state=<>&
redirect_uri=<>&
scope=openid&
claims={"userinfo":{"website": null}}

例40-13 AccessToken、IDTokenおよびUserInfoでのカスタム・クレームの追加

これを行うには、
  1. テンプレートを使用してマッピングを作成します。テンプレート名は必要なクレーム名と一致する必要があります。
    {
  "valueMapping": "customValue"
}
  2. カスタム・クレームの宛先を指定するようにクライアントまたはドメインを更新します
    {
    "accessTokenCustomClaims": [
        "customClaim_accessToken"
    ],
    "idTokenCustomClaims": [
        "customClaim_idToken"
    ],
    "userInfoCustomClaims": [
        "customClaim_userInfo"
    ]
}

例40-14 クライアント構成およびリクエスト・パラメータとしてのカスタム・クレームの追加

これを行うには、
  1. customClaim1とcustomClaim2などの2つのテンプレートを作成します。テンプレート名は必要なクレーム名と一致する必要があります。
  2. カスタム・クレームの宛先を指定するようにクライアントまたはドメインを更新します
    {    
    "idTokenCustomClaims": [
        "customClaim1"
    ]
}
  3. 認可リクエストのclaimsパラメータの一部としてcustomClaim2をリクエストします
    http://<admin-host>:<admin-port>/oauth2/rest/authz?
response_type=<>&
client_id=<>&
domain=<>&
state=<>&
redirect_uri=<>&
scope=openid&
claims={"id_token":{"customClaim2": null}}

idTokenには、クライアント構成からのcustomClaim1とリクエスト・パラメータからのcustomClaim2の両方のクレームが含まれます。