Chapter 14. Managing OpenID Connect 1.0 Authorization

In its role as OpenID Provider, OpenAM lets OpenID Connect clients discover its capabilities, handles both dynamic and static registration of OpenID Connect clients, responds to client requests with authorization codes, access tokens, and user information according to the Basic and Implicit Client Profiles of OpenID Connect, and manages sessions.

This section describes how OpenAM fits into the OpenID Connect picture in terms of the roles that it plays in basic and implicit client profiles, provider discovery, client registration, and session management.

14.1.1. OpenID Connect Basic Client Profile

The OpenID Connect Basic Client Profile specifies how the client application interacts with the provider, in this case OpenAM, based on use of the OAuth 2.0 authorization grant. The following sequence diagram shows successful processing from the authorization request, through grant of the authorization code, access token, and ID token, and optional use of the access token to get information about the end user.

[D]

In addition to what OAuth 2.0 specifies, OpenID Connect uses an ID token so the client can validate claims about the end user. It also defines how to get user information such as profile, email, address, and phone details from the UserInfo endpoint with a valid access token.

14.1.2. OpenID Connect Implicit Client Profile

The OpenID Connect Implicit Client Profile specifies how the client application interacts with the provider, in this case OpenAM, based on use of the OAuth 2.0 implicit grant. The following sequence diagram shows successful processing from the authorization request, through grant of the access and ID tokens, and optional use of the access token to get information about the end user.

[D]

As for the Basic Client Profile, the Implicit Client Profile specifies an ID token so the client can validate claims about the end user. It also defines how to get user information such as profile, email, address, and phone details from the UserInfo endpoint with a valid access token.

You can configure OpenAM's OAuth 2.0 authorization service to double as an OpenID Connect 1.0 Provider. To do so, make sure that the Response Type Plugins list includes at least the default plugin classes.

See Configuring the OAuth 2.0 Authorization Service for detailed instructions on configuring the service.

In order to allow clients to discover the provider for an end user, OpenAM supports OpenID Connect Discovery 1.0. In addition to discovering the provider for an end user, the client can also request the OpenID Connect Provider configuration.

OpenAM as OpenID Connect Provider exposes two endpoints for discovery:

A client needs to be able to discover the provider for an end user. In this case you should consider redirecting requests to URIs at the server root, such as http://www.example.com/.well-known/webfinger and http://www.example.com/.well-known/openid-configuration, to these Well-Known URIs in OpenAM's space.

Discovery relies on WebFinger, a protocol to discover information about people and other entities using standard HTTP methods. WebFinger uses Well-Known URIs, which defines the path prefix /.well-known/ for the URLs defined by OpenID Connect Discovery.

Unless you deploy OpenAM in the root context of a container listening on port 80 on the primary host for your domain, clients need to find the right host:port/deployment-uri combination to locate the well-known endpoints. Therefore you must manage the redirection to OpenAM. If you are using WebFinger for something else than OpenID Connect Discovery, then you probably also need proxy logic to route the requests.

To retrieve the provider for an end user, the client needs the following.

Ignoring the question of redirection, you can test the endpoint for the demo user account (output lines folded to make them easier to read).

$ curl "https://openam.example.com:8443/openam/.well-known/webfinger
 ?resource=acct%3Ademo%40example.com
 &rel=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer"
{
  "subject": "acct:demo@example.com",
  "links": [
    {
      "rel": "http://openid.net/specs/connect/1.0/issuer",
      "href": "https://openam.example.com:8443/openam"
    }
  ]
}

This shows that the OpenID Connect Provider for the OpenAM demo user is indeed the OpenAM server.

The client can also discover the provider configuration. Ignoring the question of redirection, you can test this (output lines folded to make them easier to read).

{
    "response_types_supported": [
        "id_token|org.forgerock.restlet.ext.oauth2.flow.responseTypes.IDTokenResponseType",
        "token|org.forgerock.restlet.ext.oauth2.flow.responseTypes.TokenResponseType",
        "code|org.forgerock.restlet.ext.oauth2.flow.responseTypes.CodeResponseType"
    ],
    "registration_endpoint": "https://openam.example.com:8443/openam/oauth2/connect/register",
    "token_endpoint": "https://openam.example.com:8443/openam/oauth2/access_token",
    "end_session_endpoint": "https://openam.example.com:8443/openam/oauth2/connect/endSession",
    "version": "3.0",
    "userinfo_endpoint": "https://openam.example.com:8443/openam/oauth2/userinfo",
    "subject_types_supported": [
        "pairwise",
        "public"
    ],
    "issuer": "https://openam.example.com:8443/openam",
    "jwks_uri": "",
    "id_token_siging_alg_values_supported": [
        "HmacSHA256",
        "HmacSHA512",
        "HmacSHA384"
    ],
    "check_session_iframe": "https://openam.example.com:8443/openam/oauth2/connect/checkSession",
    "claims_supported": [
        "phone",
        "email",
        "address",
        "openid",
        "profile"
    ],
    "authorization_endpoint": "https://openam.example.com:8443/openam/oauth2/authorize"
}

