46 Configuring OAuth Services

Oracle Access Management provides a graphical user interface for configuring OAuth Services. This chapter describes how to use the Oracle Access Management Console to configure OAuth Services and contains the following topics.

Note:

OAuth Services can be configured from the command line using WLST. For more information about the Mobile and Social WLST commands, see the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

46.1 Enabling OAuth Services

The standard OAuth Service is enabled if the Oracle Access Management Identity Federation service is enabled in Available Services. To also enable Mobile OAuth, enable the Mobile and Social service in addition to the Identity Federation service.

  • To learn about enabling the Identity Federation service, see "Enabling Identity Federation" in the ”Introducing Identity Federation in Oracle Access Management” chapter.

  • To learn about enabling the Mobile and Social service, see "Enabling Mobile and Social" in the ”Understanding Mobile and Social” chapter.

46.2 Opening the OAuth Services Configuration Page

Follow these steps to open OAuth Services configuration page in the Oracle Access Management Console.

  1. Log in to the Oracle Access Management Console.

    The Launch Pad opens.

  2. Click OAuth Service in the Mobile and Social pane.

    The OAuth Identity Domains page opens in its own tab.

46.3 Understanding OAuth Services Configuration

The OAuth Identity Domains page lists all of the OAuth Identity Domains on the OAM Server. Click a domain to configure it. The following sections contain information about the tabs used to configure OAuth Services.

46.3.1 Understanding OAuth Identity Domains Configuration

OAuth Services ship with one OAuth identity domain named DefaultDomain. You can create additional domains as needed. Each OAuth identity domain has a universally unique identifier (UUID) that uniquely identifies it on the Internet. Define the following configuration objects to configure an OAuth identity domain:

  • An OAuth Service Provider

  • One or more OAuth Service Profiles

  • One or more OAuth Clients

  • One or more OAuth Resource Servers

You can also configure the following settings at the identity domain level:

  • OAuth Server settings

  • OAuth plug-ins

  • The OAuth Jailbreak detection policy

  • User profile service settings (available on the Resource Servers configuration tab)

  • Consent management service settings (available on the Resource Servers configuration tab)

The following screen is available to help you search for and revoke tokens across an identity domain:

  • Token life cycle management

46.3.2 Understanding OAuth Service Provider Configuration

The OAuth Service Provider settings page is used to manage the connection between OAuth Services and Access Manager, which is the back-end authorization service provider that supports OAuth Services.

46.3.3 Understanding OAuth Service Profiles Configuration

A Service Profile defines the following configuration settings categories for the OAuth service:

  • The clients that can interact with the service

  • The custom resource servers that the service protects and can provide access to

  • Token settings for the service, including refresh token settings, expiration settings, and the option to enable token life-cycle management

  • The User Profile Service profile and Consent Management Service profile that are enabled on the service

  • The security profile plug-ins that are enabled on the service

  • The mobile service settings for the service, including security settings for the supported mobile platform(s)

  • The root URL for the OAuth Services endpoints

If necessary, you can create multiple Service Profiles to define different service endpoints with different configuration settings.

46.3.4 Understanding OAuth Resource Servers Configuration

Use the Resource Servers tab to define settings for each resource server independently. Define a custom resource server for your applications or services. OAuth Services also includes two built-in resource servers, the User Profile Service and the Consent Management Service.

Scope and User Consent

The Resource Server Configuration page is where you define access request scope, which determines the range of access the client will have to the requested resources. Based on this setting, the authorization server restricts access and informs the client of the scope of the access token issued.

The access service enforces scope checking when handling both authorization requests and token requests. The client sends the scope parameter as part of an authorization request. If any part of the scope parameter value is invalid, the OAuth Server sends the client application a "Bad request" (code 400) error response with the error text invalid_scope.

The Resource Server Configuration page is also where you select the Require User Consent option, which requires the authorization server to display a user consent form so that the user can approve (or deny) access to the requested resources. The Require User Consent option can be enabled on a scope by scope basis. For example, you can require user consent for a scope request that allows "write" access, but not "read" access.

Note:

The OAuth Client Configuration page has a Bypass User Consent option. If this option is selected, the client setting overrides the resource server setting.

The User Profile Resource Service

The Oracle User Profile Resource Service is a native resource server included with the Oracle Access Management OAuth Server. This service allows your organization to use OAuth 2.0 to interact with User Profile Services, which is described in Section 41.2.5, "Introducing User Profile Services." This service makes it possible to use OAuth 2.0 to interact with a back-end directory server and performs the following User Profile REST operations on Person, Group, and Relationship entities:

  • Create

  • Update

  • Delete

  • Read

  • Search

The User Profile service receives and responds to HTTPS requests using service-specific endpoints for Person, Group, and Relationship entities. Each service endpoint can be individually disabled if it is not needed.

The following tables summarize the HTTP(S) methods and user profile attributes that an OAuth client can use to interact with the User Profile resource server.

Table 46-1 User Profile Resource Server - Resource Categories

Resource Category HTTP(S) Methods Resource Endpoint Use Details

/me

GET

PUT

http://host:port/ms_oauth/resources/
userprofile/me

The OAuth client can request read and update privileges for the specified user profile.

/users

GET

POST

PUT

DELETE

http://host:port/ms_oauth/resources/
userprofile/users

The OAuth client can request create, read, search, update, and delete privileges for any user profile.

/groups

GET

POST

PUT

DELETE

http://host:port/ms_oauth/resources/userprofile/groups

The OAuth client can request create, read, search, update, and delete privileges for any group profile.

/secretkey

POST

http://host:port/ms_oauth/resources/userprofile/secretkey

  

Table 46-2 User Profile Resource Server - Scope Settings

Scope HTTP(S) Method Resource Category Attributes

UserProfile.me

GET

PUT

/me

uid, mail,description, commonname, firstname, lastname

UserProfile.users

GET

POST

PUT

DELETE

/users

uid, mail,description, commonname, firstname, lastname

UserProfile.groups

GET

POST

PUT

DELETE

/groups

name, description

UserProfile.secretkey.management

POST

/secretkey

  

46.3.5 Understanding OAuth Client Profiles Configuration

Use the Client Profile page to register clients with OAuth Services. OAuth clients need to register with the OAuth server before initiating the protocol. Provide the application name, a client secret, and one or more redirect URIs that the OAuth server will use to redirect the user-agent to the client once access is granted or denied.

The OAuth Service or a system administrator issues each client a client identifier. This ID is a unique string that represents registration information provided for the OAuth client.

Two types of OAuth client can be defined:

  • Web - Requires a client ID, a secret, and one or more HTTP redirect URIs.

  • Mobile - Requires a client ID, one or more mobile redirect URIs, and mobile OAuth implementation-specific attributes.

Privileges

You can configure allowed scopes and bypass the need for user consent on a client by client basis. Before obtaining an access token, the client must obtain an authorization grant that it can exchange with the OAuth service for an access token. Client privileges determine which clients are allowed which grant types. The OAuth 2.0 specification provides several authorization grant types for different security use-cases.

Note:

For detailed information about the OAuth grant types, see IETF RFC 6749, which defines the OAuth 2.0 standard: http://tools.ietf.org/html/rfc6749#section-1.3

The following grant types are supported in OAM OAuth Services:

  • Authorization Code - The resource owner logs in using the authorization server. The token endpoint exchanges the authorization code along with client credentials for an access token.

  • Resource Owner Credentials - The resource owner provides the client with his or her user name and password. This is only suitable for highly trusted client applications because the client could abuse the password, or the password could unintentionally be disclosed to an attacker. Per the OAuth 2.0 specification, the authorization server and client should minimize use of this grant type and utilize other grant types whenever possible.

  • Client Credentials – The client requests an access token using only its client credentials (or another supported means of authentication). This is suitable if the client is requesting access to protected resources under its control, or those of another resource owner when previously arranged with the authorization server.

In addition to the OAuth grant types defined in the OAuth 2.0 standard, the following options are also available:

  • Refresh Token - Select this option to return a refresh token together with an access token in the token response. See Section 45.2.6, "Understanding Refresh Tokens" for more information.

  • JWT Bearer - Allows a JWT assertion to be used to request an OAuth access token.

  • SAML 2 Bearer - Allows a SAML2 assertion to be used to request an OAuth access token.

  • OAM Credentials - Used to request OAM tokens, such as a master token, an access token, or an OAuth access token.

  • Client Verification Code - Used by mobile clients to request a pre-verification code from OAuth server, which subsequently gets used mobile client flows.

46.3.6 Understanding OAuth Consent Management Service Configuration

The Consent Management Services configuration page is opened from the Resource Servers tab. The default Consent Management service handles consent storage, retrieval, revocation, and consent validation operations. Consent data is stored in the Oracle Access Management database.

46.3.7 Understanding OAuth Access Token Custom Attributes

