<?xml version="1.0" encoding="UTF-8"?>

<chapter xml:id='chap-oauth2'

xmlns='http://docbook.org/ns/docbook'

version='5.0' xml:lang='en'

xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

xsi:schemaLocation='http://docbook.org/ns/docbook

xmlns:xinclude='http://www.w3.org/2001/XInclude'

xmlns:xlink='http://www.w3.org/1999/xlink'>

<title>Managing OAuth 2.0 Authorization</title>

<indexterm>

<primary>Authorization</primary>

<secondary>Configuring</secondary>

</indexterm>

<indexterm>

<primary>OAuth 2.0</primary>

</indexterm>

<para>This chapter covers OpenAM support for the OAuth 2.0 authorization

framework. The chapter begins by showing where OpenAM fits into the OAuth 2.0

authorization framework, and then shows how to configure the

functionality.</para>

<section xml:id="about-oauth2-support">

<title>About OAuth 2.0 Support in OpenAM</title>

<para>RFC 6749, <link xlink:href="http://tools.ietf.org/html/rfc6749"

xlink:show="new"><citetitle>The OAuth 2.0 Authorization Framework</citetitle></link>,

provides a standard way for <firstterm>resource owners</firstterm> to grant

<firstterm>client</firstterm> applications access to the owners' web-based

resources. The canonical example involves a user (resource owner) granting

access to a printing service (client) to print photos that the user has

stored on a photo-sharing server.</para>

<para>The section describes how OpenAM supports the OAuth 2.0 authorization

framework in terms of the roles that OpenAM plays.<footnote><para>Read

<link xlink:show="new" xlink:href="http://tools.ietf.org/html/rfc6749"

>RFC 6749</link> to understand the authorization framework itself.</para>

</footnote> The following sequence diagram indicates the primary roles

OpenAM can play in the OAuth 2.0 protocol flow.</para>

<mediaobject xml:id="figure-oauth2-flow">

<alt>OpenAM in OAuth 2.0 protocol flow</alt>

<imageobject>

<imagedata fileref="images/oauth2-flow.png" format="PNG"/>

</imageobject>

<textobject><para>OpenAM can function as the authorization server and also

as the client.</para></textobject>

</mediaobject>

<section xml:id="openam-oauth2-authz-server">

<title>OpenAM as OAuth 2.0 Authorization Server</title>

<para>OpenAM can function as an OAuth 2.0 <firstterm>authorization

server</firstterm>. In this role, OpenAM authenticates resource owners and

obtains their authorization in order to return access tokens to

clients.</para>

<para>

When using OpenAM as authorization server,

you can register clients in OpenAM Console alongside policy agent profiles

under the OAuth 2.0 Client tab.

OpenAM supports both confidential and public clients.

</para>

<para>OpenAM supports the four main grants for obtaining authorization

described in RFC 6749: the authorization code grant, the implicit grant,

the resource owner password credentials grant, and the client credentials

grant. See RFC 6749 for details on the authorization grant process, and

for details on how clients should make authorization requests and handle

authorization responses. OpenAM also supports the <link xlink:show="new"

xlink:href="http://tools.ietf.org/html/draft-ietf-oauth-saml2-bearer"

><citetitle>SAML 2.0 Bearer Assertion Profiles for OAuth 2.0</citetitle></link>,

described in the Internet-Draft.</para>

<section xml:id="oauth2-authz">

<title>OAuth 2.0 Authorization Grant</title>

<para>The authorization code grant starts with the client, such as a

web-based service, redirecting the resource owner's user-agent to the OpenAM

authorization service. After authenticating the resource owner and

obtaining the resource owner's authorization, OpenAM redirects the resource

owner's user-agent back to the client with an authorization code that the

client uses to request the access token. The following sequence diagram

outlines a successful process from initial client redirection through to the

client accessing the protected resource.</para>

<mediaobject xml:id="figure-oauth2-authz">

<alt>OpenAM in OAuth 2.0 Authorization Code Grant process</alt>

<imageobject>

<imagedata fileref="images/oauth2-authz.png" format="PNG"/>

</imageobject>

<textobject><para>OpenAM supports the authorization code

grant.</para></textobject>

</mediaobject>

</section>

<section xml:id="oauth2-implicit">

<title>OAuth 2.0 Implicit Grant</title>

<para>The implicit grant is designed for clients implemented to run inside

the resource-owner user agent. Instead of providing an authorization code

that the client must use to retrieve an access token, OpenAM returns the

access token directly in the fragment portion of the redirect URI. The

following sequence diagram outlines the successful process.</para>

<mediaobject xml:id="figure-oauth2-implicit">

<alt>OpenAM in OAuth 2.0 Implicit Grant process</alt>

<imageobject>

<imagedata fileref="images/oauth2-implicit.png" format="PNG"/>

</imageobject>

<textobject><para>OpenAM supports the implicit grant.</para></textobject>

</mediaobject>

</section>

<section xml:id="oauth2-ropc">

<title>OAuth 2.0 Resource Owner Password Credentials Grant</title>

<para>The resource owner password credentials grant lets the client use the

resource owner's user name and password to get an access token directly.

Although this grant might seem to conflict with an original OAuth goal of

not having to share resource owner credentials with the client, it can

makes sense in a secure context where other authorization grant types are

not available, such as a client that is part of a device operating system

using the resource owner credentials once and thereafter using refresh tokens

to continue accessing resources. The following sequence diagram shows the

successful process.</para>

<mediaobject xml:id="figure-oauth2-ropc">

<alt>OpenAM in OAuth 2.0 Resource Owner Password Credentials Grant process</alt>

<imageobject>

<imagedata fileref="images/oauth2-ropc.png" format="PNG"/>

</imageobject>

