Demonstrating OAuth 2.0 Implicit Grant in a Web App

salbertelli01 · March 27, 2019, 4:00am

Written by Marc Craig

Summary

Instructions for demonstrating an OAuth 2.0 implicit grant in a web app.

The OAuth 2.0 framework standard defines how a user can grant a client application authorization to access web-based assets without sharing the user’s credentials. An OAuth 2.0 client can be authorized in different ways, which the framework specification formalizes as authorization grants.

The OAuth 2.0 framework defines multiple authorization grants for different purposes. Web clients acting on behalf of a user without the user’s credentials use the authorization code or implicit grant. In most cases, the authorization code grant is preferred. However, the implicit grant is appropriate in some cases. For example, when the authorization server (AS) does not support cross-origin resource sharing (CORS) requests, public clients, which cannot protect their credentials, cannot use the authorization code grant.

ForgeRock provides a sample application that shows how to use the OAuth 2.0 implicit grant flow in a web app. The web app allows the user to manage their profile, with access to user profile information protected using OAuth 2.0 standards-based authorization.

This article walks you through a demonstration of the sample application’s capability. It uses the ForgeRock Identity Platform running on your computer to store and expose the user’s profile information.

Running the ForgeRock Identity Platform

The demonstration in this article depends on the 6.5 release of the ForgeRock Identity Platform. The ForgeRock platform assets for Kubernetes deployments are defined in a git repository called forgeops. The forgeops assets let you run the platform in minikube on your computer, or in a Kubernetes-based cloud platform. This article assumes you want to try the sample on your computer with minikube.

The sample configuration, including the resource server (RS) that depends on OAuth 2.0 for API protection, is defined in a git repository called forgeops-init. You apply the configuration to the assets defined in forgeops.

The setup process builds the following layers, starting from the bottom and working up:

Follow these steps to build the bottom three layers:

Install third-party software for Kubernetes support:

Docker (Get Docker)
minikube (minikube start | minikube)
(required to run everything locally on your laptop)
kubectl (Install Tools | Kubernetes)
helm (GitHub - helm/helm: The Kubernetes Package Manager)
skaffold (GitHub - GoogleContainerTools/skaffold: Easy and Repeatable Kubernetes Development)

Clone the following git repositories:

Clone at least the forgeops and forgeops-init repositories into the same directory. The code in the forgeops-init repository relies on the relative location of the forgeops repository.

Use the 6.5 forgeops artifacts:

cd forgeops
git checkout release/6.5.1

Follow the README for the 6.5 branch of the Platform OAuth2 Sample
(forgeops-init/6.5/oauth2/development at master · ForgeRock/forgeops-init · GitHub).

At the end of this part of the setup process, verify that you have completed all steps successfully. For example, log in to the end user UI as user.0:password to view the user’s profile page. Start by visiting the end user UI login page, ignoring certificate validation errors if you have not trusted the test CA certificate, google-chrome --ignore-certificate-errors https://end-user-ui.sample.forgeops.com/:

This shows that you have successfully deployed the ForgeRock Identity Platform 6.5 in minikube.

Running the Sample Application

The sample application under exampleOAuth2Clients/openidm-ui-enduser-jso uses the JSO JavaScript library (JSO) for OAuth 2.0 support. The application is the ForgeRock end user UI, wrapped with JSO to run as an OAuth 2.0 public client, playing the role of an OpenID Connect relying party (RP).

The application is registered with ForgeRock Access Management (AM), playing the role of the OAuth 2.0 AS and OpenID Provider (OP). ForgeRock Identity Gateway (IG), playing the role of RS, protects ForgeRock Identity Management (IDM) APIs, including the profile management APIs. AM, IDM, and IG are deployed in minikube as described above.

The sample application is open source software. ForgeRock would like to know how you use it.

ForgeRock welcomes your PRs, bug reports and requests for enhancements on GitHub at GitHub - ForgeRock/exampleOAuth2Clients: Example OAuth2 clients for standards-based profile management.

To run the sample application, follow these steps:

Check out the 6.5 version of the sample application code:

git checkout -b 6.5 -t origin/6.5

Switch to the exampleOAuth2Clients/openidm-ui-enduser-jso directory.
Review the sample code in index.html. You can see how JSO wraps requests for the underlying end user UI app.
Register the application as a public OAuth 2.0 client with AM:

curl -k 'https://login.sample.forgeops.com/json/realms/root/realm-config/agents/OAuth2Client/openidm-ui-enduser-jso' \
   -X PUT \
   --data '{
       "clientType": "Public",
       "redirectionUris": ["http://localhost:18888"],
       "scopes": [
           "openid",
           "profile",
           "profile_update",
           "consent_read",
           "workflow_tasks",
           "notifications"
       ],
       "isConsentImplied": false,
       "postLogoutRedirectUri": ["http://localhost:18888"],
       "grantTypes": ["implicit"]
       }' \
       -H 'Content-Type: application/json' \
       -H 'Accept: application/json' \
       -H 'Cookie: iPlanetDirectoryPro='$( \
           curl -k 'https://login.sample.forgeops.com/json/realms/root/authenticate' \
           -X POST \
           -H 'X-OpenAM-Username:amadmin' \
           -H 'X-OpenAM-Password:password' | sed -e 's/^.*"tokenId":"\([^"]*\).*$/\1/' \
       )

The response is a JSON resource indicating successful registration. Key fields:

{"_id":"openidm-ui-enduser-jso", "_type":{"_id":"OAuth2Client","name":"OAuth2 Clients","collection":true}}

Serve the files through an HTTP server on your computer:

http-server -p 18888

Demonstrating Profile Protection

Once the ForgeRock Identity Platform and sample application are running together, you can demonstrate profile protection by following these steps:

Log in through the home page. For example, visit google-chrome --ignore-certificate-errors http://localhost:18888/, and log in with user.0:password credentials.
After login, accept the conditions on the consent screen to authorize the application by selecting Allow:

3. The application is now authorized to access to the user’s profile:

The protected APIs are listed in the forgeops-init OAuth 2.0 sample README. For details about the RS, see the sample IG configuration. Read the IG Configuration Reference to interpret any settings that are unclear.