13.5. Configuring OpenAM as Authorization Server & Client

This section takes a high-level look at how to set up OpenAM both as an OAuth 2.0 authorization server and also as a client in order to protect resources by using a policy agent. The high-level steps are as follows.

  1. Set up a policy agent or OpenIG to protect your web resources, including the policy used to protect the resources.

    Make sure you can access the resources using an authentication module that you already know before working with OAuth 2.0.

  2. Configure OpenAM's OAuth 2.0 authorization service as described in Section 13.2, “Configuring the OAuth 2.0 Authorization Service”.

  3. Configure an OpenAM OAuth 2.0 authentication module instance using the Hints For the OAuth 2.0 Authentication Module with the OpenAM authorization service endpoints.

  4. Register the OAuth 2.0 authentication module as an OAuth 2.0 confidential client as described in Section 13.3, “Registering OAuth 2.0 Clients With the Authorization Service”.

  5. Logout and access the protected resources to see the process in action.

Example 13.1. Web Site Protected With OAuth 2.0

This example pulls everything together (except security considerations), using OpenAM as an OAuth 2.0 authorization server, OAuth 2.0 client, and "resource server" by protecting web resources with a policy agent.

This example uses two hosts, oauth2.example.com where OpenAM is deployed at http://oauth2.example.com:8080/openam, and www.example.com where the resources to protect are deployed in Apache Tomcat at http://www.example.com:8080/examples.

  1. Set up an OpenAM policy agent and policy in the top-level realm, /, to protect resources. So far this is standard OpenAM, unrelated to OAuth 2.0.

    See the OpenAM Web Policy Agent Installation Guide or OpenAM Java EE Policy Agent Installation Guide for instructions on installing a policy agent. This example relies on the Apache Tomcat Java EE policy agent, configured to protect resources in Apache Tomcat at http://www.example.com:8080/.

    The policies for this example protect the Apache Tomcat examples under http://www.example.com:8080/examples/, allowing GET and POST operations by all authenticated users. For more information on creating policies, see Configuring Policies.

    After setting up the policy agent and the policy, you can make sure everything is working by attempting to access a protected resource, in this case http://www.example.com:8080/examples/. The policy agent should redirect you to OpenAM to authenticate with the default authentication module, where you can login as user demo password changeit. After successful authentication, OpenAM redirects your browser back to the protected resource and the policy agent lets you get the protected resource, in this case the Tomcat examples top page.

    Successfully accessing the Apache Tomcat examples

    [D]

  2. Configure OpenAM's OAuth 2.0 authorization service as described in Section 13.2, “Configuring the OAuth 2.0 Authorization Service”.

    The authorization endpoint to protect in this example is at http://oauth2.example.com:8080/openam/oauth2/authorize.

  3. Configure an OpenAM OAuth 2.0 authentication module instance for the top-level realm.

    Under Access Control > / (Top-Level Realm) > Authentication > Module Instances, click New. Name the module OAuth2, and select the OAuth 2.0 type, then click OK to save your work.

    Then click Authentication > Module Instances > OAuth2 to open the OAuth 2.0 client configuration page. This page offers numerous options. The key settings for this example are the following.

    Client Id

    This is the client identifier used to register your client with OpenAM's authorization server, and then used when your client must authenticate to OpenAM.

    Set this to myClientID for this example.

    Client Secret

    This is the client password used to register your client with OpenAM's authorization server, and then used when your client must authenticate to OpenAM.

    Set this to password for this example. Make sure you use strong passwords when you actually deploy OAuth 2.0.

    Authentication Endpoint URL

    In this example, http://oauth2.example.com:8080/openam/oauth2/authorize.

    This OpenAM endpoint can take additional parameters. In particular you must specify the realm if the OpenAM OAuth 2.0 provider is configured for a subrealm rather than / (Top-Level Realm).

    For example, if the OAuth 2.0 provider is configured for the realm /customers, then use the following URL: https://openam.example.com:8443/openam/oauth2/authorize?realm=/customers

    The /oauth2/authorize endpoint can also take module and service parameters. Use either as described in Authenticating To OpenAM, where module specifies the authentication module instance to use or service specifies the authentication chain to use when authenticating the resource owner.

    Access Token Endpoint URL

    In this example, http://oauth2.example.com:8080/openam/oauth2/access_token.

    This OpenAM endpoint can take additional parameters. In particular you must specify the realm if the OpenAM OAuth 2.0 provider is configured for a subrealm rather than / (Top-Level Realm).

    For example, if the OAuth 2.0 provider is configured for the realm /customers, then use the following URL: https://openam.example.com:8443/openam/oauth2/access_token?realm=/customers

    User Profile Service URL

    In this example, http://oauth2.example.com:8080/openam/oauth2/tokeninfo.

    Scope

    In this example, cn.

    The demo user has common name demo by default, so by setting this to cn|Read your user name, OpenAM can get the value of the attribute without the need to create additional subjects, or to update existing subjects. The description, Read your user name, is shown to the resource owner in the consent page.

    OAuth2 Access Token Profile Service Parameter name

    Identifies the parameter that contains the access token value, which in this example is access_token.

    Proxy URL

    The client redirect URL, which in this example is http://oauth2.example.com:8080/openam/oauth2c/OAuthProxy.jsp.

    Attribute Mapper

    In this example, org.forgerock.openam.authentication.modules.oauth2.DefaultAccountMapper.

    Account Mapper Configuration

    In this example, cn=cn.

    Create account if it does not exist

    In this example, disable this functionality.

    OpenAM can create local accounts based on the account information returned by the authorization server. For this example, map all users to the anonymous account to keep it simple.

    Map to anonymous user

    In this example, enable this functionality.

  4. Register the OAuth 2.0 authentication module as an OAuth 2.0 confidential client as described in Section 13.3, “Registering OAuth 2.0 Clients With the Authorization Service”.

    Under Access Control > / (Top-Level Realm) > Agents > OAuth 2.0 Client > Agents > myClientID, adjust the following settings.

    Client type

    In this example, confidential. OpenAM protects its credentials as an OAuth 2.0 client.

    Redirection URIs

    In this example, http://oauth2.example.com:8080/openam/oauth2c/OAuthProxy.jsp.

    Scopes

    In this example, cn.

  5. Before you try it out, you must make the following additional change to the configuration.

    Your OpenAM OAuth 2.0 client authentication module is not part of the default chain, and therefore OpenAM does not call it unless you specifically request the OAuth 2.0 client authentication module.

    To cause the policy agent to request your OAuth 2.0 client authentication module explicitly, browse in OpenAM console to your policy agent profile configuration, in this case Access Control > / (Top-Level Realm) > Agents > J2EE > Agents > Tomcat > OpenAM Services > OpenAM Login URL, and add http://oauth2.example.com:8080/openam/UI/Login?module=OAuth2, moving it to the top of the list.

    Save your work.

    This ensures that the policy agent directs the resource owner to OpenAM with the instruction to authenticate using the OAuth2 authentication module.

  6. Try it out.

    First make sure you are logged out of OpenAM, for example by browsing to the logout URL, in this case http://oauth2.example.com:8080/openam/UI/Logout.

    Next attempt to access the protected resource, in this case http://www.example.com:8080/examples/.

    If everything is set up properly, the policy agent redirects your browser to the login page of OpenAM with module=OAuth2 among other query string parameters. After you authenticate, for example as user demo, password changeit, OpenAM presents you with an authorization decision page.

    OpenAM presenting authorization decision page to resource owner

    [D]

    When you click Allow, the authorization service creates an SSO session, and redirects the client back to the resource, thus allowing the client to access the protected resource. If you configured an attribute on which to store the saved consent decision, and you choose to save the consent decision for this authorization, then OpenAM can use that saved decision to avoid prompting you for authorization next time the client accesses the resource, but only ensure that you have authenticated and have a valid session.

    Successfully accessing the Apache Tomcat examples

    [D]