| Oracle® Communications Services Gatekeeper OAuth Guide Release 5.1 E37521-01 |
|
|
PDF · Mobi · ePub |
| Oracle® Communications Services Gatekeeper OAuth Guide Release 5.1 E37521-01 |
|
|
PDF · Mobi · ePub |
This chapter provides an overview of how Oracle Communications Services Gatekeeper (Services Gatekeeper) uses the Open Authorization Protocol (OAuth) to protect resources.
OAuth 2.0 is an open source Web authorization protocol developed by the Internet Engineering Task Force (IETF). For detailed specifications and more information see:
http://tools.ietf.org/html/rfc6749
The Services Gatekeeper OAuth implementation allows service providers to offer authorized third-party application access to protected resource owner resources over HTTP.
OAuth is an additional layer of security, in addition to the SLAs and policy control security features that Services Gatekeeper already offers. These security features all work together.
An application instanceId defined in Services Gatekeeper can be mapped to a client_id defined in the OAuth specification, seamlessly integrating regular SLA functionality. Because OAuth is enforced as a security mechanism, OAuth security is enforced before a Services Gatekeeper SLA.
For more information on supported communication services, see the Oracle Communications Services Gatekeeper RESTful Application Developer's Guide.
The OAuth2.0 security mechanism can only be enforced for REST-based APIs deployed on Services Gatekeeper. It is not possible to protect the SOAP APIs using OAuth. Services Gatekeeper protects the communication services listed in "Supported Communication Services" as well as any custom APIs that you deploy.
OAuth 2.0 security supports Transport Layer Security (TLS) if required by a client. See "OAuth Configuration" for the required configuration setting.
OAuth is an open standard for authorization. It allows users (your subscribers) to share their private resources with a third party without having to provide their own security credentials. These resources could be photos, videos, contact lists, location and billing capability, and so on, and are usually stored with another service provider. For example, photos stored on a dedicated photo Web storage site.
OAuth does this by granting requesting (client) applications a token, once access is approved by the resource owner. Each token grants access to a specific resource for a specific period. The requesting application uses the token for access to resources stored with another service provider, instead of the owner's credentials.
A resource can be:
A single file such as a photo or video.
Access to a Web site, such as the services of a video editing Web site.
Personal information such as their location or billing capability.
Table 1-1 lists OAuth terminology and definitions.
Table 1-1 OAuth Terminology and Definitions
| Term | Definition |
|---|---|
|
OAuth |
Open Authorization Protocol |
|
resource |
The Web resource protected by OAuth Protocol. |
|
resource owner |
An entity capable of granting access to a protected resource. In the operator context this is defined as Resource owner URI (tel: or sip:) |
|
Application Client |
An application making protected resource requests on behalf of the resource owner and with the resource owner's authorization. The term client does not imply any particular implementation characteristics (for example, whether the application executes on a server, a desktop, or other devices). |
|
scopeId |
Unique string that identifies a resource and used as part of scope-token by application client. |
|
Protocol Endpoint |
Network URI representing the location of a service to:
|
|
Client Identifier |
A unique string representing the registration information provided by the client. |
|
authorization grant |
Represents the authorization given by the resource owner to a client application. 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. |
|
Access Token |
Access tokens are credentials used to access protected resources. An access token is a string representing an authorization issued to the client. |
|
Refresh Token |
Refresh tokens are credentials used to re-obtain access tokens. |
|
Authorization Server |
Server that issues authorization codes and access token. |
|
Resource Server |
Server that hosts protected resources and validates access token during resource access. |
|
Authorization Endpoint |
Used to obtain authorization from the resource owner using user-agent redirection. |
|
grant endpoint |
URI supported by Services Gatekeeper to post the authentication result to issue the authorization code (defined by Services Gatekeeper). |
|
Redirection Endpoint |
After completing its interaction with the resource owner, the Authorization Server directs the resource owner's user-agent back to the client. The Authorization Server redirects the user-agent to the client's redirection endpoint previously established with the Authorization Server during the client registration process or when making the authorization request. |
|
Authentication Server |
Server that validates resource owner identity (defined by Services Gatekeeper). |
|
Delegated Authentication |
Authentication mode supported by Services Gatekeeper to integrate with 3rd party authentication systems. |
|
Subscriber Manager |
Component in Services Gatekeeper to validate subscribers provisioned in Services Gatekeeper database. |
|
Custom Subscriber Manager |
Component that authenticates resource owner's username and password with a custom identity store (such as LDAP). |
|
Group URI |
URI that represents a group of Resource Owners. |
|
Group Owner |
Owner of the Group URI. Issues authorization token on behalf of the group members. |
|
applicationInstanceID |
String that uniquely identifies the ApplicationInstance. One applicationInstanceId can be mapped with one OAuth2 Client Identifier, so that SLA can be proceed for OAuth2 based traffic. |
Figure 1-1 shows an example OAuth protocol flow for a resource access request:
The OAuth2.0 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).
This section explains how the Services Gatekeeper functionality is mapped to the OAuth specification.
OAuth defines the following terms that map to the Services Gatekeeper concepts listed:
resource: Defined by the OAuth2.0 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 expire period, parameters and subResource. resource uniquely identified by scopeId.
For more information, see "Resource Mapping".
scope request parameter: Defined by the OAuth2.0 specification. 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 2.0 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>=<value>[&<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:
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>
The chargeAmount resource is mapped to tel:1234 as the resourceOwner.
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 "Client Management" 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 will be handled by the Subscriber Manager. See "Resource Owner - Resource Mapping" for more information.
Service Gatekeeper supports the standard endpoints defined in the OAuth 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://OCSG_server_IP:port/oauth2/authorize
Token endpoint: By default, the token endpoint is configured to the following URL:
https://OCSG_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://OCSG_server_IP:port/oauth2/auth.jsp
This URL can be updated by editing the following MBean property:
OauthService.OauthCommonMBean.AuthenticationURL
Grant Endpoint: The Call back URI supported by Services Gatekeeper to process the successfully 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://OCSG_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"
You can use OAuth2.0 token based security to protect any RESTful communication service, including a customized communication service method, if 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 "Resource Management".The scope (defined in the OAuth 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 Oracle Communications Services Gatekeeper Platform Development Studio Developer's Guide.See "OAuth Component to Services Gatekeeper Component Mapping" for more details on the scope.
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:
Create a group with a group URI using the Parlay X 3.0 AddressListManagement.
Add members to the group using the Parlay X 3.0 AddressListManagement.
Create a group owner related to this group URI and password for the group owner.
Communicate the group URI and password to a group owner (outside the scope of Services Gatekeeper).
The group owner issues an authorization grant to an application to use the member URI as part of API method that requires multiple URIs.
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 this specification for more information about address list management: http://www.3gpp.org/ftp/specs/archive/29_series/29.199-13/29199-13-702.zip.
This section describes Services Gatekeeper compliance with the OAuth 2.0 specification.
The OAuth2.0 security mechanism can be used with the REST-based communication services provided with Services Gatekeeper, and any custom REST-based API that you deploy. These REST-based communication services are provided by default:
OneAPI (REST)
Anonmyous Customer References (ACRs)
SMS
MMS
Location
Payment
For more information on supported communication services, see the Oracle Communications Service Gatekeeper RESTful Application Developer's Guide.
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.
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
Services Gatekeeper facilitates customization of the 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.
Services Gatekeeper supports the following token types defined in OAuth2 specification:
Bearer
MAC
Services Gatekeeper supports Web-based, user-agent-based, and native application profiles.
The following sections illustrate the OAuth authorization grant flows that Services Gatekeeper supports:
Figure 1-4 shows an OAuth authorization code grant sequence flow diagram.
Figure 1-5 shows an Oauth implicit grant sequence flow diagram.
Figure 1-6 shows a refresh token grant flow diagram. If the client has way of recognizing when the access token expires (smart client), it skips steps E and F in this diagram. Clients without this knowledge (dumb clients) execute steps E and F.
|
 Copyright © 2012, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