<textobject><para>OpenAM supports the resource owner password credentials

grant.</para></textobject>

</mediaobject>

</section>

<section xml:id="oauth2-client-cred">

<title>OAuth 2.0 Client Credentials Grant</title>

<para>The client credentials grant uses client credentials as an

authorization grant. This grant makes sense when the client is also the

resource owner, for example. The following sequence diagram shows the

successful process.</para>

<mediaobject xml:id="figure-oauth2-client-cred">

<alt>OpenAM in OAuth 2.0 Client Credentials Grant process</alt>

<imageobject>

<imagedata fileref="images/oauth2-client-cred.png" format="PNG"/>

</imageobject>

<textobject><para>OpenAM supports the client credentials

grant.</para></textobject>

</mediaobject>

</section>

<section xml:id="oauth2-saml2-bearer">

<title>SAML 2.0 Bearer Assertion Profiles</title>

<indexterm>

<primary>Federation</primary>

<secondary>OAuth 2.0</secondary>

</indexterm>

<para>The Internet-Draft, <link xlink:show="new"

xlink:href="http://tools.ietf.org/html/draft-ietf-oauth-saml2-bearer"

><citetitle>SAML 2.0 Bearer Assertion Profiles for OAuth 2.0</citetitle></link>,

describes a means to use SAML 2.0 assertions to request access tokens and

to authenticate OAuth 2.0 clients.</para>

<para>At present OpenAM implements the profile to request access

tokens.</para><!-- Pending AME-710 -->

<para>In both profiles, the issuer must sign the assertion. The client

communicates the assertion over a channel protected with transport

layer security, by performing an HTTP POST to the OpenAM's access token

endpoint. OpenAM as OAuth 2.0 authorization server uses the issuer ID to

validate the signature on the assertion.</para>

<para>In the profile to request an access token, the OAuth 2.0 client

bears a SAML 2.0 assertion that was issued to the resource owner on

successful authentication. A valid assertion in this case is equivalent

to an authorization grant by the resource owner to the client. OAuth 2.0

clients must make it clear to the resource owner that by authenticating to

the identity provider who issues the assertion, they are granting the client

permission to access the protected resources.</para>

<mediaobject xml:id="figure-oauth2-saml2-bearer">

<alt>SAML 2.0 Bearer Assertion Authorization Grant</alt>

<imageobject>

<imagedata fileref="images/oauth2-saml2-bearer.png" format="PNG"/>

</imageobject>

<textobject><para>OpenAM supports SAML 2.0 Bearer Assertion Profiles, for

example to use an assertion to request an access token.</para></textobject>

</mediaobject>

<para>The HTTP POST to OpenAM to request an access token looks something

like this:</para>

<programlisting language="http">POST /openam/oauth2/access_token HTTP/1.1

Host: openam.example.com

Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer&amp;

assertion=PHNhbWxwOl...[base64url encoded assertion]...ZT4&amp;

client_id=[ID registered with OpenAM]</programlisting>

<!-- Pending AME-710

<para>If OpenAM is already a SAML 2.0 service provider, you can configure

OpenAM as OAuth 2.0 authorization server as well, and set an adapter class

name in the service provider configuration that lets OpenAM POST the

assertion from the service provider to the authorization server. See

<xref linkend="oauth2-sp-and-authz" /> for details.</para>

</section>

<section xml:id="oauth2-endpoints">

<title>OpenAM OAuth 2.0 Endpoints</title>

<xinclude:include href="/shared/variablelist-oauth2-endpoints.xml" />

<para>

For examples, see the <citetitle>Developer's Guide</citetitle> section,

<link xlink:href="dev-guide#rest-api-oauth2" xlink:show="new"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>OAuth 2.0

Authorization</citetitle></link>.

This section of the <citetitle>Developer's Guide</citetitle> also covers

OAuth 2.0 token administration and client administration endpoints

that are specific to OpenAM.

</para>

</section>

</section>

<section xml:id="openam-oauth2-client">

<title>OpenAM as OAuth 2.0 Client &amp; Resource Server Solution</title>

<para>OpenAM can function as an OAuth 2.0 client for installations where the

web resources are protected by OpenAM. To configure OpenAM as an OAuth 2.0

client, you set up an OpenAM OAuth 2.0 authentication module instance, and

then integrate the authentication module into your authentication chains as

necessary.</para>

<para>When OpenAM functions as an OAuth 2.0 client, OpenAM provides an

OpenAM SSO session after successfully authenticating the resource owner and

obtaining authorization. This means the client can then access resources

protected by policy agents. In this respect the OpenAM OAuth 2.0 client is

just like any other authentication module, one that relies on an OAuth 2.0

authorization server to authenticate the resource owner and obtain

authorization. The following sequence diagram shows how the client gains

access to protected resources in the scenario where OpenAM functions as both

authorization server and client for example.</para>

<mediaobject xml:id="figure-oauth2-openam-client">

<alt>OpenAM as OAuth 2.0 client and authorization server</alt>

<imageobject>

<imagedata fileref="images/oauth2-openam-client.png" format="PNG"/>

</imageobject>

<textobject><para>OpenAM as client works as an authentication module where

authentication and authorization is handled by the authorization server,

and on success an SSO session is created, so that OpenAM access management

can happen as it normally does.</para></textobject>

</mediaobject>

<para>As the OAuth 2.0 client functionality is implemented as an OpenAM

authentication module, you do not need to deploy your own resource server

implementation when using OpenAM as an OAuth 2.0 client. Instead, use policy

agents or OpenIG to protect resources.</para>

<para>To configure OpenAM as an OAuth 2.0 client, see <link

xlink:href="admin-guide#oauth2-module-conf-hints"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Hints For the

OAuth 2.0 Authentication Module</citetitle></link>.</para>

