52.4 Understanding the OAuth Services Components

The following sections contain information about the Identity Domains configuration options. Information in the following sections applies to both Identity Federation and Mobile Security OAuth Services except for the Jailbreak Detection Policy which is specific to Mobile Security OAuth Services. See Configuring OAuth Services for details on configuring these components.

52.4.1 Identity Domains - Identity Federation and OAuth Services

Identity Domains are entities that contain all artifacts required to provide standard OAuth Services or Mobile OAuth Services.

Each Identity Domain is an independent entity. One of the primary use cases of the Identity Domain is for multi tenants deployments. Each Identity Domain will correspond to a tenant. This can apply to different departments in an organization if there is a need for independence. This will also be useful for cloud deployments where each Identity Domain can correspond to a separate tenant or entity. The following artifacts are just some of the components configured within an OAuth Services Identity Domain.

  • One or more Service Profiles

  • One or more Clients

  • A Service Provider

  • One or more Resource Servers

  • Plug-ins

  • Server Settings

  • Token Life Cycle Management (search for and revoke tokens across an Identity Domain)

For information on configuring Identity Domains, see Configuring Identity Domains.

52.4.2 Service Profiles - Identity Federation and OAuth Services

You can configure a service profile that defines clients, Custom and System Resource Servers, mobile service settings, and so on.

A Service Profile defines the following settings:

  • The clients with whom OAuth Services can interact

  • The Custom and System Resource Servers that OAuth Services protects and to which it provides access

  • Refresh token settings, token expiration settings, and the option to enable the token life-cycle management

  • The User Profile Service and Consent Management Service profiles

  • The enabled security profile plug-ins

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

  • The root URL for the OAuth Services endpoints

You can create multiple Service Profiles, if necessary. Different Service Profiles may be needed if different clients or resources need to be grouped, or different token settings are required, or there are different service endpoints with different configuration settings. Being able to create multiple Service Profiles gives flexibility to configuration options although in most cases it may not be needed. For information on configuring Service Profiles, see Configuring Service Profiles.

52.4.3 Clients - Identity Federation and OAuth Services

The Client initiates the OAuth protocol by invoking the OAuth Services.

Client profiles must be created using the OAuth Services interface (in the Oracle Access Management Console) before the protocol can be initiated. At a minimum, client profiles include the application name, a client ID, and one or more URIs to which OAuth Services will redirect the user-agent once access is granted or denied. An OAuth Services Client can be defined as Web, Public or Mobile.

  • Web clients are assigned with a client ID and secret. These clients can interact with the OAuth Services server by sending the client ID and secret as part of an authorization header. It is up to each individual client to determine how the secret issued to them is securely stored.

  • Public clients are assigned with a client ID but no secret. Typically these profiles pertain to browser based applications like Javascript or can be mobile based apps.

  • Mobile clients are assigned with a client ID and the secret is dynamically generated as part of a mobile client's registration flow with OAuth Services. (The registration flow is proprietary and was developed by extending the OAuth specification.)

The client ID and secret are explained in the following bullet points.

  • The Client ID is a unique string that represents the registration information and is required for each client. You can create a unique client ID or have OAuth Services generate one. OAuth Services compares the defined Client ID with the value the client sends over HTTPS or HTTP as part of an authorization request. If the values do not match, the request is rejected. Client IDs are Base64 encoded when they are sent as authorization header.

  • The Client secret is the client password. You can create a unique client secret or have OAuth Services generate one. Web clients are required to have a Client ID and a Client secret. Mobile clients and Public clients, on the other hand, do not have a client secret and are given only a Client ID.

To request an access token, the client obtains authorization from the resource owner. The authorization is expressed in the form of an authorization grant, which the client uses to request the access token.The OAuth 2.0 specification provides authorization grant types for different security use cases. OAuth Services has implemented some of these grant types. Web, Public and Mobile Clients can access the various OAuth Services grant types that are appropriate to them. For example, the Client Verification Code grant type is only relevant to mobile clients. The following grant types are supported by OAuth Services.