The OAuth authorization server can embed custom attributes in access tokens. You can define two attribute types, static attributes and dynamic attributes:

  • Static Attributes - Attribute name and value pairs where the value is fixed at the time that you define the attribute. For example, name1=value1.

  • Dynamic Attributes - User-profile specific attributes. You must also configure the User Store setting on the OAuth Service Profile Configuration page. This setting defines the source of the User Profile attributes. The User Profile Service (and/or the underlying IDS interface) may be used to retrieve attribute names and values. Because dynamic attributes are user related, the user consent page (if configured) shows that the configured attributes are being shared with clients and resources.

You can define static and dynamic attributes using the following OAuth Services configuration objects:

  • OAuth service profile

  • Resource server

Keep the following guidelines in mind when configuring custom attributes:

  • Do not use the same name for a static and dynamic attribute.

  • Avoid using the same name when adding custom attributes to the service profile configuration and the scope configuration. If you define the same attribute name in both locations, the scope-based attribute value takes precedence.

Custom attributes appear as claims in access tokens. JWT-based access tokens contain standard JWT claims along with OAuth server specific ones. For example:

  • Standard

    "exp":1357596398000,
"iat":1357589198000,
"aud":"oam_server1",
"iss":"OAuthServiceProfile",
"prn":null,
"jti":"340c8324-e49f-43cb-ba95-837eb419e068",

  • OAuth Server Specific

    "oracle.oauth.user_origin_id":"john101",
"oracle.oauth.user_origin_id_type":"LDAP_UID",
"oracle:idm:claims:client:macaddress":"1C:AB:A7:A5:F0:DC",
"oracle.oauth.scope":"brokerage",
"oracle.oauth.client_origin_id":"oauthssoapp1id",
"oracle.oauth.grant_type":"oracle-idm:/oauth/grant-type/resource-access-token/jwt"

These claims are available as part of the access token generated by the OAuth server. Because the custom attributes appear as claims in a JWT-based access token, the following naming restrictions apply:

  • Avoid JWT standard claim names.

  • Avoid names with an "Oracle" prefix (as shown above)

46.3.8 Understanding OAuth Services Security

This section briefly discusses features and options that help protect OAuth Services transactions.

IDs and Secrets

OAuth Services requires a client secret when you register the client. Upon registration create a unique client ID for each client. (If you prefer, the system can create one for you.) The OAuth Service compares its stored values with the values the client sends when it interacts with the OAuth Service's endpoints over HTTPS or HTTP. If the values do not match, the request is rejected. Client secrets are Base64 values that are sent as authorization headers.

  • The client sends the OAuth server its client ID as part of an authorization request, and it sends the client ID and client secret in token endpoint requests.

OAuth Plug-ins

Optional plug-ins can be configured to provide additional security.

  • The adaptive-access plug-in runs fraud detection and risk analysis policy checks, enhancing authenticity and the trust level of a user.

  • The token attributes plug-in defines security policy around the token service provider.

  • The authorization and consent service plug-in defines security policy around interactions where authorization and user consent are granted. This plug-in can influence claims in a generated token as well.

  • Within an OAuth identity domain, the client plug-in defines a security policy for OAuth clients, and the resource server profile plug-in defines a security policy for resource servers.

Jail Breaking Detection Policy

A preconfigured Jail Breaking Detection Policy for iOS devices can search for files that indicate a device is jail broken and, if found, deny that device access to the OAuth flow.

Mobile Security

For information about mobile security, see the Mobile OAuth Authorization flow diagrams in Chapter 45, "Understanding Mobile OAuth Authorization."

Standard OAuth Security

Security measures provided for in the OAuth 2.0 specification also apply.

For a discussion of OAuth security considerations, see section 10 in IETF RFC 6749: http://tools.ietf.org/html/rfc6749#section-10

46.4 Configuring OAuth Services Settings

This section describes how to use the user interface to configure OAuth Services. It includes the following topics:

46.4.1 Configuring OAuth Identity Domains

See Section 46.3.1, "Understanding OAuth Identity Domains Configuration" for introductory information about OAuth Identity Domains. The following section describes how to use the user interface to configure an OAuth Identity Domain. It includes the following topics:

46.4.1.1 Creating an OAuth Identity Domain

  1. Open the OAuth Services Configuration page as described in Section 46.2, "Opening the OAuth Services Configuration Page."

  2. Choose one of the following:

    • To quickly create an Identity Domain with only basic information, click Create.

      The Identity Domain Configuration page opens.

      Complete the form and click Create to save your changes. You will need to provide additional configuration detail later.

    • To create an Identity Domain and configure essential Service Profile settings, click the wizard flow button.

      The Create OAuth Identity Domain wizard flow page opens.

      Click Back and Next to move backwards and forward through the wizard flow. Click Finish to save your changes.

46.4.1.2 Editing or Deleting an OAuth Identity Domain

  1. Open the OAuth Identity Domains page as described in Section 46.2, "Opening the OAuth Services Configuration Page."

    • To view or edit an Identity Domain, click its name in the table.

    • To delete an Identity Domain, select it by clicking the column to the left of the domain name and then click the delete button in the command bar.

46.4.1.3 Understanding the Identity Domain Configuration Page - Summary Tab

This section describes the form fields on the Identity Domain Configuration Summary tab when viewing an existing identity domain or creating a new one.

Identity Domain - The name of the identity domain. If creating or editing an identity domain, type a unique name without spaces.

Description - (Optional) A short description to help you or another administrator identify this identity domain in the future.

Identity Domain UUID - The identification code that uniquely identifies this identity domain on the Internet. Click Generate to populate this field with a universal unique identifier code.

Allow Multiple Resource Servers - Select this option if the identity domain supports more than one resource server.

Enable Mobile - Select this option if the identity domain will support mobile clients. If this option is cleared, mobile services configuration settings will not be available in the user interface for this identity domain.

Service Configuration

These fields appear on the Create Identity Domain page.

Service Profile Name - The name of the identity domain's service profile. Each identity domain requires at least one service profile. See Section 46.3.3, "Understanding OAuth Service Profiles Configuration," for more information.

User Profile Service Name - The name of the identity domain's user profile service. A user profile service is created automatically for each identity domain. See Section 46.3.4, "Understanding OAuth Resource Servers Configuration," for more information.

Consent Management Service Name - The name of the identity domain's consent management service. Each identity domain must have a consent management service, which stores and retrieves consent records, and performs consent validation and consent revocation operations. See Section 46.3.6, "Understanding OAuth Consent Management Service Configuration," for more information.

Service Profile Endpoint - The URL where the OAuth authorization service for this identity domain responds to authorization requests.

User Profile Service Endpoint - The URL where the User Profile Service receives and responds to create, read, update, and delete requests.

Consent Management Service Endpoint - The URL where the Consent Management Service receives and responds to client and resource owner service requests.

46.4.1.4 Understanding the Create OAuth Identity Domain Wizard Page

For help understanding the form fields on the Create OAuth Identity Domain wizard pages, refer to the following sections.

46.4.2 Configuring OAuth Service Profiles

See Section 46.3.3, "Understanding OAuth Service Profiles Configuration" for introductory information about OAuth Service Profiles. The following section describes how to use the user interface to configure an OAuth Service Profile. It includes the following topics:

46.4.2.1 Creating an OAuth Service Profile

  1. Open the OAuth Services Configuration page as described in Section 46.2, "Opening the OAuth Services Configuration Page," then click the identity domain to open it.

  2. Click the OAuth Service Profiles tab.

  3. Click the Create button and complete the wizard.

46.4.2.2 Editing or Deleting an OAuth Service Profile

  1. Open the OAuth Services Configuration page as described in Section 46.2, "Opening the OAuth Services Configuration Page," then click an identity domain to open it for editing.

  2. Click the OAuth Service Profiles tab.

  3. Do the following:

    • To edit a service profile, click its name in the table.

    • To delete a service profile, select it by clicking the box to the left of the name and then click the delete button in the command bar.

46.4.2.3 Understanding the OAuth Service Profile Configuration Page

Identity Domain - The name of the identity domain to which this service profile applies. (Read-only)

Name - The name of this service profile.

Description - (Optional) A short description to help you or another administrator identify this service profile in the future.

Service Enabled - Select to activate the service profile, or clear the option box to inactivate it.

Service Provider - The name of the OAuth Service Provider that corresponds with this OAuth Service Profile.

Service Endpoint - The URL where the OAuth authorization service responds to authorization requests.

User Store

User Authenticator - For user authentication, choose OAM to use the Oracle Access Management token provider, or choose IDS to use the Identity Directory Service token provider. Only choose IDS authentication if the OAM token is not used at all (for example, if only the JWT token is used). If both OAM and JWT tokens are used, choose OAM authentication to avoid duplicated authentication attempts sent by both IDS and OAM.

Identity Store Name - The name of the identity store when IDS is configured as the user authenticator.

Plug-Ins

Choose available plug-ins from the menus in the following categories.