</section>

<section xml:id="oauth2-byo-client">

<title>Using Your Own Client &amp; Resource Server</title>

<para>OpenAM returns bearer tokens as described in RFC 6750, <link

xlink:show="new" xlink:href="http://tools.ietf.org/html/rfc6750"

><citetitle>The OAuth 2.0 Authorization Framework: Bearer Token

Usage</citetitle></link>. Notice in the following example JSON response to

an access token request that OpenAM returns a refresh token with the access

token. The client can use the refresh token to get a new access token as

described in RFC 6749.</para>

<programlisting language="javascript">{

"expires_in": 599,

"token_type": "Bearer",

"refresh_token": "f6dcf133-f00b-4943-a8d4-ee939fc1bf29",

"access_token": "f9063e26-3a29-41ec-86de-1d0d68aa85e9"

}</programlisting>

<para>In addition to implementing your client, the resource server must also

implement the logic for handling access tokens. The resource server can use

the <literal>/oauth2/tokeninfo</literal> endpoint to determine whether the

access token is still valid, and to retrieve the scopes associated with the

access token.</para>

<para>The default OpenAM implementation of OAuth 2.0 scopes assumes that the

space-separated (%20 when URL encoded) list of scopes in an access token

request correspond to names of attributes in the resource owner's

profile.</para>

<para>To take a concrete example, consider an access token request where

<literal>scope=mail%20cn</literal> and where the resource owner is the

