Demonstrating OAuth 2.0 Authorization Code Grant in a Vert.x App

Setup
, , , , , , , ,
#1

Written by Marc Craig

Summary

Instructions for demonstrating an OAuth 2.0 authorization code grant in a Vert.x App.

The OAuth 2.0 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. When the client can protect its credentials, the authorization code grant is preferred.

ForgeRock provides a sample Vert.x application that demonstrates how to use the OAuth 2.0 authorization grant. The application reads the user’s profile information 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:

image
image968×378 56.3 KB

Follow these steps to build the bottom three layers:

  1. Install third-party software for Kubernetes support:
  1. 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.

  1. Use the 6.5 forgeops artifacts:

cd forgeops git checkout release/6.5.1

  1. Follow the README for the 6.5 branch of the Platform OAuth2 Sample.

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/basic-vertx uses Vert.x OAuth 2.0 support to protect access to user profile information served by the ForgeRock Identity Platform.

The application is registered with ForgeRock Access Management (AM), playing the role of the OAuth 2.0 Authorization Server (AS). 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:

  1. Check out the 6.5 version of the sample application code:
git checkout -b 6.5 -t origin/6.5
  1. Switch to the exampleOAuth2Clients/basic-vertx directory.
  2. Review the sample code, src/app.groovy. You can see how the OAuth2AuthHandler protects access to the profile information.
  3. Register the application as a confidential OAuth 2.0 client with AM:
curl -k 'https://login.sample.forgeops.com/json/realms/root/realm-config/agents/OAuth2Client/vertxClient' \
 -X PUT \
 --data '{
     "userpassword": "vertxClientSecret",
     "redirectionUris": ["http://localhost:18888/callback"],
     "scopes": ["openid","profile"],
     "tokenEndpointAuthMethod": "client_secret_post"
 }' \
 -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":"vertxClient", "_type":{"_id":"OAuth2Client","name":"OAuth2 Clients","collection":true}}
  1. Run the app on your computer:On macOS:
docker build -t basicvertxclient:latest .
docker run -d -p 18888:18888 -p 5005:5005 basicvertxclient:latest

On Linux:

docker build -t basicvertxclient:latest .
docker run -d --network host basicvertxclient:latest

Demonstrating Profile Protection

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

  1. View the home page of the sample application. For example, google-chrome --ignore-certificate-errors http://localhost:18888/:

  1. Select Access Protected Resources to visit the login page, and log in with user.0:password credentials:


3. After login, accept the conditions on the consent screen to authorize the application by selecting Allow:


4. The application is now authorized to read the user’s profile information:

Further Reading

  • A full description of the sample application is in the README.
  • The documentation about forgeops and the related deployment models is published on ForgeRock BackStage. The first document to read is Start Here.
  • For more information about the ForgeRock Identity Platform, see the ForgeRock Identity Platform page.