GRC REST API Basics: Authenticating
Brian Laskey 270003US2W Visits (8623)
From my last blog post, on how to create new objects with the OpenPages GRC REST API, I did not mention one major detail. How to provide authentication when making REST API requests?
The default out of the box authentication mechanism uses the HTTP Basic standard. The Basic authorization scheme is defined by IETF's RFC 2617, and is implemented by the client sending an HTTP request header named "Authorization". Basic authorization contains the text "Basic" followed by the username and password separated by colon ‘:’ and the entire username and password string is encoded in Base 64.
Depending on the client technology, there is likely already a mechanism provided to send Basic authorization headers with the HTTP Request. For instance in the FireFox RESTClient add-on, from the Authentication menu, choosing Basic authentication prompts you to enter the username and password, which for OpenPages REST API will be the username and password for an existing User in OpenPages.
For example a Username "Aladdin" and a Password of "open sesame"
Resulting in this header being set
As Basic authorization is part of the HTTP standard. Most web browsers will natively understand the this authentication scheme and prompt the user if you navigate to a URL of an application using Basic authorization even if you do not provide the header explicitly.
Client side code
For other programmatic clients for the REST API, will also pass the Authorization header, and may be simplified through the client technology or library that you choose to use. For example with the Apac
ClientConfig config = new ClientConfig(); //for Basic authentication Basi
HTTP Status codes returned by the REST server are important for informing the client code of whether the request with provided authorization was accepted or not.
The standard response for a successful request will have
If you supply an invalid username or password that does not authenticate against the OpenPages database of users you will receive an error code
In the Wink client you can check the status codes through the ClientResponse class returned from the get() call to the Resource.
Server Side Configuration in WebSphere
In order to use the OpenPages GRC Platform's REST API it first must be configured properly in the application server's security configuration. The REST API was architected to leverage the Application Server's existing security infrastructure for the purposes of authenticating requests. For IBM WebSphere installations this requires following these post-installation steps in the WebSphere administrators console from the section of the OpenPages Installation Guide for WebSphere: Conf
Performing these steps is required for enabling Basic authentication to work for the REST API and must be done in order to leverage the REST API in your environment.
One of the benefits for leveraging the application server security is that we can rely on their tried and tested implementation as well as deep capability for extension and integration with other authentication schemes supported through the app server, for instance with IBM WebSphere the ability to create custom LoginModules for different types of SSO implementation or support out of the box for others such as LTPA, SPNEGO. Note that some additional work may be required to also use authentication for the OpenPages UI application which in 7.0 will continue to use a form based login mechanism, as well as support for LDAP and SSO modules.
Further Reading and References
References for the REST API in the Open