default OpenAM demo user. (The demo user has no email address by default, but

you can add one, such as <literal>demo@example.com</literal> to the demo

user's profile.) When the resource server performs an HTTP GET on the token

information endpoint, <literal>/oauth2/tokeninfo?access_token=<replaceable

>token-id</replaceable></literal>, OpenAM populates the

<literal>mail</literal> and <literal>cn</literal> scopes with the email

address (<literal>demo@example.com</literal>) and common name

(<literal>demo</literal>) from the demo user's profile. The result is

something like the following token information response.</para>

<programlisting language="javascript">{

"mail": "demo@example.com",

"scope": [

"mail",

"cn"

],

"cn": "demo",

"realm": "/",

"token_type": "Bearer",

"expires_in": 577,

"access_token": "f9063e26-3a29-41ec-86de-1d0d68aa85e9"

}</programlisting>

<para>OpenAM is designed to allow you to plug in your own scopes

implementation if the default implementation does not do what your

deployment requires. See <link xlink:href="dev-guide#chap-oauth2-scopes"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Customizing

OAuth 2.0 Scope Handling</citetitle></link> for an example.</para>

</section>

</section>

<section xml:id="configure-oauth2-authz">

<title>Configuring the OAuth 2.0 Authorization Service</title>

<para>You configure the OAuth 2.0 authorization service for a particular

realm, starting from the Common Tasks page of the OpenAM console. This

process also protects the authorization endpoint using a standard

policy.</para>

<procedure xml:id="common-task-oauth2-authz">

<title>To Set Up the OAuth 2.0 Authorization Service</title>

<para>Follow these steps.</para>

<step>

<para>In the OpenAM console, select Common Tasks &gt; Configure

OAuth2.</para>

</step>

<step>

<para>On the Configure OAuth2 page, enter the Realm for the authorization

service.</para>

</step>

<step performance="optional">

<para>If necessary, adjust the lifetimes for authorization codes

(10 minutes is the recommended setting in RFC 6749), access tokens, and

refresh tokens.</para>

</step>

<step performance="optional">

<para>Select Issue Refresh Tokens unless you do not want the authorization

service to supply a refresh token when returning an access token.</para>

</step>

<step performance="optional">

<para>Select Issue Refresh Tokens on Refreshing Access Tokens if you want

the authorization service to supply a refresh token when refreshing an

access token.</para>

</step>

<step performance="optional">

<para>If you want to use the default scope implementation, whereby

scopes are taken to be resource owner profile attribute names, then

keep the default setting.</para>

<para>If you have a custom scope implementation, put it on the OpenAM

classpath, and provide the class name as Scope Implementation Class.</para>

</step>

<step>

<para>Click Create to complete the process.</para>

<para>

To access the authorization server configuration in OpenAM Console,

browse to Access Control > <replaceable>Realm Name</replaceable> > Services,

and then click OAuth2 Provider.

</para>

<para>In addition to setting up an OAuth 2.0 authorization server for the

realm, OpenAM sets up a policy to protect the authorization endpoint.

The policy appears in the list of policies for the realm. Its name is

<literal>OAuth2ProviderPolicy</literal>.</para>

</step>

<step performance="optional">

<para>If your provider has plugins for custom response types, add the

custom response types and the corresponding plugin class names to the

list of Response Type Plugins.</para>

</step>

<step performance="optional">

<para>

If you use an external identity repository where

resource owners log in not with their user ID,

but instead with their mail address or some other profile attribute,

then complete this step.

</para>

<para>

The following steps describe how to configure OpenAM authentication

so OAuth 2.0 resource owners can log in using their email address,

stored on the LDAP profile attribute, <literal>mail</literal>.

Adapt the names if you use a different LDAP profile attribute,

such as <literal>cn</literal>.

</para>

<substeps>

<step>

<para>

When configuring the data store for the LDAP identity repository,

make sure that you select Load schema when saved,

and that you set the Authentication Naming Attribute

to <literal>mail</literal>.

You can find the data store configuration under

Access Control > <replaceable>Realm Name</replaceable> > Data Stores.

</para>

</step>

<step>

<para>

Add the <literal>mail</literal> profile attribute name to the list

of attributes that can be used for authentication.

</para>

<para>

To make the change, browse to Access Control &gt; <replaceable>Realm

Name</replaceable> &gt; Services &gt; OAuth2 Provider, add the profile

attributes to the list titled User Profile Attribute(s)

the Resource Owner is Authenticated On, and then click Save.

</para>

</step>

<step>

<para>

Create an LDAP authentication module to use with the external directory.

</para>

<substeps>

<step>

<para>

In OpenAM Console under Access Control > <replaceable>Realm

Name</replaceable> > Authentication > Module Instances,

create a module to access the LDAP identity repository,

such as <literal>LDAPAuthUsingMail</literal>.

</para>

</step>

<step>

<para>

In the Attribute Used to Retrieve User Profile field,

set the attribute to <literal>mail</literal>.

</para>

</step>

<step>

<para>

In the Attributes Used to Search for a User to be Authenticated list,

remove the default <literal>uid</literal> attribute

and add the <literal>mail</literal> attribute.

</para>

</step>

<step>

<para>

Click Save.

</para>

</step>

</substeps>

</step>

<step>

<para>

Create an authentication chain to include the module

such as <literal>authUsingMail</literal>.

</para>

<substeps>

<step>

<para>

When creating the authentication chain,

choose the <literal>LDAPAuthUsingMail</literal> module

in the Instance drop-down list,

and set the criteria to REQUIRED.

</para>

</step>

<step>

<para>

Click Save.

</para>

</step>

</substeps>

</step>

<step>

<para>

Set Organization Authentication Configuration to use the new chain,

<literal>authUsingMail</literal>, and then click Save.

</para>

<para>

At this point OAuth 2.0 resource owners can authenticate

using their email address rather than their user ID.

</para>

</step>

</substeps>

<!--

</step>

<step>

<para>

Set a multi-valued, string syntax profile attribute

where OpenAM can store a resource owner's decisions to authorize clients

without further interaction

in the Saved Consent Attribute Name field.

</para>

<para>

You are not likely to find a standard profile attribute for this.

For evaluation purposes only,

you might try an unused existing profile attribute

such as <literal>description</literal>.

</para>

<para>

When moving to production, however, use

a dedicated, multi-valued, string syntax profile attribute

that clearly is not used for other purposes. For example,

you might call the attribute <literal>oAuth2SavedConsent</literal>.

</para>

<para>

Adding a profile attribute involves

updating the identity repository to support use of the attribute,

updating the AMUser Service for the attribute,

and optionally allowing users to edit the attribute.

The process is described in the <citetitle>Developer's Guide</citetitle>

chapter, <link xlink:show="new" xlink:href="dev-guide#chap-custom-attr"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle

>Customizing Profile Attributes</citetitle></link>,

which demonstrates adding a custom attribute

when using OpenDJ directory services to store user profiles.

</para>

</step>

<step>

<para>Save your changes.</para>

</step>

</procedure>

<para>You can further adjust the authorization server configuration after you

create it in the OpenAM console under Access Control &gt; <replaceable>Realm

Name</replaceable> &gt; Services &gt; OAuth2 Provider.</para>

<para>You can adjust global defaults in the OpenAM console under Configuration

&gt; Global &gt; OAuth2 Provider.</para>

</section>

<section xml:id="register-oauth2-client">

<title>Registering OAuth 2.0 Clients With the Authorization Service</title>

<para>You register an OAuth 2.0 client with the OpenAM OAuth 2.0 authorization

service by creating and configuring an OAuth 2.0 Client agent profile.</para>

<para>At minimum you must have the client identifier and client password

in order to register your OAuth 2.0 client.</para>

<procedure xml:id="create-oauth2-client-profile">

<title>To Create an OAuth 2.0 Client Agent Profile</title>

<step>

<para>Use either of these two facilities.</para>

<stepalternatives>

<step>

<para>In the OpenAM console, access the client registration endpoint

at <literal>/oauth2/registerClient.jsp</literal>.</para>

<para>The full URL depends on where you deployed OpenAM. For example,

<literal>https://openam.example.com:8443/openam/oauth2/registerClient.jsp</literal>.</para>

<para>The Register a Client page lets you quickly create and configure

an OAuth 2.0 client in a simple web page without inline help.</para>

</step>

<step>

<para>In the OpenAM console under Access Control &gt; <replaceable>Realm

Name</replaceable> &gt; Agents &gt; OAuth 2.0 Client &gt; Agent, click

New, then provide the client identifier and client password, and

finally click Create to create the profile.</para>

<para>This page requires that you perform additional configuration

separately.</para>

</step>

</stepalternatives>

</step>

</procedure>

<procedure xml:id="configure-oauth2-client-profile">

<title>To Configure an OAuth 2.0 Client Agent Profile</title>

<para>After initially registering or creating a client agent profile as

necessary.</para>

<step>

<para>In the OpenAM console, browse to Access Control &gt;

<replaceable>Realm Name</replaceable> &gt; Agents &gt; OAuth 2.0 Client

&gt; Agent &gt; <replaceable>Client Name</replaceable> to open the Edit

<replaceable>Client Name</replaceable> page.</para>

</step>

<step>

<para>Adjust the configuration as needed using the inline help for hints,

and also the documentation section <link xlink:show="new"

xlink:href="admin-guide#configure-oauth2-client"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring

OAuth 2.0 &amp; OpenID Connect 1.0 Clients</citetitle></link>.</para>

<para>Examine the client type option. An important decision to make at this

point is whether your client is a confidential client or a public client.

This depends on whether your client can keep its credentials confidential,

or whether its credentials can be exposed to the resource owner or other parties.

If your client is a web-based application running on a server, such as the OpenAM

OAuth 2.0 client, then you can keep its credentials confidential. If your client is

a user-agent based client, such as a JavaScript client running in a browser,

or a native application installed on a device used by the resource owner,

then yours is a public client.</para>

</step>

<step>

<para>When finished, Save your work.</para>

</step>

</procedure>

</section>

<section xml:id="oauth2-manage-tokens">

<title>Managing OAuth 2.0 Tokens</title>

<para>OpenAM exposes a RESTful API that lets administrators read, list, and

delete OAuth 2.0 tokens. OAuth 2.0 clients can also manage their own tokens.

See the <citetitle>Developer's Guide</citetitle> section on the <link

xlink:href="dev-guide#rest-api-oauth2-token-admin-endpoint"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>OAuth 2.0 Token

Administration Endpoint</citetitle></link> for details.</para>

<!--

</section>

<section xml:id="oauth2-client-plus-authz">

<title>Configuring OpenAM as Authorization Server &amp; Client</title>

<para>

This section takes a high-level look at how to set up OpenAM

both as an OAuth 2.0 authorization server and also as an OAuth 2.0 client

in order to protect resources on a resource server

by using an OpenAM policy agent.

</para>

<mediaobject xml:id="figure-oauth2-end-to-end-example">

<alt>OpenAM authorization server, OpenAM client, resource server</alt>

<imageobject>

<imagedata fileref="images/oauth2-end-to-end-example.png" format="PNG" />

</imageobject>

<textobject>

<para>

This example uses three servers,

an OAuth 2.0 authorization server configured in an OpenAM server,

an OAuth 2.0 client configured in another OpenAM server,

and an OAuth 2.0 resource server which is protected with a policy agent.

</para>

</textobject>

</mediaobject>

<para>

The example in this section uses three servers,

<literal>http://authz.example.com:8080/openam</literal> as the

OAuth 2.0 authorization server,

<literal>http://client.example.com:8080/openam</literal> as the

OAuth 2.0 client, which also handles policy,

<literal>http://www.example.com:8080/</literal> as the

OAuth 2.0 resource server protected with an OpenAM policy agent

where the resources to protect are deployed in Apache Tomcat.

The two OpenAM servers communicate using OAuth 2.0.

The policy agent on the resource server communicates with OpenAM

as policy agents normally do, using OpenAM specific requests.

The resource server in this example does not need to support OAuth 2.0.

</para>

<para>

The high-level configuration steps are as follows.

</para>

<orderedlist>

<listitem>

<para>

On the OpenAM server that you will configure to act as an OAuth 2.0 client,

configure a policy agent profile,

and the policy used to protect the resources.</para>

<para>

On the web server or application container

that will act as an OAuth 2.0 resource server,

install and configure the OpenAM policy agent.

</para>

<para>

Make sure that you can access the resources when you log in

through an authentication module that you know to be working,

such as the default DataStore authentication module.

</para>

<para>

In this example, you would try to access

<literal>http://www.example.com:8080/examples/</literal>.

The policy agent should redirect you to the OpenAM login page.

After you log in successfully as a user with access rights to the resource,

OpenAM should redirect you back to

<literal>http://www.example.com:8080/examples/</literal>,

and the policy agent should allow access.

</para>

<para>

Fix any problems you have in accessing the resources

before you try to set up access through the OAuth 2.0 authentication module.

</para>

</listitem>

<listitem>

<para>

Configure one OpenAM server as an OAuth 2.0 authorization service,

which is described in <xref linkend="configure-oauth2-authz" />.

</para>

</listitem>

<listitem>

<para>

Configure the other OpenAM server with the policy agent profile and policy

as an OAuth 2.0 client, by setting up an OAuth 2.0 authentication module

according to the <link xlink:show="new"

xlink:href="admin-guide#oauth2-module-conf-hints"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Hints For the

OAuth 2.0 Authentication Module</citetitle></link>.

</para>

</listitem>

<listitem>

<para>

On the authorization server, register the OAuth 2.0 authentication module

as an OAuth 2.0 client, which is described in

<xref linkend="register-oauth2-client" />.

</para>

</listitem>

<listitem>

<para>

Log out and access the protected resources to see the process in action.

</para>

</listitem>

</orderedlist>

<example xml:id="protect-web-site-with-oauth2"><?dbfo keep-together="auto"?>

<title>Web Site Protected With OAuth 2.0</title>

<para>

This example pulls everything together (except security considerations),

using OpenAM servers both as the OAuth 2.0 authorization server,

and also as the OAuth 2.0 client,

with an OpenAM policy agent on the resource server

requesting policy decisions from OpenAM as OAuth 2.0 client.

In this way any server protected by a policy agent

that is connected to an OpenAM OAuth 2.0 client

can act as an OAuth 2.0 resource server.

</para>

<orderedlist>

<listitem>

<para>

On the OpenAM server that will be configured as an OAuth 2.0 client,

set up an OpenAM policy agent and policy in the top-level realm,

<literal>/</literal>, to protect resources.

</para>

<para>See the <link xlink:href="web-install-guide#web-install-guide"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>OpenAM Web Policy

Agent <?eval ${agentsDocTargetVersion}?> Installation Guide</citetitle></link>

or <link xlink:href="jee-install-guide#jee-install-guide"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>OpenAM Java EE Policy

Agent <?eval ${agentsDocTargetVersion}?> Installation Guide</citetitle></link>

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 <literal>http://www.example.com:8080/</literal>.</para>

<para>The policies for this example protect the Apache Tomcat examples

under <literal>http://www.example.com:8080/examples/</literal>, allowing

GET and POST operations by all authenticated users. For more information

on creating policies, see <link xlink:show="new"

xlink:href="admin-guide#configure-authz-policy"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring

Policies</citetitle></link>.</para>

<para>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 <literal>http://www.example.com:8080/examples/</literal>. The policy

agent should redirect you to OpenAM to authenticate with the default

authentication module, where you can login as user <literal>demo</literal>

password <literal>changeit</literal>. 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.</para>

<mediaobject xml:id="figure-oauth2-examples">

<alt>Successfully accessing the Apache Tomcat examples</alt>

<imageobject>

<imagedata fileref="images/oauth2-examples.png" format="PNG"/>

</imageobject>

<textobject><para>If your policy agent and policy are set up correctly,

you should get HTTP 200 and the Apache Tomcat examples page.</para></textobject>

</mediaobject>

</listitem>

<listitem>

<para>

On the OpenAM server to be configured as an OAuth 2.0 authorization server,

configure OpenAM's OAuth 2.0 authorization service

as described in <xref linkend="configure-oauth2-authz" />.

</para>

<para>The authorization endpoint to protect in this example is at

<literal>http://authz.example.com:8080/openam/oauth2/authorize</literal>.</para>

</listitem>

<listitem>

<para>

On the OpenAM server to be configured as an OAuth 2.0 client,

configure an OpenAM OAuth 2.0 authentication module instance

for the top-level realm.

</para>

<para>Under Access Control &gt; / (Top-Level Realm) &gt; Authentication

&gt; Module Instances, click New. Name the module

<literal>OAuth2</literal>, and select the OAuth 2.0 type, then click

OK to save your work.</para>

<para>Then click Authentication &gt; Module Instances &gt; OAuth2 to open

the OAuth 2.0 client configuration page. This page offers numerous options.

The key settings for this example are the following.</para>

<variablelist>

<varlistentry>

<term>Client Id</term>

<listitem>

<para>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.</para>

<para>Set this to <literal>myClientID</literal> for this example.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Client Secret</term>

<listitem>

<para>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.</para>

<para>Set this to <literal>password</literal> for this example. Make

sure you use strong passwords when you actually deploy OAuth 2.0.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Authentication Endpoint URL</term>

<listitem>

<para>In this example,

<literal>http://authz.example.com:8080/openam/oauth2/authorize</literal>.</para>

<para>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).</para>