Adaptive Access - Runs Oracle Adaptive Access Manager (OAAM) fraud detection and risk analysis policy checks, enhancing authenticity and the trust level of a user

Token Attributes - Defines security policy around the token service provider.

Client - Delegates the following to an external security module: confidential client authentication, client authorization, and client profile reading.

Resource Server Profile - Delegates the following to an external security module: confidential resource server authentication, resource server authorization, and resource server profile reading.

Consent Management Service - Defines security policy around interactions where authorization and user consent are granted. This plug-in can influence claims in a generated token as well.

Attributes

Add or delete service profile attributes and their values to further configure the OAuth service profile.

For JWT token generation and validation, configure the following parameters:

  • jwt.cert.alias

  • jwt.trusted.issuer.size

  • jwt.trusted.issuer.1

  • jwt.trusted.issuer.2

Note:

For details, see Section 46.5, "Configuring OAuth to Accept Third-Party JWT Bearer Assertions."

Table 46-3 OAuth Service Profile Configuration Attributes

Name Value Notes

jwt.cert.alias

  

Private key alias name for the signing certificate in the keystore. The default alias will be used if this attribute is not specified.

jwt.CryptoScheme

RS512

The cryptographic algorithm used to sign the contents of the JWT token. The default value is RS512. (RSA encryption using SHA-512 hash algorithm.)

jwt.issuer

www.oracle.example.com

This issuer of the tokens (that is, the iss claim value in the JWT token generated by the OAuth server). The default value, www.example.oracle.com,needs to be changed in the deployment.

jwt.trusted.issuer.size

2

The number of trusted issuers. The value can be any number of trusted issuers. For example, if the number is 2, the following matching params need to be specified.

jwt.trusted.issuer.1

  

The alias name for the public key of the first trusted issuer in the key store. See jwt.trusted.issuer.size for details.

jwt.trusted.issuer.2

  

The alias name for the public key of the second trusted issuer in the key store. See jwt.trusted.issuer.size for details.

createdByDefault

true

If set to true, the current OAuth service profile is created automatically as part of domain creation. Otherwise, it's created manually.

clientPWDValidation

false

If set to true, a client ID and secret, can be used as credentials to interact with the OAuth server.

tokenTenantClaimName

user.tenant.name

The tenant claim name in the tokens issued by the OAuth server. By default this is set using the identity domain name.

oauthServerSelfClientId

Value to be specified

By default this is set with the value of the jwt.issuer attribute. This attribute gets used when the OAuth server generates a client assertion for itself when interacting with other services such as service-to-service interactions.

oauthServerSelfCTValidityInSec

Value in seconds to be specified

