2 Protecting Services Gatekeeper Resources with OAuth

Understanding the Services Gatekeeper Resource Server

As an OAuth Resource Server, Services Gatekeeper manages the protected resources contained within a service provider's network and accepts and responds to third-party application requests for access to protected resources.

In Services Gatekeeper, a resource is considered to be a communication service method. Resources can have subresources, each of which is represented by a method derived from the resource. Authorization grants to a resource also apply 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.

Understanding the Services Gatekeeper Authorization Server

As an OAuth Authorization Server, Services Gatekeeper obtains a subscriber's permission for access to protected resources when an application makes a request. Services Gatekeeper issues a token to the client application, which is used to access protected resources without requiring the resource owner to provide actual credentials.

When a client application requests access to a protected resource, the Services Gatekeeper REST handler initially checks the request, ensuring that the body contains the needed authorization information. If the request is valid, Services Gatekeeper forwards the request onto the proper communication service. An OAuth interceptor verifies that the token contained in the request is valid before completing the request. Services Gatekeeper then sends a response back to the client application.

Services Gatekeeper can also act as a SAML identity manager that accepts SAML token requests and grants the corresponding SAML tokens. You can use these tokens to supply permission to use resources protected by OAuth. You also have the ability to grant access to resources with federated identities such as single sign-ons (SSOs). You create the SSOs using an identity manager such as Oracle Fusion Middleware Identity and Access Management product (which contains Oracle Identity Manager), or another identity access management product. The SSO authorizations then allow the subscriber access to all resources protected by the SSO.

Understanding the Services Gatekeeper Authentication Server

As an Authentication Server, Services Gatekeeper maintains a subscriber database used to store the owners of protected resources. OAuth 2.0 resource owners in Services Gatekeeper must be setup as subscribers in the Authentication Server first. The Authentication Server is used to authenticate subscribers, as resource owners, before initiating authorization to protected resources.

The included Authentication Server is intended for OAuth 2.0 demonstration and development purposes.

Protecting RESTful Communication Services

To enable OAuth protection for RESTful communication services (including custom communication services), you map communication services to OAuth resources. You then use the OAuthResourceMBean to upload resource mapping to Services Gatekeeper.

For more information on the fields and methods of OAuthResourceMBean, see the "All Classes" section of Services Gatekeeper OAM Java API Reference.

Protecting Subscription Resources

Services Gatekeeper uses operations in the OAuthResourceMBean to protect subscription resources. See ”Services Gatekeeper OAuth 2.0 Authorization and Resource Servers” in Services Gatekeeper Communication Service Reference Guide.

Using the Default Subscriber Manager

Services Gatekeeper offers a built-in subscriber repository to authenticate subscribers. To use the default Subscriber Manager to authenticate subscribers, do the following:

1. Create the subscribers in Services Gatekeeper using the SubscriberMBean Mbean. Use the methods of this MBean to configure and maintain subscribers. Access the SubscriberMBean MBean through the OAM Console or the PTE Tools MBean browser.

   For more information on the fields and methods of SubscriberMBean, see the "All Classes" section of Services Gatekeeper OAM Java API Reference.

2. Verify that the AuthenticationURL property of OAuthCommonMbean is set to:

   https://app_server_IP:app_server_port/oauth2/auth.jsp

Using Delegated Authentication

Instead of provisioning users in the Services Gatekeeper database, you can delegate authentication to a custom authentication server.

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

See "Understanding the OAuth Resource Format" for details on the resource format.

Creating Individual Resource Owners

Create the individual resource owners using the methods of the OAuthResourceOwnerMBean MBean. For more information on the fields and methods of this MBean, see the "All Classes" section of Services Gatekeeper OAM Java API Reference.

Creating a Resource Rules File Using Regular Expressions

You map resource owners to their resources using regular expressions. To do so, you create an XML rules file that defines the resource owner/resource mapping and save this file.

See resource_rule.xsd for the schema definition.

The rules file that you create maps resource owner addresses, represented by a regular expression, to a list of one or more resources. The rules file is interpreted when OAuth grants the authorization, and rules must be defined in order of priority from most specific to most general.

In the following example, owner/resource mapping rules are defined with the most specific rules at the beginning of the file, proceeding to the most general rules at the end. Placing a more specific rule, with a regular expression such as ^1390.*$, at the start of the file ensures that the expected cases are caught and correctly interpreted first. Then the rules with more general regular expressions, such as ^.*$, toward the end of the file serves as a stop gaps to catch the unexpected or rarer cases.

