1. Administering Oracle Access Management
  2. Managing the Oracle Access Management OAuth Service and OpenIDConnect
  3. Understanding OpenIDConnect

40 Understanding OpenIDConnect

OpenIDConnect implements authentication as an extension to the OAuth 2.0 authorization process. Use of this extension is requested by Clients by including the openid scope value in the Authorization Request.

Note:

OpenIDConnect with Detached Credential Collector (DCC) is not supported. Also see, Overview of Access Manager Credential Collection.

OpenIDConnect provides information about the end-user in the form of an id_token. This token verifies the identity of the user and provides basic profile information about the end-user. OpenIDConnect is enabled by default as a part of the OAM 12cBP01 installation process.

This section describes the following topics:

See Also:

40.1 About OpenIDConnect Tokens

OpenIDConnect generates a token namely, OpenIDConnect ID Token.

In addition to OAuth Access and refresh tokens, OpenIDConnect considers an identity token (ID Token). The primary extension that OpenIDConnect makes to OAuth 2.0 to enable End-Users to be authenticated is the ID Token data structure.

See

40.1.1 OpenIDConnect ID Token

An ID Token is a security token that contains Claims about the Authentication of an End-User by an Authorization Server when using a Client, and potentially other requested Claims.

The Claims of an ID Token include subject, issuer, audience, and timestamps. The following table lists out the Claims used within the ID Token for all OAuth 2.0 flows used by OpenIDConnect:

Table 40-1 Claims within the ID Token used by OpenIDConnect

Field Description Type Required/Optional

iss

Issuer Identifier for the Issuer of the response.

String

Required

sub

Subject Identifier.

String

Required

aud

Audience that this ID Token is intended for.

String

Required

exp

Expiration time on or after which the ID Token MUST NOT be accepted for processing.

String

Required

iat

Time at which the JWT was issued.

String

Required

auth_time

Time when the End-User authentication occurred.

String

Required

Nonce

Value used to associate a Client session with an ID Token, and to mitigate replay attacks.

String (case-sensitive)

Required

acr

Value of the authentication level.

String (case-sensitive)

Optional

amr

Identifier for a family of closely related authentication methods. See Authentication Method Reference Values.

an array of case sensitive strings

Optional

azp

Identifier of the party that is intended to use the access token and to request resources.

String (case-sensitive)

Optional

sid

Value of the encrypted token that contains session identifier and details.

String (case-sensitive)

Optional

Note:

nonce value is passed through unmodified from the Authentication Request to the ID Token. If present in the ID Token, Clients MUST verify that the nonce Claim Value is equal to the value of the nonce parameter sent in the Authentication Request. If present in the Authentication Request, Authorization Servers MUST include a nonce Claim in the ID Token with the Claim Value being the nonce value sent in the Authentication Request. Authorization Servers SHOULD perform no other processing on nonce values used.

Sample of a set of claims in an ID Token: 