<para>For example, if the OAuth 2.0 provider is configured for the

realm <literal>/customers</literal>, then use the following URL:

<literal>http://authz.example.com:8080/openam/oauth2/authorize?realm=/customers</literal></para>

<para>The <literal>/oauth2/authorize</literal> endpoint can also take

<literal>module</literal> and <literal>service</literal> parameters. Use

either as described in <link xlink:href="admin-guide#authn-from-browser"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle

>Authenticating To OpenAM</citetitle></link>, where

<literal>module</literal> specifies the authentication module instance

to use or <literal>service</literal> specifies the authentication chain

to use when authenticating the resource owner.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Access Token Endpoint URL</term>

<listitem>

<para>In this example,

<literal>http://authz.example.com:8080/openam/oauth2/access_token</literal>.</para>

<para>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).</para>

<para>For example, if the OAuth 2.0 provider is configured for the

realm <literal>/customers</literal>, then use the following URL:

<literal>http://authz.example.com:8080/openam/oauth2/access_token?realm=/customers</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>User Profile Service URL</term>

<listitem>

<para>In this example,

<literal>http://authz.example.com:8080/openam/oauth2/tokeninfo</literal>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Scope</term>

<listitem>

<para>In this example, <literal>cn</literal>.</para>

<para>The demo user has common name <literal>demo</literal> by default,

