In this post, we’re going to talk about installing and setting up your very own OAuth2 provider. If you have used Facebook or Twitter logins, you’d know that they have their own OAuth2 providers. In reality, those are more than just OAuth2 providers as they also have OpenID Connect on them, however, that will be a post for another day.

Why would I want an OAuth2 provider?

Well, there are many reasons why you’d want an OAuth2 provider.

1. Because its cool.
2. Because its hip.
3. Because, why not?

On a more serious note, if you have a bunch of applications running in your house, you can use your own OAuth2 provider to provide identity and custom authorisations to every app in a way that if one of those apps gets compromised, it won’t take your whole house down. This lets you operate all of your apps in a standard way.

Also, who in your family doesn’t want “Sign in via <insert_family_name>” button? 😛

For this post, we’re going to use Forgerock’s OpenAM version 13.

Install prerequisites

OpenAM runs on tomcat so you need to install that first. We’re going to use OpenAM 13 for this demo along with Tomcat 8 running on Java 8. So the running order is:

1. Download Java 8 JDK
2. Download Tomcat 8
3. Download OpenAM 13 WAR (web archive)

Initial Setup

Before you start tomcat, copy the OpenAM 13 WAR into the tomcat webapps directory. This directory is typically under $TOMCAT_HOME/webapps where $TOMCAT_HOME is the root folder of where tomcat is installed. If you are unsure, $TOMCAT_HOME folder will also contain other directories like bin, conf, lib etc. When you copy the war over, make sure you rename it something memorable (and without any spaces or special characters) like openam.war. Whatever you rename this war to will become the context root of your web server. So if you rename the war file to openam.war, the openam server will become accessible at http://localhost:8080/openam.

Start tomcat by running the startup.sh shell script located in $TOMCAT_HOME/bin directory. To ensure that the startup was successful, open catalina.out log file located in $TOMCAT_HOME/logs directory. The war file is relatively large and could take some time to deploy. Make sure the log ends with something like this:

and has a line like:

somewhere above the startup log message.

Manually configure OAuth2 provider

Setup OAuth2 Provider

This is the quick and dirty way of configuring OAuth2 provider if you are using a server that is going to be long lived, as in, not a docker image. Once you do this, make sure you back up the disk to ensure that the settings are preserved.

In your web browser, navigate to the following URL:

Go through the default configuration. Setup the admin account password. Make sure you remember this as there is no way to recover it afterwards if you lose it. I usually have the admin account credentials as follows:

Once you have completed the initial setup, it will take you to the login screen. Login with your admin credentials and you will be taken to the OpenAM console. Here, click on the “Top Level Realm /” to configure the realm.

At this point, you should be able to see this:

In the common tasks pane, click “Configure OAuth Provider” button. From there, click “Configure OAuth 2.0” button. You should see something like this:

On this screen, you can configure your OAuth2 provider however you want. For simplicity reasons, lets just keep everything as default and click “Create” button. For me, this action takes less than a second. Click “OK” on the pop up modal.

Now you should be back to the OpenAM console realm overview page.

Setup OAuth Clients

If you have used any public OAuth2 providers like Facebook and Twitter, you should be familiar with OAuth clients. A client is an application that wants to access user data from the OAuth provider. Each client must first authenticate itself using a set of credentials and then request authorisation using scopes to access a set of resources.

The first part, authentication, is achieved by issuing a set of credentials which are, usually, a clientId and clientSecret. We need to create a client and then issue a clientId and clientSecret for it to use.

From the OpenAM dashboard, click on “Agents” on the left. In the resulting page, click on “OAuth 2.0/OpenID Connect Client” tab on the second tab row from the top.

Click “New” under the Agent section. Here, Name refers to the ClientId and Password refers to the ClientSecret. Once you’ve created a strong secret, click “Create”. This will take you back to the “OAuth 2.0/OpenID Connect Client” agents screen. Click into the agent that you just created.

Now this is the screen where you can fully configure almost every aspect about your client. You must explicitly whitelist the redirectionUri for your client as well as the scopes that are allowed for the client to access.

Ideally you should repeat this for every client application you have such that each application has a unique set of clientId and clientSecret.

Add users

Currently, you won’t have many users in your OAuth2 provider. Out of the box OpenAM will come with an embedded OpenDJ instance. At its core, OpenDJ is an LDAP data store with a REST interface around it.

The easiest way to add users is to click on “Subjects” item in the left pane on the OpenAM console realm overview page.

Under “Users” section, click on “New”. This should open up a “New User” screen where you can add some details about your user. Also, in case you didn’t notice, your OpenAM instance comes built in with a “demo” user. The “demo” user has its default password set to “changeit”.

Now that you have added some users and have a client, you should be able to write an OAuth2 client app that allows you to “Sign In” via your OAuth2 provider instance!