{
"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 Claims

The Client obtains Claims about the end-user and the authentication event. Standard claims can be requested to be returned either in the userinfo response or in the ID token.

Following are some of the standard claims used by OpenIDConnect. For a complete list of standard claims supported, see https://openid.net/specs/openid-connect-basic-1_0.html#StandardClaims

Table 40-2 Claims used by OpenIDConnect

Field Description Type Required/Optional

sub

Identifier for the end-user at the issuer.

string

Required

name

Full name of the end-user in displayable form including all name parts, possibly including titles and suffixes, ordered according to the end-user's locale and preferences.

string

Required

given_name

Given name(s) or first name(s) of the end-user. Separate multiple given names using space characters, as applicable for different cultures.

string

Required

family_name

Surname(s) or last name(s) of the end-user.

Separate multiple family names using space characters, as applicable for different cultures.

string

Required

preferred_username

Shorthand name by which the end-user wishes to be referred to at the Client, such as janedoe or j.doe.

string

Required

email

Preferred e-mail address of the end-user.

string

Required

email_verified

True if the end-user's e-mail address has been verified.

False if the end-user's e-mail address has been verified.

boolean

Required

gender

Gender of the end-user, male or female or other.

string

Required

Locale

Location of the end-user.

String

Required

phone_number

Preferred telephone number of the end-user.

String

Required

phone_number_verified

True if the end-user's phone number has been verified.

False if the end-user's phone number has been verified.

boolean

Required

address

Preferred postal address of the end-user.

JSON object

Required

updated_at

Time the end-user's information was last updated. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

number

Required

40.3 Custom Claims

Topics

OAM Bundle Patch 12.2.1.4.210920 and Later Releases. This content applies only to OAM Bundle Patch 12.2.1.4.210920 and later releases.

This section describes the following topics:

40.3.1 About Custom Claims

OAM extends the ability to define the custom claims using templates that can be configured at client or domain level. The custom claims can be included in all the access tokens, ID tokens and userinfo. You can also perform value transformation as well as value filtering of the custom claim.

Custom claims are defined using templates and the usage details can be configured at client or domain level

Note:

If the custom claims are defined at both the client and domain level, the claims at the client level takes precedence.

You can specify if the custom claim name needs to be included in one or all of the following: access tokens, ID tokens, and userinfo response, for a specific client or all the clients under a specific domain.

You can set the following attributes while creating client or domain:

For example, when creating an identity domain, if you specify a custom claim named "ClientIP" for access tokens ("accessTokenCustomClaims":["ClientIP"]) then all the access tokens that are created using any of the clients under that identity domain will include the ClientIP custom claim.

Note:

You must define the Custom Claim before using it in the Client or Domain request. For details, see Defining Custom Claims Using Templates

40.3.2 Defining Custom Claims Using Templates

Administrators must define the custom claim that needs to be used in the client or the domain request.

Use the <admin-host>:<admin-port>/oam/services/rest/ssa/api/v1/template/{name} REST API to create a custom claim. The API must include the name of the custom claim that needs to be created. For example, to create a custom claim named ClientIP, you must use <admin-host>:<admin-port>/oam/services/rest/ssa/api/v1/template/ClientIP

Note:

The following names are not supported for creating templates. Their value cannot be overwritten.

The custom claim needs to be defined by the following attributes:

Table 40-3 Attributes and Values for Custom Claim Definition

Custom Claim Attributes Value Description
name <CustomClaim_Name>

Name of the custom claim. For example ClientIP
valueMapping <$namespace.var_name> Claim value can be mapped to any of the following:
  • static attribute
  • dynamic attribute from the UserStore, Session, or Requests using $

    For example, a claim can be mapped to dynamic value using UserStore attribute using $user.attr.<attributeName>

For more information about dynamic value mapping, see Namespace and Variable Names for Policy Responses
defaultValue <default_Claim_Value> Optional. This default value is used if the template processing fails.

For more information, see About defaultValue
transformFirst false or true

Optional. By default the value is false

If the value is set to true then valueTransformation is applied before valueFiltering
description   Optional. Details related to this template.
dynamicParams   Optional. Parameters must be defined as list of entries in dynamicParams

For details, see About dynamicParams
valueFiltering Java string methods that return boolean.

Optional. Filter the values of the claim. The value filters must be defined using Java methods whose return type is boolean.

For example, startsWith, contains, endswith, and so on.

For more information, see About valueFiltering

Also refer to Class String in Java™ Platform, Standard Edition 8 API Specification
valueTransformation Java string transformation methods

String transformations on the custom claim value. The transformation operations must be defined using Java methods.

Optional. For example, concat, replace, split, and so on

For more information, see About valueTransformation

Also refer to Class String in Java™ Platform, Standard Edition 8 API Specification

For the full list of attributes supported for defining custom claims, see the REST API Documentation.

The custom claims JSON must be similar to the following structure:
{
  "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 About valueTransformation

You can use valueTransformation to transform the values of the claim.

You can perform string transformations on the custom claim value. The transformation operations must be defined using Java methods.

Refer to Class String in Java™ Platform, Standard Edition 8 API Specification

Examples

The following examples illustrate the use of valueTransformation on custom claims.

Example 40-1

In this example, the claim value sampleText is transformed to sampleData

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

Example 40-2

You need not specify the type, if all parameters are of type string. For example: 

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

Example 40-3

You can chain transformations, if the result of each transformation is also a string. The result of the first transformation is taken as the input for the next one.

In the following example, the claim value sampleText is transformed to SAMPLETEXT.STRING1.STRING2

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

Example 40-4

In the following example, the claim value sampleText1:sampleText2 is transformed to ["sampleText1", "sampleText2" ]

Note:

The "operation":"toUpperCase" is not applied because the result of first operation (split) is not a string. 
{
  "valueMapping": "sampleText1:sampleText2",
  "valueTransformation": [
    {
      "operation": "split",
      "params": [
        ":"
      ]
    },
    {
      "operation": "toUpperCase"
    }
  ]
}
40.3.2.2 About valueFiltering

You can use valueFiltering to filter the value/values of the claim.

The value filters must be defined using Java methods whose return type is boolean.

Refer to Class String in Java™ Platform, Standard Edition 8 API Specification.

Note:

A filter can contain either populateIf tag or populateIfNot tag, but not both.
  • populateIf: returns claim value only if the result of this filter java method is true.
  • populateIfNot: returns claim value only if the result of this filter java method is false.

Examples

The following examples illustrate the use of valueFiltering on custom claims.

Example 40-5

In the following example, the filtered value returns null as it does not match the populateIf filter 

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

Example 40-6

You need not specify the type, if all parameters are of type string. For example: 

{
  "valueMapping": "sampleText",
  "valueFiltering": {
    "populateIf": "endsWith",
    "params": [
      "Text"
    ]
  }
}
40.3.2.3 About defaultValue

If there is an error while processing the template, the claim value is set to null and the claim is not returned back. You can choose to default to a particular claim value in case of error by setting the defaultValue.

Example 40-7

In this example, the claim value after processing the template is defaultSampleText.

In this case, invalid filter is defined as "populateIf": "invalidMethodName". Therefore, the claim is assigned the configured default value and none of the further processing like transforms is applied. 

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

You can use dynamic parameters while defining valueTransformation and valueFiltering, in addition to the static parameters.

To use dynamic parameters, parameters must be defined as list of entries in dynamicParams

Example 40-8

In the following example, claim value is sampleText and the dynamicParams is defined as "$user.attr.email" : email.com. Therefore, the claim value returned after processing the template is sampleTextemail.com 

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

40.3.3 Using Claims Parameter in Authorization Request

You can add the claims parameter in the Authorization Request to request for individual claims. 

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

The claims Authentication Request parameter requests for specific Claims to be returned from the UserInfo endpoint and/or in the ID Token.

It is represented as a JSON object containing lists of Claims.

claims JSON Support Keys Description
userinfo Optional. Requests that the listed individual Claims be returned from the UserInfo Endpoint in addition to other claims that are being requested through scope or client/domain configuration.
id_token Optional. Requests that the listed individual Claims be returned in the ID Token in addition to other claims that are being requested through scope or client/domain configuration.

The values for these keys must be one of the following:

claims JSON Supported Values Description Sample
null Indicates that this Claim is being requested in the default manner 
claims = {
    "userinfo": {
        "nickname": null,
        "picture": null,
        "customClaim": null
    },
    "id_token": {
        "customClaim1": null,
        "email": null
    }
}
JSON Object Optional. Indicates whether the Claim being requested is an Essential Claim. If the value is true, this indicates that the Claim is an Essential Claim.

Note:

Only essential is supported. 
claims = {
    "userinfo": {
        "given_name": {
            "essential": true
        },
        "email": {
            "essential": true
        },
        "email_verified": {
            "essential": true
        },
    },
    "id_token": {
        "customClaim1": {
            "essential": true
        },
        "email": {
            "essential": true
        }
    }
}

For details, refer to https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter

40.3.4 Examples for Template-Based Claims

This section provides examples that illustrate value transformations, value filtering, and creating custom claims in AccessToken , IDToken, and UserInfo.

Example 40-9 Transforming Claim Value by Composing Different User Store Attributes

In this example, a custom e-mail is composed using <users given name>.<users family name>@<users domain name>.com. The values are as follows:
  • claim name is CustomEmail
  • $user.attr.given_name: "user"
  • $user.attr.family_name: "lastname"
  • $user.attr.domain_name: "domainName"

The claim value after processing the template is: user.lastname@domainName.com

Note:

A variable-length argument must be defined as Array, for example, CharSequence... must be defined as 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"
      ]
    }
  ]
}