The default value is 300sec. This attribute is related to oauthServerSelfClientId (that is, the OAuth server's own client assertion validity period).

msAlwaysShowLogin

true/false

This attribute is used with 3-legged mobile clients using the JWT SSO authentication mechanism. (Not applicable to 2-legged mobile clients in this release.)

true - Mobile applications are not registered using the server-side JWT user token. The OAuth server shows a login page for the user to submit credentials.

false - Mobile Applications are registered using the server side JWT user token.

By default true. If this attribute is not defined in the service profile, the server does not allow mobile applications to use the server-side JWT user token to register without a user name and password.

Mobile Service Settings

Supported Platforms - Choose iOS, Android, and/or Others:

  • iOS - The authorization server accepts requests from iOS clients if selected.

  • Android - The authorization server accepts requests from Android clients if selected.

  • Others - The authorization server accepts requests from clients other than iOS or Android if selected.

iOS Security Level - Choose High, Medium, or Low:

  • Advanced - All client registrations and token acquisitions are done using both push notification and HTTP(S).

  • Hybrid - All client registrations are done using both push notification and HTTP(S), and access token acquisitions are done using HTTP(S) only.

  • Standard - All client registrations and token acquisitions are done using HTTP(S)

Android Security Level - Choose High, Medium, or Low:

  • Advanced - All client registrations and token acquisitions are done using both push notification and HTTP(S).

  • Hybrid - All client registrations are done using push notification and HTTP(S), and access token acquisitions are done using HTTP(S) only.

  • Standard - All client registrations and token acquisitions are done using HTTP(S)

Android Sender ID - Enter the GCM sender ID that is required for Android push notification.

Android API Key - Enter the API key required for Android push notification.

Consent Service Protection - Authorization requests are routed to the consent service, which requires the user to log in and give consent. Select OAM or Third-Party Access Management to use either Oracle Access Management or a third-party option for consent page protection. Clear this option to use the OAuth server itself for consent page protection. If using the OAuth server for consent page protection, the authentication flow is determined by the User Store setting.

Require User Consent for Client Registration - Select this option to require the user to give authorization before registering each mobile OAuth application installation instance on a mobile device.

Preferred Hardware IDs - Use the list to prioritize the hardware ID attributes that should be used to uniquely identify mobile devices. The first available hardware ID from the list will be used.

Mobile Client Attributes - Add or delete mobile client attributes and their values based on the following table.

Table 46-4 Mobile Client Attributes Names and Values

Name Value Notes

oracle.oauth.debug.override.preAuthzCodeRequired

true

Supported values include true or false (enable/disable, respectively).

Clients

Allow access to all clients - Select if all clients in the identity domain should use this service profile. Clear this option to select which clients will be able to access the service profile.

Clients - Add to the table the clients that should be able to access the service profile. Click Browse Clients, then select the clients to add to the Clients table. To assign a client to a different service profile, click the box to the left of the client name and click Remove.

Token Settings

Use this tab to configure token settings, as well as settings for custom attribute that the OAuth service should embed in access tokens.

Tokens

  • Token Name - The name of the token.

  • Expires - The length of time in minutes after which the token is no longer valid.

  • Refresh Token Enabled - Select this option to allow a refresh token to be used. A refresh token cannot be used with a client verification code or an authorization code. See Section 45.2.6, "Understanding Refresh Tokens" for more information.

  • Refresh Token Expires - The length of time in minutes after which the refresh token is no longer valid.

  • Life Cycle Enabled - Select this option if the OAuth server should cache a token and save it in the database until the token expires.

Custom Attributes

Use this section to define custom attributes that the OAuth service embeds in the access tokens. See Section 46.3.7, "Understanding OAuth Access Token Custom Attributes" for more information about custom attributes.

  • Static Attributes - Attribute name and value pairs where the value is fixed at the time that you define the attribute. For example, name1=value1.

  • Dynamic Attributes - User-profile specific attributes.

Custom Resource Servers

Use this tab to choose which custom resource servers clients should have access to. A custom resource server is any resource server that is not the User Profile and Consent Management resource servers that are included with OAuth Services.

Allow clients access to all resource servers - Select to allow clients to access all resource servers configured in the identity domain. Clear this option to select which resource servers clients will be able to access.

Custom Resource Servers - Use the arrows to move the resource servers that clients should be able to access from the Available Servers box to the Selected Servers box. (This option is only available if the Allow clients access to all resource servers option is not selected.)

System Resource Servers

Use this tab to configure if clients should have access to the user profile service and/or consent management service.

User Profile Services -Use the arrows to move the user profile server that clients should be able to access from the Available Servers box to the Selected Servers box. Services listed in the Selected Servers box are active services.

Consent Management Services - Use the arrows to move the consent management server that clients should be able to access from the Available Servers box to the Selected Servers box. Services listed in the Selected Servers box are active services.

46.4.3 Configuring OAuth Clients

See Section 46.3.5, "Understanding OAuth Client Profiles Configuration" for introductory information about OAuth clients. The following section describes how to use the user interface to configure an OAuth Web client and an OAuth mobile client. It includes the following topics:

46.4.3.1 Creating an OAuth Client

  1. Open the OAuth Services Configuration page as described in Section 46.2, "Opening the OAuth Services Configuration Page," then click the identity domain to open it.

  2. Click the OAuth Clients tab.

  3. To create an OAuth Web (non-mobile) client, click the Create button located directly under the OAuth Web Clients heading and complete the form.

    To create an OAuth mobile client, click the Create button located directly under the OAuth Mobile Clients heading and complete the form.

46.4.3.2 Editing or Deleting a Client

  1. Open the OAuth Services Configuration page as described in Section 46.2, "Opening the OAuth Services Configuration Page," then click an identity domain to open it for editing.

  2. Click the OAuth Clients tab.

  3. Do the following:

    • To edit a client configuration, click its name on the page.

      The client configuration page opens in a new tab.

    • To delete a client, select it by clicking the box to the left of the name and then click the delete button in the command bar.

46.4.3.3 Understanding the OAuth Web Clients Configuration Page

This section describes the form fields on the OAuth Web Client Configuration page when viewing an existing OAuth Web client or creating a new one.

Identity Domain - The name of the identity domain in which this OAuth Web client is registered. (Read-only)

Name - The name of this OAuth client.

Description - (Optional) A short description to help you or another administrator identify this OAuth Web client in the future.

HTTP Redirect URIs - The client URIs that the OAuth server is allowed to redirect the user-agent to once access is granted or denied.

Client ID - The unique ID that the authorization server created for this client during registration. (Read-only).

Allow Token Attributes Retrieval - Select this option to allow custom attributes (both attribute names and values) to be shared with resource servers and the resource owner. See Section 46.3.7, "Understanding OAuth Access Token Custom Attributes" for more information about custom attributes.

Client Secret - A secret value known to the OAuth authorization service and the client. The authorization service checks the client secret and the client ID when it receives token endpoint requests from the client.

Privileges

Bypass User Consent - If selected, the client will not ask for the user's explicit authorization to access the user's protected resources. If this option is selected, this setting overrides the resource server setting. Clear this option if the client should be subject to the resource server setting.

Allow Access to all Scopes - If selected, the client can obtain an access token regardless of scope limitations for any resource server in the identity domain. Clear this option if the client should be subject to scope limitations.

Allowed Scopes - Lists the range of access the client has to the requested resources. To grant additional access, click Add to add a row to the table, then choose from the drop-down menu the scope to be added. To restrict access, select the scope that you want to remove by clicking the table row, then click Delete to remove the highlighted row. Click OK at the prompt to confirm that you want to remove the selected scope.

Grant Types - The OAuth 2.0 specification provides several authorization grant types for different security use-cases. Before obtaining an access token, the client must obtain an authorization grant that it can exchange with the OAuth service for an access token. Client privileges determine which clients are allowed which grant types. The following grant types are supported in OAM OAuth Services:

  • Authorization Code - The resource owner logs in using the authorization server. The token endpoint exchanges the authorization code along with client credentials for an access token.

  • Resource Owner Credentials - The resource owner provides the client with his or her user name and password. This is only suitable for highly trusted client applications because the client could abuse the password, or the password could unintentionally be disclosed to an attacker. Per the OAuth 2.0 specification, the authorization server and client should minimize use of this grant type and utilize other grant types whenever possible.

  • Client Credentials - The client requests an access token using only its client credentials (or another supported means of authentication). This is suitable if the client is requesting access to protected resources under its control, or those of another resource owner when previously arranged with the authorization server.

In addition to the OAuth grant types defined in the OAuth 2.0 standard, the following options are also available:

  • Refresh Token - Select this option to return a refresh token together with an access token in the token response. See Section 45.2.6, "Understanding Refresh Tokens" for more information.

  • JWT Bearer - Allows a JWT assertion to be used to request an OAuth access token.

  • SAML 2 Bearer - Allows a SAML2 assertion to be used to request an OAuth access token.

  • OAM Credentials - Used to request OAM tokens, such as a master token, an access token, or an OAuth access token.

  • Client Verification Code - Used by mobile clients to request a pre-verification code from OAuth server, which subsequently gets used mobile client flows.

Attributes

Add or delete custom attributes that the authorization server returns to the client along with the the scope settings.

Avoid using the same name when adding custom attributes to the service profile configuration and the scope configuration. If you define the same attribute name in both locations, the scope-based attribute value takes precedence.

Table 46-5 Web Client Attributes Names and Values

Name Value Notes

jwt.audience

Space separated values.

Used when the OAuth server generates a client assertion and a user assertion. The aud claim for those JWT tokens contain the defined values in this token.

46.4.3.4 Understanding the OAuth Mobile Clients Configuration Page

This section describes the form fields on the OAuth Web Client Configuration page when viewing an existing OAuth Web client or creating a new one.

Identity Domain - The name of the identity domain in which this OAuth mobile client is registered. (Read-only)

Name - The name of this OAuth client.

Description - (Optional) A short description to help you or another administrator identify this OAuth mobile client in the future.

Client ID - The unique ID that the authorization server created for this client during registration. (Read-only).

Allow Token Attributes Retrieval - Select this option to allow custom attributes (both attribute names and values) to be shared with resource servers and the resource owner. See Section 46.3.7, "Understanding OAuth Access Token Custom Attributes" for more information about custom attributes.

Jail Breaking Detection - Select to enable jail breaking detection for mobile devices. See "Jail Breaking Detection Policy" for more information.

Mobile Redirect URIs - The client URIs that the OAuth server is allowed to redirect the user-agent to once access is granted or denied.

Privileges

Bypass User Consent - If selected, the client will not ask for the user's explicit authorization to access the user's protected resources. If this option is selected, this setting overrides the resource server setting. Clear this option if the client should be subject to the resource server setting.

Allow Access to all Scopes - If selected, the client can obtain an access token regardless of scope limitations for any resource server in the identity domain. Clear this option if the client should be subject to scope limitations.

Allowed Scopes - Lists the range of access the client has to the requested resources. To grant additional access, click Add to add a row to the table, then choose from the drop-down menu the scope to be added. To restrict access, select the scope that you want to remove by clicking the table row, then click Delete to remove the highlighted row. Click OK at the prompt to confirm that you want to remove the selected scope.

Grant Types - The OAuth 2.0 specification provides several authorization grant types for different security use-cases. Before obtaining an access token, the client must obtain an authorization grant that it can exchange with the OAuth service for an access token. Client privileges determine which clients are allowed which grant types. The following grant types are supported in OAM OAuth Services:

  • Authorization Code - The resource owner logs in using the authorization server. The token endpoint exchanges the authorization code along with client credentials for an access token.

  • Resource Owner Credentials - The resource owner provides the client with his or her user name and password. This is only suitable for highly trusted client applications because the client could abuse the password, or the password could unintentionally be disclosed to an attacker. Per the OAuth 2.0 specification, the authorization server and client should minimize use of this grant type and utilize other grant types whenever possible.

  • Client Credentials - The client requests an access token using only its client credentials (or another supported means of authentication). This is suitable if the client is requesting access to protected resources under its control, or those of another resource owner when previously arranged with the authorization server.

  • Refresh Token - Select this option to return a refresh token together with an access token in the token response. See Section 45.2.6, "Understanding Refresh Tokens" for more information.

Apple Push Notification

Applies to iOS devices only. The OAuth authorization server can restrict token delivery to a specific app installed on a specific mobile device by sending part of the client registration handle through HTTPS, and sending the other part through push notification using the Apple Push Notification Service (APNS). Use the following fields to configure how the OAuth server connects to APNS for this specific client app.

Connection Settings - Select Enabled to send a portion of security codes and tokens to the mobile client app using APNS. (The portions not sent using APNS are sent using HTTPS.) Clear this option if you do not want to use APNS for this mobile client app.

Minimum Connection Pool Size - Specifies the minimum number of connections in the connection pool.

Maximum Connection Pool Size - Specifies the maximum number of connections in the connection pool.

Keep Alive - The Apple Push Notification keep alive value in seconds.

Communication Mode - Choose Development to use the Apple development environment for initial development and testing of the application; choose Production to use Apple's production environment.

SSL/TLS Certificate for Development - Click Browse to navigate to the development SSL/TLS certificate issued by Apple for the Apple Push Notification Service.

Development Certificate Password - Type the development password for the Apple Push Notification certificate.

SSL/TLS Certificate for Production - Click Browse to navigate to the production SSL/TLS certificate issued by Apple for the Apple Push Notification Service.

Production Certificate Password - Type the production password for the Apple Push Notification certificate.

Google Application Settings

Applies to Android devices only. The OAuth authorization server can restrict token delivery to a specific app installed on a specific mobile device by sending part of the client registration handle through HTTPS, and sending the other part through push notification using Google Cloud Messaging (GCM) for Android. Use the following fields to configure how the OAuth server connects to the GCM service for this specific client app.

Restricted Package Name - The Google restricted package name.

Configuration Settings

Device Claim Attributes - Specifies the device attributes that the system should collect for device fingerprinting. If empty, the system collects every attribute in the SDK.

Mobile Custom Attributes - Specifies key-value pairs that should be sent to mobile applications using app profiles. (Mobile applications request app profiles that contain server-side settings, including endpoints, jail break detection policies, and security level details.

Attributes

Add or delete custom attributes that the authorization server returns to the client along with the scope settings.

Avoid using the same name when adding custom attributes to the service profile configuration and the scope configuration. If you define the same attribute name in both locations, the scope-based attribute value takes precedence.

46.4.4 Configuring the OAuth Service Provider

See Section 46.3.2, "Understanding OAuth Service Provider Configuration" for introductory information about OAuth Service Providers. The following section describes how to use the user interface to configure an OAuth Service Provider. It includes the following topics:

46.4.4.1 Editing or Deleting the OAuth Service Provider

  1. Open the OAuth Services Configuration page as described in Section 46.2, "Opening the OAuth Services Configuration Page," then click the identity domain to open it for editing.

  2. Click the OAuth Service Providers tab.

  3. Do the following:

    • To edit a service provider, click its name in the table.

    • To delete a service provider, select it by clicking the box to the left of the name and then click the delete button in the command bar.

46.4.4.2 Understanding the OAuth Service Provider Configuration Page

This section describes the form fields on the OAuth Service Provider Configuration page.

Identity Domain - The name of the identity domain with which this OAuth service provider is registered. (Read-only)

Name - The name of this service provider.

Description - (Optional) A short description to help you or another administrator identify this service provider.

Service Provider Java Class - The Java class that implements this service provider.

Attributes

Use the attribute settings in Table 46-6 to configure the OAuth service provider connection with Access Manager.

Table 46-6 OAuth Service Provider Attributes for Access Manager

Name Value Notes

oam.OAM_VERSION

OAM_11G

Either OAM_11G or OAM_10G, depending on the Oracle Access Manager version in use.

oam.WEBGATE_ID

accessgate-oic

  

oam.ENCRYPTED_PASSWORD

    

oam.DEBUG_VALUE

0

  

oam.TRANSPORT_SECURITY

OPEN

Specify the method for encrypting messages between this AccessGate and the Access Servers. The encryption methods need to match. Valid values include:

  • OPEN

  • SIMPLE

  • CERT

To update these settings, see Section 42.9.1.1, "Configuring Mobile Services to Work With Access Manager in Simple and Certificate Mode."

oam.OAM_SERVER_1

localhost:5575

Specify the host name and port number of the primary Oracle Access Management server.

oam.OAM_SERVER_1_MAX_CONN

4

Specify the maximum number of connections that this Mobile and Social instance can establish with OAM_SERVER_1. The default value is 4.

oam.OAM_SERVER_2

oam_server_2:5575

Specify the host name and port number of the secondary Oracle Access Management server.

oam.OAM_SERVER_2_MAX_CONN

4

Specify the maximum number of connections that this Mobile and Social instance can establish with OAM_SERVER_2. The default value is 4.

oam.AuthNURLForUID

wl_authen://sample_ldap_no_pwd_protected_res

  

46.4.5 Configuring OAuth Resource Servers

See Section 46.3.4, "Understanding OAuth Resource Servers Configuration" for introductory information about OAuth Resource Servers. The following section describes how to use the user interface to configure an OAuth resource server. It includes the following topics:

46.4.5.1 Creating an OAuth Resource Server

  1. Open the OAuth Services Configuration page as described in Section 46.2, "Opening the OAuth Services Configuration Page," then click the identity domain to open it.

  2. Click the Resource Servers tab.

  3. Choose from the following:

    • To define a new resource server for use with OAuth Services, click the Create button in the Custom Resource Servers section.

      The Custom Resource Server Configuration page opens.

    • To define a new User Profile Services instance, click the Create button in the User Profile Services section.

      The OAuth User Profile Service Configuration page opens.

    • To define a new Consent Management Services instance, see Section 46.4.7, "Configuring OAuth Consent Management Services."

46.4.5.2 Editing or Deleting an OAuth Resource Server

  1. Open the OAuth Services Configuration page as described in Section 46.2, "Opening the OAuth Services Configuration Page," then click the identity domain to open it for editing.

  2. Click the Resource Servers tab.

  3. Choose from the following:

    • To open a resource server for editing, click it. The Custom Resource Server Configuration page opens.

    • To open an OAuth User Profile Service configuration for editing, click it in the User Profile Services section. The User Profile Service Configuration page opens.

    • See Section 46.4.7, "Configuring OAuth Consent Management Services" for help configuring consent management services.

46.4.5.3 Understanding the OAuth Resource Servers Configuration Page

Identity Domain - The name of the identity domain to which this resource server applies. (Read-only)

Name - The name of this resource server (or resource service).

Description - (Optional) A short description to help you or another administrator identify this resource server in the future.

Allow Token Attributes Retrieval - Select this option to allow custom attributes (both attribute names and values) to be shared with clients and the resource owner. See Section 46.3.7, "Understanding OAuth Access Token Custom Attributes" for more information about custom attributes.

Authorization & Consent Service Plug-in - From the menu, choose an authorization plug-in for the resource server. This plug-in type defines security policy around interactions where authorization and user consent are granted. It can influence claims in a generated token as well.

Audience Claim - Identifies the audiences that the OAuth token is intended for. Each principal intended to process the OAuth token must identify itself with a value in Audience Claim.

Resource Server ID - The unique ID created for this resource server during registration. (Read-only)

Scopes

Click Add to add a new row to the scopes table. Click to select a row, then click Delete to remove it.

Name - Type a scope definition. Use dot notation, for example: photo.read

Description - Type a short note that describes the scope.

Require User Consent - Select to require the authorization server to display a user consent form so that the user can approve (or deny) the access request.

Offline Scope - Allows client applications to request a refresh token that can be used to obtain an access token even when the user is offline or not present. Client applications use the refresh token to get a new access token to access resources. See Section 45.2.6, "Understanding Refresh Tokens" for more information.

Token Settings

Override the default settings - Select this option if the token settings defined on the resource server configuration page should override the default token settings defined on the OAuth service profile page.

Token Name - The name of the token.

Expires - The length of time in minutes after which the token is no longer valid.

Refresh Token Enabled - Select this option to allow a refresh token to be used. A refresh token cannot be used with a client verification code or an authorization code. See Section 45.2.6, "Understanding Refresh Tokens" for more information.

Refresh Token Expires - The length of time in minutes after which the refresh token is no longer valid.

Life Cycle Enabled - Select this option if the OAuth server should cache the token and save it in the database until the token expires.

Custom Attributes

Use this section to define custom attributes that the OAuth service embeds in the access tokens. See Section 46.3.7, "Understanding OAuth Access Token Custom Attributes" for more information about custom attributes.

  • Static Attributes - Attribute name and value pairs where the value is fixed at the time that you define the attribute. For example, name1=value1.

  • Dynamic Attributes - User-profile specific attributes.

46.4.6 Configuring User Profile Services

The following section describes how to use the console to configure the OAuth User Profile Service.

46.4.6.1 Creating a New User Profile Service

  1. Open the OAuth Services Configuration page as described in Section 46.2, "Opening the OAuth Services Configuration Page," then click the identity domain to open it.

  2. Click the Resource Servers tab.

  3. Click the Create button in the User Profile Services section.

46.4.6.2 Editing the User Profile Service

  1. Open the OAuth Services Configuration page as described in Section 46.2, "Opening the OAuth Services Configuration Page," then click the identity domain to open it for editing.

  2. Click the Resource Servers tab.

  3. In the User Profile Services section, click the service name to edit it. The OAuth User Profile Service Configuration page opens.

46.4.6.3 Understanding the OAuth User Profile Services Configuration Page

Use this page to configure the User Profile Service. This service supports OAuth 2.0 authorization and allows clients to interact with a back-end directory server and perform User Profile REST operations on Person, Group, and Relationship entities.

Identity Domain - The name of the identity domain to which this service profile applies. (Read-only)

Name - The name of this service profile.

Description - (Optional) A short description to help you or another administrator identify this service profile in the future.

Resource Server ID - The unique ID that OAuth Services created for this User Profile resource server. (Read-only)

Service Endpoint - The URI where the service receives and responds to create, read, update, and delete user profile service requests. Create a unique uniform resource identifier (URI) address for this service; for example, localhost:5575

Service Enabled - Select to enable the service, or clear the option box to disable it.

Allow Token Attributes Retrieval - Select this option to allow custom attributes (both attribute names and values) to be shared with clients. If enabled, the user consent form notifies the user that user-profile-specific details will be shared with the client. See Section 46.3.7, "Understanding OAuth Access Token Custom Attributes" for more information about custom attributes.

Authorization & Consent Service Plug-in - From the menu, choose an authorization plug-in for the service. This plug-in type defines security policy around interactions where authorization and user consent are granted. It can influence claims in a generated token as well.

Identity Store Name - The name of the identity store that contains the user records.

Protected by OAuth Service Profile - From the menu, choose the OAuth service profile that protects the user profile service.

Scopes

Configure individual permission settings for person, relationship, and group entities. The service uses the following default entity names:

  • /me - Designates operations that apply to the user logged in to the client

  • /users - Designates operations that apply to other users

  • /groups - Designates operations that apply to groups

URI - The URI segment for which the scope is defined.

Allow Read - Select to allow read operations for this scope.

Allow Write - Select to allow write operations for this scope.

Allow Anonymous Access - Select this option if you do not want to limit access, or clear this option to limit access by scope.

OAuth Scope - Type a scope definition. Use dot notation, for example: UserProfile.me.write

Description - Type a short note that describes the scope.

Require User Consent - Select to require the authorization server to display a user consent form so that the user can approve (or deny) the access request.

Offline Scope - Allows client applications to request a refresh token that can be used to obtain an access token even when the user is offline or not present. Client applications use the refresh token to get a new access token to access resources. See Section 45.2.6, "Understanding Refresh Tokens" for more information.

Token Settings

Override the default settings - Select this option if the token settings defined on the resource server configuration page should override the default token settings defined on the OAuth service profile page.

Token Name - The name of the token.

Expires - The length of time in minutes after which the token is no longer valid.

Refresh Token Enabled - Select this option to allow a refresh token to be used. A refresh token cannot be used with a client verification code or an authorization code. See Section 45.2.6, "Understanding Refresh Tokens" for more information.

Refresh Token Expires - The length of time in minutes after which the refresh token is no longer valid.

Life Cycle Enabled - Select this option if the OAuth server should cache the token and save it in the database until the token expires.

Attributes

Use this section to define user-profile specific (dynamic) attributes.

Table 46-7 User Profile Service Attributes

Name Value Notes

accessControl

false

  

adminGroup

cn=Administrators,ou=groups,ou=myrealm,dc=base_domain

  

selfEdit

true

  

Resource URIs

Use this section to enable or disable the /me, /users, and /groups services, and define the service endpoint URIs and provider implementation class paths for these services.

Service Endpoint - The URI where the service receives and responds to service requests. Create a unique uniform resource identifier (URI) address for this service; for example, localhost:5575

Service Enabled - Select to enable the service, or clear the option box to disable it.

Provider Implementation Class - The name of the Java class that implements the user profile service provider.

Entities - Use the fields in this section to configure entity relationships.

  • Name - The name of the defined entity.

  • Identity Directory Service Relation - Choose the directory service relationship that is to be accessed by the End Point segment.

  • End Point - Type a URI segment that will be used to access a corresponding data column in the Identity Directory service. For example, if memberOf is the End Point URI, then:

    http://host:port/.../idX/memberOf

    would be the URI to access related entities of an entity with ID idX.

  • Source Entity URI - The URI (or URL) of the source entity.

  • Destination Entity URI - The URI (or URL) of the destination entity.

  • Scope for Requesting Recursion - Use Scope attribute values with the scope query parameter to retrieve a nested level of attributes in a relationship search. To access related entities recursively, type the value to be used. The default configuration uses two scope attribute values: toTop and all. If the Scope for Requesting Recursion value is the attribute value all, then the following REST URI example is used to make the request:

    http://host:port/.../idX/reports?scope=all

    In this example, the URI returns the entities related to the entity with ID idX, as well as all further related entities.

Attributes - Use this section to define user-profile entity specific (dynamic) attributes.

46.4.7 Configuring OAuth Consent Management Services

See Section 46.3.6, "Understanding OAuth Consent Management Service Configuration" for introductory information about the OAuth consent management service. The following section describes how to use the user interface to configure the consent management service.

46.4.7.1 Creating a New Consent Management Service

  1. Open the OAuth Services Configuration page as described in Section 46.2, "Opening the OAuth Services Configuration Page," then click the identity domain to open it.

  2. Click the Resource Servers tab.

  3. Click the Create button in the Consent Management Services section.

46.4.7.2 Editing the Consent Management Service

  1. Open the OAuth Services Configuration page as described in Section 46.2, "Opening the OAuth Services Configuration Page," then click the identity domain to open it for editing.

  2. Click the Resource Servers tab.

  3. In the Consent Management Services section, click the service name to edit it. The OAuth Consent Management Service Configuration page opens.

46.4.7.3 Understanding the OAuth Consent Management Service Configuration

The Consent Management service handles consent storage, retrieval, revocation, and consent validation operations.

Identity Domain - The name of the identity domain to which this consent management service applies. (Read-only)

Name - The name of this consent management service.

Description - (Optional) A short description to help you or another administrator identify this service in the future.

Resource Server ID- The unique ID that the authorization server created for this resource server during registration. (Read-only)

Service Endpoint - The URL where the Consent Management Service receives and responds to client and resource owner service requests.

Service Enabled - Select to enable the service, or clear the option box to disable it.

Allow Token Attributes Retrieval - Select this option to allow custom attributes (both attribute names and values) to be shared with clients, resource servers, and the resource owner.

Authorization & Consent Service Plug-in - From the menu, choose an authorization plug-in for the service. This plug-in type defines security policy around interactions where authorization and user consent are granted. It can influence claims in a generated token as well.

Protected by OAuth Service Profile - From the menu, choose the OAuth service profile that protects the consent management service.

Scopes

URI - The URI segment for which the scope is defined.

Allow Read - Select to allow read operations for this scope.

Allow Write - Select to allow write operations for this scope.

Allow Anonymous Access - Select this option if you do not want to limit access, or clear this option to limit access by scope.

OAuth Scope - Type a scope definition. Use dot notation, for example: UserProfile.me.write

Description - Type a short note that describes the scope.

Require User Consent - Select to require the authorization server to display a user consent form so that the user can approve (or deny) the access request.

Offline Scope - Allows client applications to request a refresh token that can be used to obtain an access token even when the user is offline or not present. Client applications use the refresh token to get a new access token to access resources. See Section 45.2.6, "Understanding Refresh Tokens" for more information.

Token Settings

Override the default settings - Select this option if the token settings defined on the resource server configuration page should override the default token settings defined on the OAuth service profile page.

Token Name - The name of the token.

Expires - The length of time in minutes after which the token is no longer valid.

Refresh Token Enabled - Select this option to allow a refresh token to be used. A refresh token cannot be used with a client verification code or an authorization code. See Section 45.2.6, "Understanding Refresh Tokens" for more information.

Refresh Token Expires - The length of time in minutes after which the refresh token is no longer valid.

Life Cycle Enabled - Select this option if the OAuth server should cache the token and save it in the database until the token expires.

Attributes

Use this section to define custom attributes

Resources URIs

Use this section to enable or disable the retrieve, grant, and revoke services. You can also define the service endpoint URIs and provider implementation class paths for these services.

Service Endpoint - The URI where the service receives and responds to requests. Create a unique URI address for this service.

Service Enabled - Select to enable the service, or clear the option box to disable it.

Provider Implementation Class - The name of the Java class that implements this consent management service provider.

46.4.8 Configuring OAuth Plug-Ins

Use this page to configure OAuth security plug-ins.

  • The Adaptive Access Plug-ins run fraud detection and risk analysis policy checks, enhancing authenticity and the trust level of a user.

  • The Custom Token Attributes Plug-ins define security policy around the token service provider.

  • The Authorization and Consent Service Plug-ins define security policy around interactions where authorization and user consent are granted. This plug-in can influence claims in a generated token as well.

  • Within an OAuth identity domain, the Client Plug-ins define a security policy for OAuth clients, and the Resource Server Profile Plug-ins defines a security policy for resource servers.

46.4.8.1 Creating a new OAuth Plug-in

  1. Open the OAuth Services Configuration page as described in Section 46.2, "Opening the OAuth Services Configuration Page," then click the identity domain to open it.

  2. Click the OAuth Plug-ins tab.

  3. Click the Create button in one of the plug-in category sections.

    The Plug-in Configuration page opens.

46.4.8.2 Understanding the Plug-in Configuration Page

Use this page to add an OAuth plug-in to an identity domain or edit an existing plug-ins configuration information.

Identity Domain - The name of the identity domain where the plug-in is located.

Name - The name of the plug-in.

Description - (Optional) A short description to help you or another administrator identify this plug-in in the future.

Security Handler Class - Choose the Java class that defines the Security Handler Plug-in.

Attributes - Use this section to define custom plug-in attributes.

46.4.9 Configuring OAuth Server Settings

Use the OAuth Server Settings Configuration page to configure general server settings for the identity domain named.

Note:

See Section 41.1.2, "Deploying Mobile and Social" for information about deploying Mobile and Social with a WebGate.

Identity Domain - The name of the identity domain to which the settings on this configuration page apply. (Read-only)

HTTP Proxy Settings

Configure the following settings if a proxy server is in place between the OAuth Token Service (the Push Service) and the Apple Push Notification Service (APNS) or Google Cloud Messaging (GCM) service.

Proxy URL - Choose the protocol to use to connect to the proxy server (HTTP or HTTPS), then type the proxy server host name and port number.

Proxy Authentication - Type the user name and password required to authenticate with the proxy server.

Apple Push Notification

Configure the default values that should be used for this identity domain. Use the OAuth Mobile Client Configuration page to customize these settings on an app by app basis.

Minimum Connection Pool Size - Specifies the minimum number of connections in the connection pool.

Maximum Connection Pool Size - Specifies the maximum number of connections in the connection pool.

Keep Alive - The Apple Push Notification keep alive value in seconds.

Token Life Cycle Management

Maximum Search Results - Specify the maximum number of token entry search results that should be returned on the Token Life Cycle Management page.

Attributes

Attributes - Use this section to define custom attributes.

Table 46-8 OAuth Server Settings Attributes

Name Value Notes

wgAuthnUserHeader

OAM_REMOTE_USER

This attribute usage is optional. If an OAM WebGate is front ending/proxying requests to an OAuth server, set this attribute. The OAM WebGate sets the OAM_REMOTE_USER header to identify the authenticated user. If a deployment uses another header name instead of OAM_REMOTE_USER, then this attribute needs to be set with that header name.

46.4.10 Configuring the OAuth Services Jail Breaking Detection Policy

See Section 46.4.10, "Configuring the OAuth Services Jail Breaking Detection Policy" for introductory information about the jail breaking detection policy. The following section describes how to use the user interface to configure the policy.

Jailbreak Detection - Select Enabled to turn the Jail Breaking Detection policy on, or clear this option to turn it off for all client application instances. If you enable the Jail Breaking Detection Policy here, you can disable it on an application by application basis. If you disable the Policy here, you cannot enable or disable the feature on an application by application basis.

Policy Statements

Policy Statements - Use the buttons in the menu to add, delete, and re-order policy statements.

Policy Statement Conditions

Enabled - Select this option to activate the policy statement condition.

Minimum OS Version - The minimum iOS version to which the policy applies. If the value is 1.0, the policy will apply to iOS devices running at least version 1.0 of iOS.

Maximum OS Version - The maximum iOS version to which the policy applies. If the value is empty, a maximum iOS version number is not checked so the policy applies to any iOS version higher than the value specified for Min OS Version.

Minimum Client SDK Version - The minimum Mobile and Social Client SDK version number. For example, 11.1.2.0.0.

Maximum Client SDK Version - The maximum Mobile and Social Client SDK version number. For example, 11.1.2.2.0.

Policy Statement Detection Logic

Policy Expiration Duration - Type the length of time in seconds that the SDK on the mobile client device should wait before expiring the local copy of the policy and retrieving a newer version.

Auto Check Period - Type the interval of time in minutes that the client device should wait before executing the Jail Breaking Detection Policy statements again.

Detection Location - The iOS client device uses a logical-OR operator to evaluate Policy statements. Add a Detection Location as follows:

  • File Path - Type the absolute path to the file or directory on the device for which the Detection Policy should search.

  • Action - Select Exists which instructs the Detection Policy to evaluate whether it can access a file path.

  • Success - Select if the Policy should flag the device as jail broken if the specified files or directories are found on the device. Use this option if the policy is checking for unauthorized files or directories. Clear this option if the Policy should flag the device as jail broken if the specified files or directories are not found. (Use this option if checking for required files or directories.)

46.4.11 Configuring Token Life Cycle Management

Use this screen to search for and revoke tokens that have been issued. You can search for tokens using criteria such as user ID, client ID/name, client IP address, service profile, assertion token category, and token creation/expiration time. Enter your criteria and click Search. The maximum number of token entry search results returned is determined by the Maximum Search Results setting on the OAuth Server Settings page.

Search Criteria

Identity Domain - The name of the identity domain that you are searching for tokens. (Read only)

User - Specify an LDAP UID (john.smith) or an LDAP Fully Qualified DN (cn=jane.smith,dc=example,dc=com) to search by.

Client - Specify a client ID to search for tokens by.

Client IP Address - Specify a client IP address (for example, 192.168.100.1) to search for tokens by

Service Profile - Choose a profile from the menu, or leave this selection empty.

Assertion Token Category - Choose a category from the menu, or leave this selection empty.

Token Issued - Search for tokens by the date and time that they were issued.

Token Expiring at - Search for tokens by the date and time that they expire.

Mobile Device Claim Attributes

IMEI - Specify the unique 15-digit IMEI (International Mobile Equipment Identity) code to search by. The IMEI can be displayed on most mobile handsets by dialing *#06#.

MAC Address - Specify the unique MAC (Media Access Control) address to search by.

Phone Number - Specify a phone number to search by.

46.5 Configuring OAuth to Accept Third-Party JWT Bearer Assertions

The Oracle Access Management OAuth Service accepts third-party (non-Oracle) JWT assertions. You must, however, configure a trust relationship by adding the third-party's certificate into the OAuth Service Profile keystore. The service uses the keystore to verify the JWT assertion's digital signature. Create a separate keystore for each OAuth Service Profile that needs its own signing certificate. This section covers the following topics:

46.5.1 Understanding the default OAuth Service Profile Keystore

The role of the OAuth Service Profile is described in Section 46.3.3, "Understanding OAuth Service Profiles Configuration." The default OAuth Service Profile (OAuthServiceProfile) included in the DefaultDomain uses the Java Keystore (JKS) included with Oracle Access Management. The default service consists of the following files.

Table 46-9 Default OAuth JKS Keystore File and Settings File

File Path

JKS keystore file

$DOMAIN_HOME/config/fmwconfig/default-keystore.jks

Keystore settings file

$DOMAIN_HOME/config/fmwconfig/jps-config.xml

Note:

Oracle Web Services Manager also uses the default-keystore.jks service. For details see Section 37.2.2, "About the Oracle Web Services Manager Keystore (default-keystore.jks)."

You can use the following Java keytool command to list all of the private key and certificate information in the default keystore (default-keystore.jks).

keytool -list -keystore default-keystore.jks

46.5.2 Creating a Non-Default Keystore for an OAuth Service Profile

The steps in this section describe how to do the following:

  • Create a separate keystore to store the third-party's certificates

  • Import the certificates into the keystore

  • Configure the keystore

  • Add the keystore service to the appropriate OAuth Service Profile

Create the Keystore

Create a new Java Keystore (JKS) using the keytool utility that is distributed with the Java JDK.

  1. Go to $JDK_HOME/jdk/bin and open a prompt.

  2. Using keytool, generate a key pair:

    keytool -genkeypair -keyalg RSA -dname dname

    -alias aliasname -keypass key_password -keystore keystore

    -storepass keystore_password -validity days_valid

    Where:

    • dname is the X.500 Distinguished Name to be associated with alias, and is used as the issuer and subject fields in the self-signed certificate. This can be any string as long as it's in the correct format (for example, cn=spaces,dc=example,dc=com).

    • aliasname is a short name that identifies the new keystore entry

    • key_password is the password for the new public key

    • keystore is the keystore name, (for example, oauth-xyz-keystore.jks)

    • keystore_password is the keystore password

    • days_valid is the number of days for which the certificate should be considered valid (for example, 1064).

    Example 46-1 Creating the Keystore

    keytool -genkeypair -keyalg RSA -dname "cn=spaces,dc=example,dc=com" 
-alias oauthkey -keypass password123 -keystore oauth-xyz-keystore.jks 
-storepass passwordxyz -validity 1064

Load the Certificates Into the Keystore

Use the keytool utility to import the certificates into the keystore.

  1. Using keytool, type the following command:

    keytool -importcert -alias aliasname -file certfile

    -keystore keystore -storepass keystore_password

    Where:

    • aliasname is a short name that identifies the keystore

    • certfile is the file containing the certificates to load

    • keystore is the keystore name, (for example, oauth-xyz-keystore.jks)

    • keystore_password is the keystore password

    Example 46-2 Loading the Certificates

    keytool -importcert -alias oauthkey_123 -file samplekey.cer -keystore oauth-xyz-keystore.jks -storepass passwordxyz

Add the Keystore Instance to jps-config.xml

Configure the keystore service and update the credential store so that OAM can read the keystore and keys correctly. In the jps-config.xml keystore settings file, add the following new keystore service instance in the <serviceInstances> element.

  1. In a text editor, open the keystore settings file:

    $DOMAIN_HOME/config/fmwconfig/jps-config.xml

  2. Find the <serviceInstances> node for the keystore.provider Provider, and add the following:

    <serviceInstance name="<service-instance-name>" provider="keystore.provider" location="<keystore-location>">
  <property name="keystore.provider.type" value="db"/>
  <property name="keystore.sig.csf.key" value="sign-csf-key"/>
  <property name="keystore.enc.csf.key" value="enc-csf-key"/>
  <property name="keystore.csf.map" value="oracle.oauth.security"/>
  <property name="keystore.pass.csf.key" value="keystore-csf-key"/>
  <property name="keystore.type" value="JKS"/>
  <propertySetRef ref="props.db.1"/>
</serviceInstance>

    Where:

    • service-instance-name = Any service-instance-name

    • keystore-location = Path to the keystore file

    Example 46-3 Update jps-config.xml

    <serviceInstance name="oauth-xyz-keystore.db" provider="keystore.provider" location="./oauth-xyz-keystore.jks">
  <property name="keystore.provider.type" value="db"/>
  <property name="keystore.sig.csf.key" value="sign-csf-key"/>
  <property name="keystore.enc.csf.key" value="enc-csf-key"/>
  <property name="keystore.csf.map" value="oracle.oauth.security"/>
  <property name="keystore.pass.csf.key" value="keystore-csf-key"/>
  <property name="keystore.type" value="JKS"/>
  <propertySetRef ref="props.db.1"/>
</serviceInstance>

  3. Find the <jpsContexts> node and add the new service instance into the default context section. The following example shows the addition of a <serviceInstanceRef> element with a ref to the oauth-xyz-keystore.db service instance (defined in the previous step).

    Example 46-4 Adding the new Service Instance

    <jpsContexts default="default">
  <jpsContext name="default">
     <serviceInstanceRef ref="oauth-xyz-keystore.db"/>
     ... other serviceInstanceRef elements ...
  </jpsContext>

Create a CSF Entry for the Keystore Service Instance

Use the following WLST commands to create the necessary Credential Store Framework (CSF) entries. Restart the server when you are done.

createCred(map="oracle.wsm.security", key="sign_csf_key", user="alias_name", password=keystore_password, desc="Description of the signing key credential")

createCred(map="oracle.wsm.security", key="enc_csf_key", user="alias_name", password=keystore_password, desc="Description of the encryption key credential")

createCred(map="oracle.wsm.security", key="keystore_csf_key", user="oauth", password=keystore_password, desc="Description of the keystore credential")

Where:

  • sign_csf_key = the password for the signing key

  • alias_name = the alias name for the key

  • keystore_password = the keystore password

  • enc_csf_key = the password for the encryption key

  • keystore_csf_key = the password for the keystore

Example 46-5 Creating Credential Store Entries

createCred(map="oracle.wsm.security", key="oauth-sign-csf-key", user="ms-oauth-key", password=passwordxyz, desc="Signing key credential")

createCred(map="oracle.wsm.security", key="oauth-enc-csf-key", user="ms-oauth-key", password=passwordxyz, desc="Encryption key credential")

createCred(map="oracle.wsm.security", key="keystore_csf_key", user="oauth", password=passwordxyz, desc="Keystore credential")

Add the Provider Service Name to the OAuth Service Profile

Apply the updated configuration to the OAuth Service Profile. See Section 46.4.2.1, "Creating an OAuth Service Profile" if you have not yet created an OAuth Service Profile for the third-party service.

  1. Open the OAuth Services Configuration page as described in Section 46.2, "Opening the OAuth Services Configuration Page," then click the identity domain to open it for editing.

  2. Click the OAuth Service Profiles tab.

  3. Click the Service Profile name in the table.

  4. Expand the Attributes section.

  5. Add the keystore service information you configured in Example 46-4, "Adding the new Service Instance" to the Attributes table using the keystore.service name. Refer to the following screen capture.

    Description of oauthservprofilexyz.gif follows
    Description of the illustration oauthservprofilexyz.gif

46.5.3 Configuring an OAuth Service Profile for Third-Party JWT Assertion Validation

This section describes how to configure OAuth services to support JWT bearer assertion validation. For each token provider, configure the following:

  • The JWT bearer assertion issuer name(s). This is a required attribute.

  • The key ID (KID) for the certificate alias. This is an optional attribute.

Configure the JWT bearer assertion issuer name(s) as follows:

Attribute Name Attribute Value
jwt.trusted.issuer.1

jwt.trusted.issuer.2

...

jwt.trusted.issuer.n

 alias-1 <cert-alias-name in keystore>

alias-2 <cert-alias-name in keystore>

...

alias-n <cert-alias-name in keystore>

Configure the key ID as follows:

Attribute Name Attribute Value
jwt.trusted.issuer.size n

Where n is the number of configured issuer alias names

The OAuth server has to Base64 decode the JWT assertion to validate it. The server looks for the issuer name, and the signing method and key ID values.

If the signing method and the key ID value are not included, the system uses the issuer name to get the necessary configuration information. It then invokes the OPSS validation method. If the signing method and the key ID value are included, the system verifies that the information matches the configured values, and then invokes the OPSS validation method.

46.6 Configuring a WebGate to Support the OAuth Service

This section describes how to configure a WebGate for use with the OAuth Service. The WebGate serves as a proxy so that client authorization and token endpoint requests access the WebGate instead of accessing the Oracle Access Management server directly. These steps are for WebLogic environments only.

  1. Install the Oracle HTTP Server 11g WebGate for OAM using the instructions in Installing WebGates for Oracle Access Manager.

  2. Configure the WebGate by defining the following resource and creating an authentication policy and authorization policy.

    1. Open the Oracle Access Management console.

    2. Under Access Manager, click Application Domains. and click Search to view the Application Domains on the Search Application Domains page.

    3. Click to edit the Application Domain.

    4. On the Application Domains page, click the Resources tab.

    5. Create the following resource. If you are using the existing IAMSuiteAgent Host Identifier, the resource is already present and can be searched on using the Resource URL field.

      /ms_oauth/oauth2/ui/**

      Click to select the resource, then click the Edit button.

    6. Under the Protection heading, choose the following options from the menus and click Apply:

      Protection Level - Protected

      Authentication Policy - Protected HigherLevel Policy

      Authorization Policy - Protected Resource Policy

      These settings allow the WebGate to perform user authentication and user authorization.

    7. Add the following resources and set the Protection Level to Excluded:

      /ms_oauth/oauth2/endpoints/**
/ms_oauth/oauth2/oammsui/**
/ms_oauth/style/**
/ms_oauth/img/**
/oam/**

      The WebGate does not protect Excluded resources and allows them to be accessed.

  3. Add the following lines to the mod_wl_ohs.conf file and restart the WebGate. For WebLogicPort, be sure to add the managed port details for your environment.

    # the following directive proxies all the OAuth requests
<IfModule weblogic_module>
      WebLogicHost host123.us.example.com
      WebLogicPort 17100
      Debug ON
      WLLogFile /tmp/weblogic.log
      MatchExpression /ms_oauth/*
</IfModule>
# the following directive proxies all the OAM managed server requests. 
 
<IfModule weblogic_module>
      WebLogicHost host123.us.example.com
      WebLogicPort 17100
      Debug ON
      WLLogFile /tmp/weblogic.log
      MatchExpression /oam/*
</IfModule>

  4. Update the Access Manager Load Balancing settings as follows:

    1. Open the Oracle Access Management console.

    2. Under Configuration, click Access Manager Settings.

    3. In the Load Balancing section, change the OAM Server Host and the OAM Server Port settings to the WebGate's host and port settings.

    4. Click Apply.

  5. Complete the following steps.

    1. Open $ORACLE_HOME/ORACLE_IDM1/oam/server/apps/ and locate the oam-server.ear file. For example:

      cd /scratch/test/Oracle/Middleware/Oracle_IDM1/oam/server/apps

    2. Back up the .ear file:

      cp oam-server.ear oam-server.ear.original

    3. Create a temporary directory and go to that directory:

      mkdir tmp-ear 
cd tmp-ear/

    4. Extract the oam-server.ear file into the tmp-ear directory:

      jar -xvf ../oam-server.ear

    5. Create another temporary directory inside tmp-ear and go to that directory:

      mkdir tmp-ms-war
cd tmp-ms-war

      You should be in this directory:

      /scratch/test/Oracle/Middleware/Oracle_IDM1/oam/server/apps/tmp-ear/tmp-ms-war

    6. Extract the ms_oauth.war into the tmp-ms-war directory:

      jar -xvf ../ms_oauth.war

    7. Open the WEB-INF/web.xml file for editing and update it by adding comment tags around the security-constraint as follows:

      <!-- BEGIN: Comment the following security constraint if either the OAM WebGate is front-ending OAM in a WebSphere setup or if the WebLogic server Domain Agent is not used. 
    <security-constraint>
        <web-resource-collection>
            <web-resource-name>OAuthSecuredResources</web-resource-name>
            <url-pattern>/oauth2/ui/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>valid-users</role-name>
        </auth-constraint>
    </security-constraint>
 END of security constraint needing to be commented -->

    8. Recreate the .war file in the tmp-ms-war directory:

      jar cvf ms_oauth.war

    9. Copy the updated .war file to the parent directory, then remove the tmp-ms-war directory located in tmp-ear/:

      cp /scratch/test/Oracle/Middleware/Oracle_IDM1/oam/server/apps/tmp-ear/tmp-ms-war/ms_oauth.war /scratch/test/Oracle/Middleware/Oracle_IDM1/oam/server/apps/tmp-ear

rm -rf /scratch/test/Oracle/Middleware/Oracle_IDM1/oam/server/apps/tmp-ear/tmp-ms-war

    10. Create the oam-server.ear archive in the tmp-ear directory:

       jar cvf oam-server.ear .

    11. Copy the tmp-ear/oam_server.ear archive file to the parent directory:

      cp /scratch/test/Oracle/Middleware/Oracle_IDM1/oam/server/apps/tmp-ear/oam-server.ear /scratch/test/Oracle/Middleware/Oracle_IDM1/oam/server/apps/oam-server.ear

    12. Restart the WebSphere server.

    The WebGate will now reverse-proxy OAuth URLs as well as OAM managed server URLs. All authorization and token endpoint requests are now accessed using the WebGate host and port values instead of the actual OAM host and port values.