1 Using OAuth With Services Gatekeeper

Using SAML Assertions to Access Resources

You can use Security Assertion Markup Language (SAML) credentials to gain access to resources protected by OAuth 2.0 in Services Gatekeeper. This enables you to combine the centralized identity management of Access Manager and an existing trust relationship with identity management.

You can create single sign on (SSO) features that provide your subscribers with one authorized SAML token (federated identity) for use in accessing multiple third-party resources that you support. Services Gatekeeper acts as the SSO authorization server for SSOs that you create using an identity management system such as Oracle Identity Management (OIM). OIM is a subset of the Oracle Fusion Middleware Identity and Access Management product.

See "Support For SAML Assertions", "Understanding the Services Gatekeeper Authorization Server", and "Configuring SAML (Optional)" for details.

The Oracle Fusion Middleware WebLogic server provides the underlying support for SAML capabilities. For details see ”Security Assertion Markup Language (SAML)” in Oracle Fusion Middleware Understanding Security for Oracle WebLogic Server 12c here:

http://docs.oracle.com/cd/E24329_01/web.1211/e24446/security.htm#INTRO232

Understanding OAuth Terminology

Table 1-1 lists OAuth terminology and definitions.

About the OAuth/Services Gatekeeper Entities and Their Relationships

Figure 1-1 shows an example OAuth protocol flow for a resource access request:

(A) The client requests authorization from the resource owner. The authorization request can be made directly to the resource owner (as shown), or preferably indirectly using the Authorization Server as an intermediary.
(B) The client receives an authorization grant, including a credential representing the resource owner's authorization, expressed using one of four grant types defined in this specification or using an Extension grant type. The authorization grant type depends on the method used by the client to request authorization and the types supported by the Authorization Server.
(C) The client requests an access token by authenticating with the Authorization Server and presenting the authorization grant.
(D) The Authorization Server authenticates the client and validates the authorization grant, and if valid issues an access token.
(E) The client requests the protected resource from the resource server and authenticates by resending the access token.
(F) The resource server validates the access token, and if valid, serves the request.

About the OAuth Protocol Endpoints

The OAuth specification defines three types of protocol endpoints.

• Redirection Endpoint: The redirection endpoint is a URI used by Authorization Server to return authorization credentials responses from the Authorization Server to the client using the resource owner user-agent.

• Authorization Endpoint: The authorization endpoint interacts with the resource owner (typically the subscriber) and obtain an authorization grant which will be issued to an application client by the resource owner. The Authorization Server must first verify the identity of the resource owner before granting the authorization grant. This authorization grant will be exchanged by the application client for an access token.

• Token Endpoint: The client uses the token endpoint to obtain an access token by presenting its authorization grant (the authorization code) or refresh token. The token endpoint is used with every authorization grant except for the implicit grant type (since an access token is issued directly).

OAuth Component to Services Gatekeeper Component Mapping

OAuth defines the following terms that map to the Services Gatekeeper concepts listed:

• resource: Defined by the OAuth specification. In Services Gatekeeper, a resource maps to the API(s) and methods protected by the OAuth token. This is a combination of communication service application-facing interface (Plug-in) name, method name, token expiration period, parameters, and the subResource. resource uniquely identified by scopeId.

  For more information, see "Understanding Resource Mapping".

• scope request parameter: Defined by the OAuth 2.0 specification and specified by the authorization server. Determines the limits of an OAuth token. A scope parameter defining these limits is submitted as part of obtaining an authorization grant.

  The format of the scope is defined in the OAuth specification as:

  scope = scope-token *(SP scope-token)
  scope-token = 1*(%x21 / %x23-5B / %x5D-7E)
  

  Services Gatekeeper maps the scope-token parameter to:

  <scopeId>[?<param>=<[&<param>>=<value]*]+
  

  Where:

  scopeId identifies a resource.

  param is a custom parameter defined as part of resource.

  value is the value for the resource.

  Parameter values submitted as part of the scope can be interpreted by custom interceptors.

  For example:

  scope=chargeAmount?MaxAmount=5&itemId=123SPgetLocation?Accuracy=5where
  SP=blank space
  

• scopeId: A unique identifier that represents an OAuth resource during resource mapping and determines the access scope of a resource during an authorization grant.

  Defined as part of mapping a communication service method as an OAuth resource, scopeId is used as the value of the id attribute of the resource tag. Each resource is indicated as owned by a resource owner by creating an association between the resource owner (subscriber URI) and the scopeId. The scopeId is submitted as part of scope-token parameter within the authorization grant request.

  For example:

  1. As part of resource configuration, the oracle.Services Gatekeeper.parlayrest.plugin.PaymentPlugin (communication service) method amountTransaction is created as a resource with scopeId chargeAmount:

     <resource id="chargeAmount" name="Charge or refund"
     interfaceName="oracle.Services Gatekeeper.parlayrest.plugin.PaymentPlugin"
     methodName="amountTransaction"
     tokenExpirePeriod="3600">
     <parameter name="code" description="billable item id"/>
     </resource>
     

  2. The chargeAmount resource is mapped to tel:1234 as the resourceOwner.

  3. During the authorization grant, the application sends scope=chargeAmount as part of the authorization request.

