# OpenAM Administration Guide
Chapter 13. Managing OAuth 2.0 Authorization

Sidebar | Prev | Up | Next

## 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.

   [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.

   [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.

   [D]