Tuesday, 23 July 2013

Oracle API Gateway : Authenticating with REST parameters

Oracle API Gateway 11gR2
Authenticating with REST parameters

This example will show you how to build an Oracle API Gateway 11gR2 policy that performs authentication using credentials that are passed as REST parameters. The example REST request that we will be using is:

In the above REST request the credentials we wish to authenticate are passed in the 'username' and 'password' parameters. Our policy will extract the credentials from the REST request and check them against an authentication store. It will then return the result of the authentication in a JSON message. For this example we will use the OAG Local Authentication store, however the same policy will work with an LDAP authentication store just by specifying the appropriate authentication store in the Attribute Authentication filter.

Here is how our policy will look once completed.

Before continuing with this example, make sure the OAG Node Manager and Gateway Instance have been started.
  • Start the OAG Policy Studio and click on the Admin Node Manager link to start editing policies.
  • On the next screen click on the Gateway or Group and then click Edit Active Configuration.
  • Navigate to the Policy Library and click on Add Policy.
  • Enter a name and description for the policy.

  • Click on the Attributes folder in the design palette on the right and drag an 'Extract REST Request Attributes' filter onto the policy editor canvas.

  • Right-click on the filter and select 'Set as Start'.

  • Next add a 'Copy/Modify Attributes' filter to set the OAG authentication attributes: 'authentication.subject.id' and 'authentication.subject.password'. The 'Copy/Modify Attributes' filter is in the Authentication folder of the design palette.

Click the 'Add' button to add the following mappings:

'http.querystring.username' to 'authentication.subject.id'

'http.querystring.password' to 'authentication.subject.password'

  • Next add an 'Attribute Authentication' filter to perform the authentication. The 'Attribute Authentication' filter is in the Authentication folder of the design palette.

  • Next add two 'SET Message' filters from the Conversion folder of the design palette. We must provide the correct JSON response message for a successful and unsuccessful authentication.

  • At this point we can also link the actions together into a Success / Failure Path by clicking on the Success / Failure Path tools and clicking on the filters in the order we want them applied.
  • We need to add a Relative Path to the policy to define when it will be triggered. This is the URL path that the service will be available on. Click on the Add Relative Path tool at the bottom of the policy editor and enter the relative path you wish this policy to apply.
  • Now we need to deploy the policy. Click on the Deploy icon at the top right of the Policy Studio window to deploy the policy. Once successfully deployed the service will be available at http://localhost:8080/RESTParamsAuth.
An example request to this service looks like this:

An example response from this service looks like this:
    "LoginResponse": {
        "result": "OK"
That's it! I hope this example provides a useful starting point for exploring authentication using the Oracle API Gateway.