About the Sample App

OpenAM services make it easy to add access management to modern mobile applications.

OpenAM OAuth 2.0 iOS Sample App demonstrates use of OpenAM server's standard OAuth 2.0 REST API to authorize OAuth 2.0 client access.

For more information on OpenAM's support for OAuth 2.0, read the Administration Guide chapter on Managing OAuth 2.0 Authorization.

For more information on OpenAM's support for mobile applications, read the Administration Guide chapter on Working with Mobile Devices & Applications.

To Prepare OpenAM Server

Before you try the sample application, install and configure OpenAM server as described in the OpenAM Installation Guide, and then prepare OpenAM for use with the sample application.

Important For the initial version of the sample, the cookie domain must be .forgerock.com, the OpenAM administrator amadmin must have password cangetin, and the SSO Token cookie must have the default name, iPlanetDirectoryPro.

Tip Add an alias to the localhost address such as oauth2.forgerock.com in your /etc/hosts file to fake the fully-qualified domain name before configuring OpenAM.

After initial installation and configuration of OpenAM, follow these steps to prepare OpenAM for use with the sample application.

  1. In OpenAM Console > Common Tasks, click Configure OAuth2, and then click Create in the Configure OAuth2 page to configure an OAuth 2.0 Authorization Server for the realm /.

  2. In OpenAM Console > Access Control > / (Top Level Realm) > Agents > OAuth 2.0 Client, click New, and then use the New OAuth 2.0 Client page to register an OAuth 2.0 client with name MyApp and password password.

    After you register the client, click the link to the client profile to set the Redirection URI to http://www.example.com/ and the Scopes to cn and mail, and then click Save.

To Build the Sample App on Mac OS X

You can build the sample on OS X 10.8 or later with Xcode installed.

  1. In Terminal, check out the sample application source code.

    $ svn co https://svn.forgerock.org/commons/samples/mobile/ios

    This subversion command checks out iOS sample application code into an ios folder in the current working directory. It also checks out the REST SDK framework code that you need in order to build the sample application.

  2. Build the REST SDK framework that the sample application depends on.

    $ cd ios/openam-ios-rest-sdk/trunk/
    $ rake

    When you build with rake on the command line, the framework is copied to your Frameworks folder, ~/Library/Frameworks/openam-ios-rest-sdk.framework.

  3. Build the sample project in Xcode.

    You can open the project either from Finder, or from the command line.

    $ cd ../../openam-ios-oauth2-sample-app/trunk/
    $ open openam-ios-oauth2-sample-app.xcodeproj
  4. Click the play button in Xcode to build and then run the current scheme. After the sample builds, Xcode launches the sample in the simulator.

If you have successfully arrived at this point, then OpenAM can function as an OAuth 2.0 Authorization Server, and the client application is registered as MyApp. The client application is also running in an iOS device simulator, waiting to be configured.

To Try the Sample App

After the sample builds in Xcode, Xcode launches the application in an iOS device simulator, and you can try it with OpenAM.

  1. The initial screen in the simulator lets you configure the client.

    initial-screen

    • Set the Base URI to the URL to your OpenAM server, such as http://oauth2.forgerock.com:8080/openam.
    • Edit the OAuth2 client settings to correspond to the OAuth 2.0 client profile that you configured in OpenAM.
  2. After you finish setting the client configuration, click the Authorize link to have the client direct you as amadmin to OpenAM to authorize an access token for the client application.

    before-authorization

  3. Click allow to authorize access on the OAuth authorization page.

    authorizing-access

  4. On success, you see the OAuth 2.0 access token information and also the scope values for amadmin in the client.

    token-and-scopes

To Change Sample App Settings

You can change the client settings after you leave the initial screen. Follow these steps.

  1. Type Command + Shift + H to open the simulator home page where you can access the device settings.

    access-settings

  2. Click Settings, and then navigate down the page to select the settings for the sample application.

    selecting-settings

  3. On the settings screen, edit the settings as necessary.

    settings-screen

  4. When finished, return to the application by returning to the device home page and paging through the available applications to find the sample application.