OpenID Connect Clients can register with OpenAM both statically through OpenAM console for example, and also dynamically using OpenID Connect 1.0 Dynamic Registration.

OpenID Connect Session Management 1.0 allows the client to manage OpenID Connect sessions, making it possible to know when the end user should be logged out.

As described in the OpenID Connect Session Management 1.0 specification, OpenAM's OpenID Connect provider exposes both a "check_session_iframe" URL that allows the client to receive notifications when the end user's session state changes at the provider, and also an "end_session_endpoint" URL to which to redirect an end user for logout.

When registering your client that uses session management, you set the OAuth 2.0 client agent profile properties Post Logout Redirect URI and Client Session URI, described in Configuring OAuth 2.0 & OpenID Connect 1.0 Clients. The Post Logout Redirect URI is used to redirect the end user user-agent after logout. The Client Session URI is the client URI where OpenAM sends notifications when the end user's session state changes.

OpenID Connect Basic and Implicit Client Profiles define how clients interact with the provider to obtain end user authorization and profile information. Although you can run the simple example clients mentioned in this section without setting up Transport Layer Security, do not deploy clients in production without securing the transport.

Code for the client examples shown here is available online. Clone the example project to deploy it in the same web container as OpenAM. Edit the configuration at the outset of the .js files in the project, register a corresponding profile for the example client as described in Section 14.4, “Registering OpenID Connect Clients”, and browse the deployment URL to see the initial page.

[D]

Example 14.1. Basic Client Profile Example

OpenID Connect Basic Client Profile 1.0 is designed for web-based relying parties that use the OAuth 2.0 Authorization Code grant type. This grant type makes it possible for the client to get the access code by using the authorization code directly, without passing through the end user's browser. To protect its client secret (password), part of the client must run on the server.

In the example, the Basic Client Profile Start Page describes the prerequisite configuration, which must be part of the client profile stored in the OpenAM realm where you set up the OpenID Provider. In OpenAM console, check that the OAuth 2.0 agent profile matches the settings described.

[D]

Logout of OpenAM, and click the link at the bottom of the page to request authorization. The link sends an HTTP GET request asking for openid profile scopes to the OpenID Connect provider authorization URI.

If everything is configured correctly, OpenAM's OpenID Connect provider has you authenticate as an end user, such as the demo user with username demo and password changeit, and grant (Allow) the client access to your profile.

If you successfully authenticate and allow the example client access to your profile, OpenAM returns an authorization code to the example client. The example client then uses the authorization code to request an access token and an ID token. It shows the response to that request, and also decodes the ID token to show the content and to perform some validation. Finally it uses the access token to request information about the end user who authenticated, and displays the result.

[D]

Notice that in addition to the standard payload, the ID token indicates the end user's OpenAM realm, in this case "realm": "/".

Example 14.2. Implicit Client Profile Example

OpenID Connect Implicit Client Profile 1.0 is designed for relying parties that use the OAuth 2.0 Implicit grant type. This grant type is designed for clients implemented in a browser. Rather than protect a client secret, the client profile must register a protected redirect URI in advance with the OpenID Provider.

In the example, the Implicit Client Profile Start Page describes the prerequisite configuration, which must be part of the client profile stored in the OpenAM realm where you set up the OpenID Provider. In OpenAM console, check that the OAuth 2.0 agent profile matches the settings described. If you have already configured the agent profile for the Basic Client Profile then you still need to add the redirect URI for the Implicit Client Profile.

[D]

Logout of OpenAM, and click the link at the bottom of the page to request authorization. The link sends an HTTP GET request asking for id_token token response types and openid profile scopes to the OpenID Connect provider authorization URI.

If everything is configured correctly, OpenAM's OpenID Connect provider has you authenticate as an end user, such as the demo user with username demo and password changeit, and grant (Allow) the client access to your profile.

If you successfully authenticate and allow the example client access to your profile, OpenAM returns the access token and ID token directly in the fragment (after #) of the redirect URI. The client does not get an authorization code. The client shows the response to the request, and also decodes the ID token to show the content and to perform some validation (though it does not check the ID token signature). Finally the client uses the access token to request information about the end user who authenticated, and displays the result.

[D]

As for the Basic Client Profile, the ID Token indicates the end user's OpenAM realm in addition to the standard information.

As for other OAuth 2.0 applications, you must protect messages going across the network. OpenID Connect 1.0 requires Transport Layer Security (TLS). The chapter on Managing Certificates includes some discussion of protecting traffic in the container where OpenAM runs. Also see the documentation for your web application container.

Also take into account the points developed in the section on Security Considerations in the OpenID Connect Messages draft specification.