Tivoli Federated Identity Manager OAuth Demonstrations

This article guides you through how to try out a new capability of the Tivoli Federated Identity Manager self service demonstration site. I have introduced the demonstration site in a previous article. In particular the site now demonstrates OAuth 2.0 service provider capabilities that are new in TFIM 6.2.2. The site includes a couple of demonstration clients, and you can also write you own client to work with this site. I have also provided a simple AJAX client that works with the OAuth 2.0 implicit grant flow on this very page which has been pre-registered with the demonstration site.

Where to Start

To get started make sure you have read the introduction article to the demonstration site and have self-registered using an OpenID or your Facebook account. From here I’ll assume you’ve already done that.

Next, go the the Manage your Attributes page on the demonstration site and add an attribute called email and another called phone with any value you like. Both email and phone will be used as requested scopes in the OAuth flow. If you don’t have values for them in your attribute list on the demonstration site then that’s ok, they just won’t be available in the protected resource response.

To try out the AJAX client included on this page, you must be using a browser which supports Cross Origin Resource Sharing (CORS) or otherwise permits cross-domain requests.

I have found current versions of Firefox and Chrome work with default settings.

For Internet Explorer, CORS is disabled by default for sites in the Internet Zone. To enable it:

• Go to Tools -> Internet Options -> Security
• Click on Custom Level
• Find Miscellaneous -> Access data sources across domains
• Select “Enable” or “Prompt”, then OK

Provided you are using a CORS-capable browser, start the OAuth flow by clicking on the Redirect for Authorization link below. After you have authenticated to the demonstration site and granted access you will be returned to this page with the access token in a URL fragment. The access token will also appear in the Access Token entry field below. You can then press Get Resource to retrieve the protected resource. Note that you can continue to press Get Resource to re-retrieve the JSON profile until the access token expires. If you were to open another browser and go to the Manage your attributes page and modify an attribute value, then return to this browser and press Get Resource you will immediately see the changed attribute value in the protected resource JSON data.

Demonstration AJAX OAuth Client Using Implicit Grant Flow

OAuth Clients on the Demonstration Site

The demonstration site itself also has a number of built-in OAuth clients showing different types of OAuth flows. The OAuth Services page has links and instructions for each of these demonstration clients as well as the ability for you to self-register your own OAuth client application. The page also contains comprehensive information for OAuth-aware developers on everything you need to know to write your own OAuth client to interact with the demonstration site OAuth service provider.

Take some time to explore each of these clients and watch how they work. Ultimately they will all retrieve the same protected resource however the way in which each obtains an access token is unique to that specific OAuth flow.

Driving an OAuth flow manually

In this section I will demonstrate how you can drive the most common OAuth flow (authorization code flow) manually with a browser and using curl.

First use the Manage OAuth Client Registrations page to add an OAuth client but in this case leave the Redirect URI blank as shown here:

After saving that client write down the client id and secret, then use a browser to simulate the client “redirecting for authorization” to the authorize endpoint:

https://tfim01.demos.ibm.com/FIM/sps/oauth20sp/oauth20/authorize?client_id=<your_client_id>
    &response_type=code&scope=phone email

You will then be prompted to authenticate and authorize the client, as shown:

After consent approval you are typically redirected back to the client with the authorization code in a query parameter however in this case our client has no registered Redirect URI so the authorization code will be display on the screen for manually transferring to the client:

In the demonstration environment authorization codes expire after 300 seconds so you have a little time to do this next step. We will now act as the client and use curl to exchange the authorization code for an access token and refresh token:

curl -d "client_id=<your_client_id>&client_secret=<your_client_secret>&grant_type=authorization_code
    &code=<your_authorization_code>" https://tfim01.demos.ibm.com/FIM/sps/oauth20sp/oauth20/token

{"expires_in":3599,"scope":"email phone","access_token":"lCn1oPFA6SJXKyWW7xpF",
    "token_type":"bearer","refresh_token":"JgDXOI5uSEVTUn9DbKhB4lv1XN9aZe2rxrTVmDZ8"}

You can see the response from the token endpoint contains an access_token (as well as a refresh token). You can now use this access token to request a protected resource – three different ways:

curl -H "Authorization: Bearer <your_access_token>" https://tfim01.demos.ibm.com/FIM/demo/oauthprotected/profile.jsp

curl -d "access_token=<your_access_token>" https://tfim01.demos.ibm.com/FIM/demo/oauthprotected/profile.jsp

curl https://tfim01.demos.ibm.com/FIM/demo/oauthprotected/profile.jsp?access_token=<your_access_token>

In each case you should get back the protected resource, similar to:

{"timestamp":1323944023721,"username":"sweeden@au1.ibm.com","email":["sweeden@au1.ibm.com"],"phone":["12345"]}

Conclusion

This article has given you some insight into the OAuth capabilities on the TFIM demonstration site, and hopefully you have the information necessary to write and test your own OAuth clients against this site. While the protected resource currently on offer is very trivial (simply the ability to get a user’s attributes with the attribute names representing OAuth scopes), you can imagine this could be used for protected resource which are actually REST API’s that perform operations at the service provider (e.g. Twitter’s ability to have a third party application post a tweet on behalf of a user). Should you have any questions or feedback on TFIM’s OAuth capabilities or would like to arrange a real time demonstration, please feel free to contact me.