<?xml version="1.0" encoding="UTF-8"?>
<tns:addressResourceRules
xmlns:tns="http://oracle/ocsg/oauth2/management/resource_rule"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<!-- numbers start with '1390' own the 'location' and 'payment' services  -->
<tns:rule addressPattern="^1390.*$" resources="location payment"/>
<!-- numbers start with '139' own the 'location' service  -->
<tns:rule addressPattern="^139.*$" resources="location"/>
<!-- All other resources are protected and no resource owners are defined. -->
<!-- Any request with a scope not defined in this xml file will be rejected. -->
<tns:rule addressPattern="^.*$" resources=""/>
</tns:addressResourceRules>

Uploading the Resource Rules to Services Gatekeeper

Upload the saved resource rules XML file to Services Gatekeeper using the loadResourceRuleXml method in OAuthResourceMBean MBean.

To retrieve the current rules XML file, you use the retrieveResourceRuleXml method.

For more information on the fields and methods of the OAuthResourceMBean MBean, see the "All Classes" section of Services Gatekeeper OAM Java API Reference.

Steps to Protecting the OneAPI Payment Service with OAuth

1. Adding a Client in Services Gatekeeper

2. Configuring the Authentication URL

3. Adding One API Payment Communication Service as an OAuth resource

4. Adding a New Subscriber

5. Assigning the Resource to the Subscriber to Act as Resource owner

Adding a Client in Services Gatekeeper

1. Open the MBean browser in PTE or use the OAM WebLogic interface to access the addClient operation in the OAuthClient MBean at:

   Wlng, OauthServer, OauthClientMBean, addClient()

2. Use the following parameters for the addclient operation:

   • Id: app123

   • Name: App123_name

   • Password: password

   • Description: Demo Application

   • AllowRedirectURI: https://localhost/app/redirect.php

   • AppInstanceId: domain_user

3. Submit the parameters to add the new client.

Configuring the Authentication URL

1. Open the MBean browser in PTE or use the OAM WebLogic interface to access the AuthenticationURL configuration setting in the OAuthCommon MBean at:

   Wlng, OauthServer, OauthCommonMBean, AuthenticationURL

2. Use the following parameter for the AuthenticationURL field:

   AuthenticationURL: https://app_tier_host:app_tier_port/oauth2/auth.jsp

3. Submit the parameter to set the authentication URL.

Adding One API Payment Communication Service as an OAuth resource

1. Open the MBean browser in PTE or use the OAM to access the loadResourceXml operation in the OAuthResourceMBean at:

   Wlng, OauthServer, OauthResourceMBean, loadResourceXml()

2. Use the following sample XML content for the FileContent parameter field:

   <?xml version="1.0" encoding="UTF-8"?>
   <resources xmlns="http://oracle/Services Gatekeeper/oauth2/management/xml"
    mlns:xsi="http://www.w3.org/2001/XMLSchema-instance">  
     <!--  OneAPI Payment  amountTransaction    -->
     <resource id="POST-/payment/acr:Authorization/transactions/amount"
    name="Charge or refund" interfaceName="oracle.Services
    Gatekeeper.parlayrest.plugin.PaymentPlugin" methodName="amountTransaction"
    tokenExpirePeriod="3600">
           <parameter name="code" description="billable item id"/>
     </resource> 
   </resources>
   

3. Submit the parameter to add the payment service as an OAuth resource.

Adding a New Subscriber

1. Open the MBean browser in PTE or use the OAM WebLogic interface to access the addSubscriber operation in the SubscriberMBean at:

   Wlng, SubscriberService, SubscriberMBean, addSubscriber()

2. Use the following parameters for the addSubscriber operation:

   • Address: tel:888

   • LoginID: Jack

   • Password: password

3. Submit the parameters to create a subscriber.

Assigning the Resource to the Subscriber to Act as Resource owner

1. Open the MBean browser in PTE or use the OAM WebLogic interface to access the addResourceOwner operation in the OAuthResourceOwnerMBean at:

   Wlng, OauthServer, OauthResourceOwnerMBean, addResourceOwner()

2. Use the following parameters for the addResourceOwner operation:

   • Address: tel:888

   • resourceScope: POST-/payment/acr:Authorization/transactions/amount

3. Submit the parameters to create a subscriber.