Example 40-10 Transforming Users Group Allocation to Array and Filter Groups based on a Regular Expression

In this example, users group allocation is transformed from colon-separated string to an array and a list of group values that belong to the admin set are returned, that is, 'admin' or 'Admin'

The values are as follows:
  • claim name is Groups
  • $user.groups: "HR:Finance:Admin:Manager:HRadmin:Testadmin"

The claim value after processing the template is: ["Admin", "HRadmin", "Testadmin"]

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

Example 40-11 Mapping an OIDC Standard Claim in Userinfo to LDAP Attributes

In this example, email_verified reads from LDAP attribute named emailVerified

To achieve this,
  1. Create a mapping using a template. The template name must match the claim name required.
    {
   "valueMapping":"$user.attr.emailVerified"
}
  2. Update the client or domain to read template-based claims
    {
  "userInfoCustomClaims": [
    "email_verified"
  ]
}

    Note:

    Alternatively, you can also specify this per request in the claims parameter in the Authorization request. For details, Using Claims Parameter in Authorization Request

Example 40-12 Applying transformations and Filters to OIDC Standard Claim

In this example, the claim website is filtered and the transformations are being applied. That is, only if it starts with https, it is converted to lower case.

To achieve this,
  1. Create mapping using a template, template name must match claim name required.
    {
  "valueMapping": "$user.attr.website",
  "valueFiltering": {
    "populateIf": "startsWith",
    "params": [
      "https"
    ]
  },
  "valueTransformation": [
    {
      "operation": "toLowerCase"
    }
  ]
}
  2. Update the client or domain to read template-based claims. Alternatively, request this claim as part of the authorization request claims parameter, for example:
    http://<admin-host>:<admin-port>/oauth2/rest/authz?