so by setting this to <literal>cn|Read your user name</literal>, OpenAM

can get the value of the attribute without the need to create

additional subjects, or to update existing subjects. The description,

<literal>Read your user name</literal>, is shown to the resource owner

in the consent page.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>OAuth2 Access Token Profile Service Parameter name</term>

<listitem>

<para>Identifies the parameter that contains the access token value, which

in this example is <literal>access_token</literal>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Proxy URL</term>

<listitem>

<para>The client redirect URL, which in this example is

<literal>http://client.example.com:8080/openam/oauth2c/OAuthProxy.jsp</literal>.</para>

</listitem></varlistentry>

<varlistentry>

<term>Account Mapper</term>

<listitem>

<para>In this example,

<literal>org.forgerock.openam.authentication.modules.oauth2.DefaultAccountMapper</literal>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Account Mapper Configuration</term>

<listitem>

<para>In this example, <literal>cn=cn</literal>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Attribute Mapper</term>

<listitem>

<para>In this example,

<literal>org.forgerock.openam.authentication.modules.oauth2.DefaultAttributeMapper</literal>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Attribute Mapper Configuration</term>

<listitem>

<para>In this example, <literal>cn=cn</literal>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Create account if it does not exist</term>

<listitem>

<para>In this example, disable this functionality.</para>

<para>OpenAM can create local accounts based on the account information

returned by the authorization server.</para>

</listitem>

</varlistentry>

</variablelist>

</listitem>

<listitem>

<para>

On the OpenAM server configured to act as an OAuth 2.0 authorization server,

register the OAuth 2.0 authentication module

as an OAuth 2.0 confidential client,

which is described in <xref linkend="register-oauth2-client" />.

</para>

<para>Under Access Control &gt; / (Top-Level Realm) &gt; Agents &gt;

OAuth 2.0 Client &gt; Agents &gt; <literal>myClientID</literal>, adjust

the following settings.</para>

<variablelist>

<varlistentry>

<term>Client type</term>

<listitem>

<para>In this example, <literal>confidential</literal>. OpenAM protects

its credentials as an OAuth 2.0 client.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Redirection URIs</term>

<listitem>

<para>In this example,

<literal>http://client.example.com:8080/openam/oauth2c/OAuthProxy.jsp</literal>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Scopes</term>

<listitem>

<para>In this example, <literal>cn</literal>.</para>

</listitem>

</varlistentry>

</variablelist>

</listitem>

<listitem>

<para>