(For general information about the OAuth specification grant types, see http://tools.ietf.org/html/rfc6749#section-1.3.

  • Authorization Code - The Resource Owner logs in using Oracle Access Management. The token endpoint exchanges the authorization code along with client credentials for an access token. The Authorization Code grant type is required for 3-legged flows.

  • Resource Owner Credentials - The Resource Owner provides the client with a 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. The Resource Owner Credentials grant type is required for 2-legged authorization scenarios.

  • 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. The Client Credentials grant type is required for 2-legged authorization scenarios.

  • Refresh Token - Select this option to return a refresh token together with an access token in the token response. See About OAuth Services Tokens for more information.

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

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

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

  • Client Verification Code - Used by Mobile OAuth Services clients to request a pre-verification code which subsequently gets used in mobile client flows.

Privileges and Allowed Scopes can also be configured on a client by client basis. OAuth Services allows for the configuration of scopes to bypass the need for user consent. Thus, you can configure Privileges to define which clients are allowed which grant types. If applicable, the Client will then obtain an authorization grant that can be exchanged with OAuth Services for an access token. For information on configuring Clients, see Configuring Clients.

52.4.4 Service Providers - Identity Federation and OAuth Services

The Service Provider settings are used to manage the connection between OAuth Services and Access Manager, the back-end authorization Service Provider that supports OAuth Services. The OAuthServiceProvider is the default Service Provider for the DefaultDomain Identity Domain although a Custom Service Provider can be created.

In this release, OAuth Services provides support for both OAM authentication (most authentication modules can be invoked, usually user/credential based plugins) and IDS authentication. Any features not provided through OAM or IDS authentication will require a custom service provider. Each Identity Domain can only have one Service Provider.


Currently, authentication modules that have multi step orchestration in OAM can not be invoked; this refers to 2-legged OAuth Services scenarios. For 3-legged scenarios, there is no limitation on invoking OAM authentication modules because authentication is done through a browser flow.

For information on configuring Service Providers, see Configuring the Service Provider.

52.4.5 Resource Servers - Identity Federation and OAuth Services

Resource Servers settings are independently configured in a profile for each remote resource server that contains applications or services to be protected by OAuth Services.

The Resource Server profile does not define the resource server specific settings like the endpoint or security protection - only OAuth Services related configurations.

Part of the Resource Server configuration involves defining scope. Scope determines the range of access the Client will have to the protected resource. Based on the scope setting, Oracle Access Management restricts access and informs the Client of the scope in the access token issued. Thus, an OAuth Services access token with proper scope needs to be obtained in order for a Client application to access a Resource Server.

The client provides a scope string in it's request to OAuth Services. The scope can be a URL or a string literal. After successful authentication and authorization, OAuth Services includes the scope in the Access Token. For example, if an OAuth client requests access to a resource for a specific end user, OAuth Services would create an Access Token with the scope defined as UserProfile.me and the client could access the User Profile Resource Server with the /me endpoint. (See Table 52-1.) In turn, the User Profile Resource Server will decide whether the client can access the resource with acquired access token or not. The following is true in regards to scope.

  • A Resource Server can have one or more scope(s) associated with it.

  • Multiple Resource Servers can be created if there is a need, for example, to have different token settings or to modify the default security protection (like not allowing revocation of consent). Each will have it's own set of scope definitions. This is not a common scenario

  • The client sends the scope parameter as part of an authorization request. If any part of the scope parameter value is invalid, OAuth Services sends the client application an invalid_scope error response. If the scope parameter value is valid, it gets embedded as part of the authorization code and access tokens.

OAuth Services provides two out-of-the-box services modeled as Resource Servers and protected with an Access Token. For information on the User Profile Services and Consent Management Services Resource Servers, see the following sections.

For configuration information, see Configuring Custom Resource Servers, Configuring User Profile Services, and Configuring Consent Management Services. User Profile Services

The default UserProfile User Profile Services configuration is a Resource Server created during Oracle Access Management OAuth Services installation.

This configuration allows your organization to use OAuth 2.0 to interact with a back-end LDAP directory server and perform the REST operations documented in Table 52-1 on Person, Group, and Relationship entities. See the Oracle Fusion Middleware Developer's Guide for Oracle Access Management for more details on using REST to interact with the User Profile Services.

Table 52-1 Default User Profile Services Endpoint Operations

Resource Endpoint (URI) HTTP(S) Methods Use Details

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

GET allows read

PUT allows update

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

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

GET allows read, search

POST allows create

PUT allows update

DELETE allows delete

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

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

GET allows read, search

POST allows create

PUT allows update

DELETE allows delete

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

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

GET allows read

POST allows create

DELETE allows delete

Used by Oracle Mobile Authenticator to read, create or delete secret key for given user. The secret key is used by OMA to generate a one time pin.

User Profile Services receives and responds to HTTPS requests using the service-specific endpoints for Person, Group, and Relationship entities. Each service endpoint can be individually disabled if it is not needed. If there are users across multiple user repositories, you can create multiple instances of User Profile Services; for example, if a company uses different repositories for different organizations this would be useful. Creating multiple user profile services may not be common though. See Introducing User Profile Services for more information. For information on configuring User Profile Services, see Configuring User Profile Services. The following sections contain details on specific User Profile Services configurations. Proxy Authentication

Proxy authentication allows a user to control the security of middle tier applications by preserving client identities and privileges through all tiers, and auditing actions taken on behalf of clients.

For example, this feature allows the identity of a user using a web application (also known as a "proxy") to be passed through the application to the database server. Oracle Unified Directory (OUD) and Active Directory (AD) are few directory servers that support proxy authentication. Proxy authentication delivers the following security benefits.

  • A limited trust model, by controlling the users on whose behalf middle tiers can connect, and the roles the middle tiers can assume for the user.

  • Accountability, by preserving the identity of the real user through to the database, and enabling auditing of actions taken on behalf of the real user.

  • Flexibility, by supporting environments in which users are known to the database, and in which users are merely "application users" of which the database has no awareness.

Oracle Access Management provides the ability to add proxy authentication features on top of directory servers that do not support it. The Access Control option is simply Proxy Authentication support for directory servers that do not have built in support for proxy authentication.

Proxy Authentication and Access Control were previously available in Mobile Services and now this support is available in OAuth Services. Without Proxy Authentication or Access Control enabled, communication with directory servers is done using the administrator user account; in this case, the administrator can perform any operations on any user. By enabling this feature, the logged in user can only perform operations for which privilege has been granted. Securing User Profile Services Activity

Security considerations are very important when implementing User Profile Services.

For example, a user with write access to UserProfile.me can change their own UID or mail address causing a serious breach. Because of this it is possible to limit the scope of all URI to read only and you should be careful about granting write access to any scope. You can also configure read and write access independently on a per-attribute basis.

Security protection is defined within the Scopes table of the configured User Profile Service. Adding a URI allows you to select whether the service endpoint is enabled, whether read or write access is allowed, whether the URI is protected by an access token, and whether user consent is required.

The Oracle Access Management Console also allows fine-grained configuration of the attributes that can be modified. You can also add custom attributes or remove default attributes. Table 52-2 documents the out-of-the box configurable attributes for each scope setting.

Table 52-2 User Profile Resource Server - Scope Settings

Scope HTTP(S) Method Resource URI Attributes





uid, mail, description, commonname, firstname, lastname







uid, mail, description, commonname, firstname, lastname







name, description






There are no attributes needed. Entity Relationship

An entity relationship is an association between two entities such as Users and Groups.

The entity types can be the same or different. For example, the memberOf entity is a relationship between a user and a group while the manager entity is a relationship between two users. Client applications can create, read or delete relationships using the User Profile Services relationship endpoint. The following REST operations illustrate how to create a memberOf relationship. In these examples, the relationship endpoint is memberOf, the source entity URI is user-uri and the destination-entity URI is group-uri.

Create User "John"

curl -H "Content-Type: application/json" --request POST http://localhost:port/ms_oauth/resources/userprofile/users -d '{"uid":"John"Anderson","commonname":"John Anderson","firstname":"John"}'

Create Group "Group1"

curl -H "Content-Type: application/json" --request POST http://localhost:port/ms_oauth/resources/userprofile/groups -d  '{"description":"group1 testing","commonname":"group1"}'

Create memberOf relationship

curl -H "Content-Type: application/json" --request POST http://localhost:port/ms_oauth/resources/userprofile/users/memberOf -d '{"group-uri":"\/idaas_rest\/rest\/userprofile\/group\/group1", "user-uri":"\/idaas_rest\/rest\/userprofile\/people\/John"}' Consent Management Services

The default Consent Management Services configuration is labeled ConsentManagement and handles consent storage, retrieval, revocation, and consent validation operations. If you select the Require User Consent option Oracle Access Management displays to the user a consent form so that access to the requested resource can be approved or denied by the user. 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. Consent data is stored in the Oracle Access Management database. For information on configuring Consent Management Services, see Configuring Consent Management Services.


The Clients configuration page has a Bypass User Consent option. If this option is selected, the Client setting overrides the Resource Server setting. For information on configuring Clients, see Configuring Clients.

Any consent operation requires an access token of the Client Credentials grant type (as discussed in Clients - Identity Federation and OAuth Services) and the desired Consent Management scope. A user (through the client) requests access to a resource protected by OAuth Services. The request contains an access token, the client identifier and the user identifier. OAuth Services retrieves the configured scopes and, if allowed, grants consent by adding the scope to the access token. The access token is added to the authorization header in the HTTP request which is used to retrieve, grant or revoke consent using the endpoints provided by the Consent Management Service. For details on using REST interfaces to interact with Consent Management Services, see Oracle Fusion Middleware Developer's Guide for Oracle Access Management.


Multiple Consent Management Services are not necessary.

52.4.6 Plug-Ins - Identity Federation and OAuth Services

Plug-ins enhance security by consulting additional logic for trust and risk analysis. (Such additional logic may deny certain risky operations.) Plug-ins apply the logic during authentication operations, including client application registration for mobile apps.

The following plug-in types are available for use with OAuth Services and Mobile OAuth Services.

  • The Custom 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 type can influence claims in a generated token as well.

  • The Client Plug-in defines a security policy for Clients in an Identity Domain.

  • The Resource Server Profile Plug-in defines a security policy for Resource Servers in an Identity Domain.

The following plug-in types are available for use with Mobile OAuth Services only:

  • The Mobile Security Manager Plug-in is for use with Oracle Mobile Security Suite (OMSS). The Mobile Security Manager (MSM) component (part of OMSS) collects a rich set of mobile device data. This plug-in gathers that information and also invokes the MSM compliance policy, which checks the compliance status of the device. Finally, the plug-in sends the device information and the compliance status to the Adaptive Access Plug-in. For information about configuring the Mobile Security Manager plug-in, see Plug-in Configuration Page.

  • The Adaptive Access Plug-in is for use with Oracle Adaptive Access Manager (OAAM). It runs fraud detection and risk analysis policy checks that further validates that the user connection is authentic and can be trusted. The Adaptive Access Plug-in can utilize mobile device attribute values collected by the Mobile Security Manager Plug-in, or, if Oracle Mobile Security Suite is not available, the Adaptive Access plug-in can use mobile device attribute values that the Mobile OAuth Services obtains during mobile app requests. If the Mobile Security Manager Plug-in is active, it runs first and passes device data to the Adaptive Access Plug-in, which runs second.

    For more information, see OAuth Services Plug-ins.

For each plug-in type only one instance can be active at a time at the service profile level. For example, you can create and save different instances of the Client Plug-in at the Identity Domain level, but at the Service Profile level you can only assign one Client Plug-in instance at a time. Optional plug-ins can be configured to provide additional security. For information on configuring plug-ins, see Configuring Plug-Ins.

52.4.7 Server Settings - Identity Federation and OAuth Services

The Server Settings page is for configuring general server settings for the Identity Domain under which it is accessed.

For information on configuring Server Settings, see Server Settings.

52.4.8 Jailbreak Detection Policy - OAuth Services

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

This setting tab is displayed and for use with Mobile OAuth Services only. For information on configuring the Jailbreak Detection Policy, see Jailbreak Detection Policy.

52.4.9 Token Life Cycle Management - Identity Federation and OAuth Services

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. Using the Token Life Cycle Management page, you can revoke a token that have been issued.

For information on configuring Token Life Cycle Management, see Token Life Cycle Management.