response_type=<>&
client_id=<>&
domain=<>&
state=<>&
redirect_uri=<>&
scope=openid&
claims={"userinfo":{"website": null}}

Example 40-13 Adding Custom Claims in AccessToken , IDToken and UserInfo

To achieve this,
  1. Create mapping using a template. Template name must match claim name required.
    {
  "valueMapping": "customValue"
}
  2. Update client or domain to specify the destination of custom claim
    {
    "accessTokenCustomClaims": [
        "customClaim_accessToken"
    ],
    "idTokenCustomClaims": [
        "customClaim_idToken"
    ],
    "userInfoCustomClaims": [
        "customClaim_userInfo"
    ]
}

Example 40-14 Adding Custom Claims as Client Configurations and Request Parameters

To achieve this,
  1. Create two templates, for example, customClaim1 and customClaim2. Template name must match claim name required.
  2. Update client or domain to specify the destination of custom claim
    {    
    "idTokenCustomClaims": [
        "customClaim1"
    ]
}
  3. Request customClaim2 as part of the authorization request claims parameter
    http://<admin-host>:<admin-port>/oauth2/rest/authz?
response_type=<>&
client_id=<>&
domain=<>&
state=<>&
redirect_uri=<>&
scope=openid&
claims={"id_token":{"customClaim2": null}}

The idToken will include both the claims: customClaim1 from client configuration and customClaim2 from the request parameter.