Before you try it out,

on the OpenAM server configured to act as an OAuth 2.0 client,

you must make the following additional change to the configuration.

</para>

<para>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.</para>

<para>To cause the policy agent to request your OAuth 2.0 client

authentication module explicitly, browse in OpenAM console to your

<emphasis>policy agent profile configuration</emphasis>, in this case

Access Control &gt; / (Top-Level Realm) &gt; Agents &gt; J2EE &gt;

Agents > <replaceable>Agent Name</replaceable> > OpenAM Services > OpenAM

Login URL, and add

<literal>http://client.example.com:8080/openam/UI/Login?module=OAuth2</literal>,

moving it to the top of the list.</para>

<para>Save your work.</para>

<para>This ensures that the policy agent directs the resource owner

to OpenAM with the instruction to authenticate using the

<literal>OAuth2</literal> authentication module.</para>

</listitem>

<listitem>

<para>Try it out.</para>

<para>First make sure you are logged out of OpenAM, for example by

browsing to the logout URL, in this case

<literal>http://client.example.com:8080/openam/UI/Logout</literal>.</para>

<para>Next attempt to access the protected resource, in this case

<literal>http://www.example.com:8080/examples/</literal>.</para>

<para>If everything is set up properly, the policy agent redirects your

browser to the login page of OpenAM with <literal>module=OAuth2</literal>

among other query string parameters. After you authenticate, for example

as user <literal>demo</literal>, password <literal>changeit</literal>,

OpenAM presents you with an authorization decision page.</para>

<mediaobject xml:id="figure-oauth2-authz-page">

<alt>OpenAM presenting authorization decision page to resource owner</alt>

<imageobject>

<imagedata fileref="images/oauth2-authz-page.png" format="PNG"/>

</imageobject>

<textobject><para>Upon successful authentication, the resource owner must

make a decision to authorize the client to access the protected

resource.</para></textobject>

</mediaobject>

<para>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.</para>

<mediaobject xml:id="figure-oauth2-examples-again">

<alt>Successfully accessing the Apache Tomcat examples</alt>

<imageobject>

<imagedata fileref="images/oauth2-examples.png" format="PNG"/>

</imageobject>

<textobject><para>If everything is set up correctly, you should end up

with HTTP 200 and the Apache Tomcat examples page.</para></textobject>

</mediaobject>

</listitem>

</orderedlist>

</example>

</section>

<section xml:id="oauth2-sp-and-authz">

<title>Configuring OpenAM as Both SAML 2.0 Service Provider &amp; OAuth 2.0

Authorization Server</title>

<para>As described in <xref linkend="oauth2-saml2-bearer" />, OpenAM as

OAuth 2.0 authorization server can handle the profile where a SAML 2.0

assertion borne by the client functions as an authorization grant to get

an access token. This lets a client get an access token when a resource owner

completes SAML 2.0 Web Single Sign-On.</para>

<para>You can configure OpenAM as both SAML 2.0 service provider and OAuth

2.0 authorization server, using an built-in adapter class to POST assertions

returned to the service provider to the access token endpoint of the

authorization server. This allows clients to send a resource owner to the

identity provider for SAML 2.0 web SSO, get an assertion at the service

provider, and retrieve an access token from the authorization server. In other

words, once this scenario is configured, the client must only direct the

resource owner to start web SSO as described in <link

xlink:href="admin-guide#using-saml2-sso-slo"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Using SAML 2.0

Single Sign-On &amp; Single Logout</citetitle></link>, and then retrieve the

access token on success or handle the error condition on failure.</para>

<procedure xml:id="configure-oauth2-sp-and-authz">

<title>To Get an Access Token From SAML 2.0 Web SSO</title>

<itemizedlist>

<para>For this scenario to work, the following conditions must be met.</para>

<listitem>

<para>The client must make the resource owner understand that by

authenticating to the SAML 2.0 identity provider the resource owner grants

the client access to the protected resources. OpenAM does not present the

resource owner with an authorization decision.</para>

</listitem>

<listitem>

<para>The SAML 2.0 identity provider issuing the assertion must sign the

assertion, and must correctly handle the name ID for the subject.</para>

</listitem>

<listitem>

<para>OpenAM as relying party must request that assertions are signed, must

verify the signatures on assertions, must correctly handle name IDs

from the issuer, and must use the built-in

<literal>org.forgerock.openam.oauth2.saml2.core.OAuth2Saml2GrantSPAdapter</literal>

adapter class in the service provider configuration to POST assertions

to the OAuth 2.0 authorization service.</para>

</listitem>

<listitem>

<para>The OAuth 2.0 authorization service and SAML 2.0 service provider

must be configured together on the same OpenAM server.</para>

</listitem>

<listitem>

<para>An OAuth 2.0 client configuration on OpenAM with the same name as

the service provider entity ID must be set up on OpenAM.</para>

</listitem>

<listitem>

<para>The OAuth 2.0 client initiating the process must be able to consume

the access token and to handle errors if necessary.</para>

</listitem>

</itemizedlist>

<para>Follow these steps. The test configuration hints in this procedure let

you prepare configuration to test with the demo user created in OpenAM by

default.</para>

<step>

<para>Make sure the SAML 2.0 identity provider signs assertions and that

name IDs are correctly configured to map resource owner accounts.</para>

<para>When configuring OpenAM as a hosted identity provider follow these

steps.</para>

<substeps>

<step>

<para>Make sure the Signing Key is properly configured on setup.</para>

<para>For a test configuration, select the <literal>test</literal>

certificate shown in the Common Tasks &gt; Create Hosted Service Provider

wizard.</para>

</step>

<step>

<para>Make sure name IDs are properly configured.</para>

<para>For a test configuration, in the OpenAM console under Federation

