OAuth 2 Access and Refresh Token Tool
We are pleased to announce the availability of an easy-to-use and helpful OAuth 2 Access and Refresh Token Tool in v2.3.0 of Examine. The main purpose of this tool is to address one of the biggest challenges of working with REST APIs that require OAuth access tokens, namely obtaining these access tokens from the Authorization servers. The OAuth 2 specification allows for 4 different mechanisms to get the Access Token from the Authorization Server so that the client/consumer can access the resource using this token.
The OAuth 2 Token Tool makes it easy to obtain Access Tokens from compliant OAuth 2 service providers (like Google, Twitter (for application-only auth), Salesforce etc).
This tool supports all 4 authorization grant types and in this article we’ll give an example of each grant method using a service provider who supports each one.
For Authorization Code Grant, Implicit Grant and Resource Owner Password Credentials Grant, we’ll take Salesforce as the provider and for the Client Credentials Grant, we’ll test out Twitter and show you how easy it is (code-less, point-and-click!) to obtain an Access and optionally a Refresh Token. We can also quickly verify that accessing a Resource endpoint using this Access Token works correctly.
For Salesforce, the first step is to login to your account (developer.force.com) and add a New Connected App under (App Setup -> Create -> Apps) that represents Examine.
Specify the Callback URL as https://localhost:8443/OAuthCallback (Note that, most service providers will require that the Authorization Code Grant callback URL be HTTPs based, Examine comes with a Jetty SSL connector enabled on port 8443 with a default keystore – see the product documentation on how to change this if needed).
Authorization Code Grant:
Once you have the Client Id and Client Secret values for your Remote app, you can specify it along with any optional scopes to use for authorization (space separate list).
Also specify the Authorization Server URL and the Token Server URL. The former is used to make the initial request to obtain the Authorization Code (which will sent to the callback URL as a query parameter as a browser redirect). Once these values are specified, click on Get Access Token. You will be directed to the authorization endpoint that will ask for your permission to allow Examine to obtain the code. Once you agree, the Authorization server will send a request to the above callback URL. Examine will then retrieve the Auth Code and then send a request to the Token Server URL you have specified to exchange the code for an Access Token (and optionally a Refresh Token; for Salesforce you must specify the scope as ‘refresh_token’ to get a Refresh Token as well).
If the Access Token request is successful, then the Token Details are shown immediately.
Examine uses an innovative approach to get this Access Token and make it available for you for testing purposes. Examine makes a HTML page available that can be used as the callback URL when registering the app in the service provider. The callback URL is:
(Note that the protocol, host and port can be different – unlike the Authorization Code approach, this URL does not have to be HTTPS based. But the path segment must be the same as mentioned above).
Also, since there is no separate request to obtain the Access Token, you only need to specify the Authorization Server URL.
Note however that this grant does not provide Refresh Tokens.
Resource Owner Password Credentials Grant:
Salesforce also supports this grant method, so we can easily use this to obtain an Access Token. Unlike the first two approaches, this is not a recommended approach as it involves sending the resource owner’s (your) username and password credentials to the Authorization server to exchange it for a Access Token!
But to test it out, just specify the Username and Password values (for Salesforce, your password is usually the password + security token value) and the Token Server URL value (e.g. https://login.salesforce.com/services/oauth2/token).
Client Credentials Grant:
This is arguably the easiest of the 4 authorization grant types and Twitter supports this for accessing some of its REST APIs (that don’t involve a user context such as the Search APIs). Just specify the Client ID, Client Secret and the Authorization URL and click on Get Access Token to get the access token.
Testing the Access Token:
Once you obtain the Access Token using any of the above 4 methods, the next step is to check if you are able to access any of the REST Resources using this token. The OAuth specification allows the client to send the Access Token to the resource endpoint using the Bearer Authentication method. Check out the Bearer Token specification for more information. Basically, you can send the token either in the Authorization HTTP Header, or as a URL query parameter or in the body of the request as a form-encoded value.
Note that there are specific requirements for each of the approaches, especially for the form-encoded approach. Most providers should however support the Authorization header method.
Just specify the HTTP method, the Resource Endpoint, the Content Type to use and if you are using POST/PUT/OPTIONS/PATCH, you can optionally specify the content to be sent as well (either fixed text or from a file).
On clicking OK, the response received by accessing the resource endpoint is displayed to you in HTML format.
You can read more about this tool on the product documentation page here.
We invite you to try out this new feature by downloading a trial version or purchasing a copy. We believe Examine has a really good price-to-value ratio and will serve your testing needs well. If you have any questions or comments, please don’t hesitate to get in touch with us! Thanks!