• resource owner: Defined by the OAuth2.0 specification. Represented as the target address used in the REST API (communication service), and typically represented as one MSISDN. The MSISDN serves as the connection between the resource defined during configuration time, and the resource protected during resource authorization and access time.

  • The resource owner (MSISDN) and the scopeId (collection of resources) are mapped during configuration time.

  • Depending on the grant type, the OAuth authorization code/access token is issued by the resource owner (MSISDN).

• subResource: A subResource protects and authorizes multiple resources (API methods) with a single token. Resources can have one or more subResources defined as part of resource definition. Authorization grants to a resource also applies to its subResources.

  For example, for a payment communication service, a resource called amountTransaction can be created for charging transactions. A subResource called checkTransactionStatus is a method used to query the status of a charging transaction. When a resource owner issues a token for resource amountTransaction, it can be automatically used against the checkTransactionStatus subResource as well.

• Application Client: You map a Services Gatekeeper Application Instance Id to an OAuth application client ID during client creation with the OAuthclientMBean. See "Managing Clients" for details.

Services Gatekeeper relies on the authentication endpoint to validate the resource owner. In the Services Gatekeeper default implementation of the authentication endpoint, the validation is handled by the Subscriber Manager. See "Mapping Resources to Resource Owners" for more information.

Understanding the OAuth Endpoints

Service Gatekeeper supports the standard endpoints defined in the OAuth 2.0 specification.

OAuth generates these endpoints that Services Gatekeeper uses:

• Redirection endpoint: Provided by an application client during the authorization grant.

• Authorization endpoint: The default authorization endpoint is configured to the following URL:

  https://Gatekeeper_server_IP:port/oauth2/authorize

• Token endpoint: By default, the token endpoint is configured to the following URL:

  https://Gatekeeper_server_IP:port/oauth2/token

In addition to the standard endpoints, Services Gatekeeper supports two custom endpoints to facilitate integration with external/custom Authentication Servers:

• Authentication Endpoint: Verifies the identity of a resource owner. The authentication endpoint is an extension point offered by Services Gatekeeper handling resource owner authentication and authorization grant collection.

  This endpoint interacts with a resource owner, assuring that the subscriber's identity is valid and providing necessary information for the resource owner to authorize an application to obtain an authorization grant.

  By default, the authentication endpoint uses the following URL:

  https://Gatekeeper_server_IP:port/oauth2/auth.jsp

  This URL can be updated by editing the following MBean property:

  OauthService.OauthCommonMBean.AuthenticationURL

• Grant Endpoint: The callback URI supported by Services Gatekeeper to process the successful authenticated requests and issue authorization grants to application clients.

  After a resource owner grants access to protected resources through authentication, the authorization request is submitted to the grant endpoint, which sends the resource requester to a redirect URI provided by the application along with the authorization code.

  By default, the grant endpoint uses the following URL:

  https://Gatekeeper_server_IP:port/oauth2/grant

  This URL can be updated by editing the following MBean property:

  OauthService.OauthCommonMBean.GrantURL

For more information about the interactions between these endpoints, see "Implementing a Third-Party Authentication Service".

Authentication of Network Flows

Services Gatekeeper provides OAuth security for RESTful Web services required by application-initiated or network-initiated traffic when the requests call API management APIs.

Mapping a Resource to a Services Gatekeeper Method

You can use OAuth token-based security to protect any RESTful communication service, including a customized communication service method, as long as the specified method is configured as a protected resource.

Figure 1-2 illustrates the relationship between:

• Communication service and an OAuth resource

• Resource and resource owner

• Scope and the resource

The communication service-to-resource mapping is explained in detail in "Managing OAuth Resources".The scope (defined in the OAuth 2.0 specification) consists of one or more scope-tokens. Each scope-token contains a scopeId (which identifies the resource) and a list of parameter name-values pairs associated with this scopeId. The scope is submitted as part of the authorization grant request. The scopeId, submitted as part of the scope-token, is interpreted and enforced by the default Services Gatekeeper OAuth interceptor. By default the OAuth interceptor allows all resources to pass. You can also filter these resources to meet the needs of your implementation. If the OAuth interceptor does not meet your implementations's needs, you can replace it with a custom interceptor. For details on modifying the OAuth interceptor or creating a custom interceptor see ”Using Service Interceptor to Manipulate Requests” in Services Gatekeeper Extension Developer's Guide.

See "OAuth Component to Services Gatekeeper Component Mapping" for more details on the scope.

Securing Resources with Multiple Owners

Some APIs require authorization from multiple resource owners. For example:

A Sales Manager may want to expose the location of his sales associates to a location tracking application. This use case requires using the getGroupLocation method in the Location API with multiple resource owner addresses.With Services Gatekeeper, you can create a group of resource owners and associate them with a group URI. You then create a group owner to issue an authorization grant on behalf of the group members. The group owner is represented by an address (Group URI), loginId and password much like a resource owner. The authorization grant issued by a group owner can be easily used with APIs that accept the URIs of group members as one of the request parameters.