&gt; Entity Providers &gt; <replaceable>IDP name</replaceable> &gt;

NameID Value Map, add

<literal>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified=cn</literal>

and then Save your work.</para>

</step>

</substeps>

<para>For more detail on configuring OpenAM as a SAML 2.0 identity provider,

see <link xlink:href="admin-guide#configure-idp"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring

Identity Providers</citetitle></link>.</para>

</step>

<step>

<para>Configure OpenAM as service provider.</para>

<substeps>

<step>

<para>Set up a hosted service provider in OpenAM console under

Common Tasks &gt; Create Hosted Service Provider, keeping track of

the name, such as <literal>https://www.sp.example:8443/openam</literal>,

and selecting Use default attribute mapping from Identity Provider.</para>

<para>For details on configuring OpenAM as a SAML 2.0 service provider,

see <link xlink:href="admin-guide#configure-sp"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring

Service Providers</citetitle></link>.</para>

</step>

<step>

<para>Under Federation &gt; Entity Providers &gt; <replaceable>SP

name</replaceable> &gt; Assertion Content &gt; Request/Response Signing,

check Assertions Signed.</para>

</step>

<step>

<para>For a test configuration, in Federation &gt; Entity Providers &gt;

<replaceable>SP name</replaceable> &gt; Assertion Content &gt; NameID

Format List, remove all but

<literal>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</literal>,

and then Save your work.</para>

</step>

<step>

<para>In Federation &gt; Entity Providers &gt; <replaceable>SP

name</replaceable> &gt; Assertion Processing &gt; Adapter, add

<literal>org.forgerock.openam.oauth2.saml2.core.OAuth2Saml2GrantSPAdapter</literal>,

and then Save your work.</para>

<para>This is the adapter class that POSTs the SAML 2.0 assertion to

the OAuth 2.0 access token endpoint.</para>

</step>

<step>

<para>Use the wizard under Common Tasks &gt; Register Remote Identity

Provider to import the identity provider metadata.</para>

</step>

</substeps>

</step>

<step>

<para>Make sure the identity provider imports the metadata for your

service provider.</para>

<para>If your service provider is at

<literal>https://www.sp.example:8443/openam</literal>, then the metadata

can be accessed at

<literal>https://www.sp.example:8443/openam/saml2/jsp/exportmetadata.jsp</literal>.</para>

</step>

<step>

<para>On the service provider OpenAM server, set up the OAuth 2.0

authorization server as described in

<xref linkend="configure-oauth2-authz" />.</para>

<para>For a test configuration, set the realm to <literal>/</literal>, and

accept the defaults.</para>

</step>

<step>

<para>On the service provider and authorization server OpenAM server, set

up an OAuth 2.0 client profile with the same name as the service

provider under Access Control &gt; <replaceable>realm</replaceable> &gt;

Agents &gt; OAuth 2.0 Client &gt; New...</para>

<para>For example, if the service provider name is

<literal>https://www.sp.example:8443/openam</literal>, then that is also

the name of the OAuth 2.0 client profile.</para>

<para>You can make additional changes to the client profile if necessary.

See <xref linkend="register-oauth2-client" /> for details.</para>

</step>

<step>

<para>Test your configuration.</para>

<substeps>

<step>

<para>Logout of all OpenAM servers.</para>

</step>

<step>

<para>Initiate SAML 2.0 Web SSO.</para>

<para>For example, if your identity provider is at

<literal>https://www.idp.example:8443/openam</literal> with meta alias

<literal>/idp</literal> and your service provider is at

<literal>https://www.sp.example:8443/openam</literal>, then browse to the

following URL (without line breaks or spaces).</para>

<programlisting language="none"

>http://www.idp.example:8443/openam/saml2/jsp/idpSSOInit.jsp

?metaAlias=/idp&amp;spEntityID=http://www.sp.example:8443/openam</programlisting>

<para>For other configurations, see <link

xlink:href="admin-guide#using-saml2-sso-slo"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Using SAML 2.0

Single Sign-On &amp; Single Logout</citetitle></link>.</para>

</step>

<step>

<para>Login to the identity provider.</para>

<para>For OpenAM, login with user name <literal>demo</literal> and

password <literal>changeit</literal>.</para>

</step>

<step>

<para>Login to the service provider.</para>

<para>For OpenAM, login with user name <literal>demo</literal> and

password <literal>changeit</literal>.</para>

</step>

<step>

<para>See the resulting access token on successful login.</para>

<para>The result looks something like this, all on one line.</para>

<programlisting language="javascript">{

"expires_in": 59,

"token_type": "Bearer",

"access_token": "f0f731e0-6013-47e3-9c07-da598157a85f"

}</programlisting>

</step>

</substeps>

</step>

</procedure>

</section>

<section xml:id="oauth2-security-considerations">

<title>Security Considerations</title>

<para>OAuth 2.0 messages involve credentials and access tokens that allow

the bearer to retrieve protected resources. Therefore, do not let an attacker

capture requests or responses. Protect the messages going across the

network.</para>

<para>RFC 6749 includes a number of <link xlink:show="new"

xlink:href="http://tools.ietf.org/html/rfc6749#section-10">Security

Considerations</link>, and also requires Transport Layer Security (TLS)

to protect sensitive messages. Make sure you read the section covering

<citetitle>Security Considerations</citetitle>, and that you can implement

them in your deployment.</para>

<para>Also, especially when deploying a mix of other clients and resource

servers, take into account the points covered in the Internet-Draft, <link

xlink:href="http://tools.ietf.org/html/draft-ietf-oauth-v2-threatmodel"

xlink:show="new"><citetitle>OAuth 2.0 Threat Model and Security

Considerations</citetitle></link>, before putting your service into

production.</para>

</section>

</chapter>