The relationships between resources, resource owner(s), groups, group URI and group owner are illustrated in Figure 1-3:

Figure 1-3 show Tel: URIs, but you can also use SIP: URIs.

Use these general steps to protect an API that takes group URIs:

1. Create a group with a group URI using the Parlay X 3.0 AddressListManagement.

2. Add members to the group using the Parlay X 3.0 AddressListManagement.

3. Create a group owner related to this group URI and password for the group owner.

4. Communicate the group URI and password to a group owner (outside the scope of Services Gatekeeper).

5. The group owner issues an authorization grant to an application to use the member URI as part of API method that requires multiple URIs.

6. Subscribers access the resource (invoking an API method) that accepts multiple resource owners as method parameters.

The default Subscriber Manager supports a mechanism to provision the group owner represented by the group URI. Services Gatekeeper supports this requirement by using the Parlay X 3.0 AddressListManagement communication service to create groups. See the 3GPP specification for more information about address list management:.

http://www.3gpp.org/ftp/specs/archive/29_series/29.199-13/29199-13-702.zip

Support For SAML Assertions

In order to use SAML assertions, the application must have a trusted relationship with the identity provider, and be able to request end user authorization assertions. Services Gatekeeper is pre-configured to trust the identity provider with accounts and policies for the application.

Figure 1-4 shows how traffic flows Services Gatekeeper interacts with the identity provider (Oracle IDM) to support an SSO application. First the identity provider and Services Gatekeeper (as the authorization server) exchange metadata and the OAuth client registration information. Once that trusted relationship is set up, the service provider can request a SAML assertion from the identity provider. The service provider then presents the SAML assertion together with an application identifier to Services Gatekeeper as the authorization server. Services Gatekeeper then exchanges the end user authentication assertion and application identity for an access token. The access token can then be used as evidence of authentication when accessing 3rd party resources through Services Gatekeeper. You can also apply any policies associated with the API access.

See "Understanding the Services Gatekeeper Authorization Server" and "Configuring SAML (Optional)" for details on configuring SAML.

Support for Anonymous Customer References

In addition to basic and session ID authentication, Services Gatekeeper also supports OAuth authentication of applications requesting or querying Anonymous Customer References (ACR) identifiers. Services Gatekeeper can use OAuth to provide subscribers SSO-like access to resources such as photos or websites.

Services Gatekeeper supports allowing OAuth access to subscriber resources using ACRs. Requests can use a valid accessToken to retrieve or update ACR information when submitted. The Services Gatekeeper OAuth Interceptor uses the provided accessToken to confirm a subscriber's identity before releasing ACR information.

For more information adding anonymous customer references, see "Adding RESTful Anonymous Customer Reference Support" in Services Gatekeeper Application Developer's Guide.

Accessing the OAuth Log Messages

OAuth stores logged output messages in the Middleware_home/user_projects/domains/domain_name/oauth2_log/oauth2.log file.

Supported Communication Services

The OAuth security mechanism can be used with the REST-based communication services provided with Services Gatekeeper, and any custom REST-based API that you deploy.

See ”Part II Creating Applications Using the RESTful Interface” in Services Gatekeeper Application Developer's Guide for the list of REST-based communication services.

Supported OAuth Server Roles

By default, Services Gatekeeper supports the following OAuth server roles:

• Authorization Server: Issuing authorization grant and access tokens.

• Resource Server: Protecting resources and enforcing OAuth token-based access to resources.

Supported Authorization Grant Types

An authorization grant is a credential representing the resource owner's authorization (to access its protected resources) used by the client to obtain an access token.

By default, Services Gatekeeper supports the following grant types:

• Authorization Code Grant

• Implicit Grant

Extension Grant Flows Enabled Through Supported Grant Types

Services Gatekeeper facilitates customizing authorization flow by supporting the custom Endpoints described in "Understanding the OAuth Endpoints".

Instead of authenticating with the default Subscriber Manager, it is possible to define a custom authentication URL that authenticates and obtains user's consent and posts the authorization result back to Services Gatekeeper to issue the authorization code.

This delegated authentication is only supported with the authorization code grant type.

See "Implementing a Third-Party Authentication Service" for more information.

Supported Token Types

Services Gatekeeper supports the following token types defined in OAuth2 specification:

• bearer

• MAC

• saml-bearer

Supported Client Profiles

Services Gatekeeper supports Web-based, user-agent-based, and native application profiles.

OAuth Flows Supported by Services Gatekeeper

The following sections illustrate the OAuth authorization grant flows that Services Gatekeeper supports:

• Authorization Code Grant

• Implicit Grant

• Refresh Token Grant

Supported URIs (Subscribers)

Services Gatekeeper supports the following resource owner URIs for use with OAuth:

• tel: URI (as described in RFC 2806)

• sip: URI (as described in RFC3261)