Overview

This lab configures API Protection using OAuth 2.0. The API to be protected is SmartPlan energy meter, which gives real time data on buildings and charging stations. Electric Green Cabs has developed a mobile app (Green cabs Mobile) that will fetch data from SmartPlan API. Users will log in with their existing SmartPlan credentials (CustomerID users' repository).

As a refresher on OAuth2, let us review the three main elements and its equivalent in our SmartPlan use case:

The diagram below also shows the interactions among these three components.

All three elements will run on your local environment. Both SimpleSPA and SimpleAPI require Apache HTTP Server running.

SimpleSPA will be installed on port 5000.

SimpleAPI will be installed on port 5001.

In a real deployment, each of these services can and would be in different environments: Electric Green Cabs would host the client (mobile app), SmartPlan would run the API. For the lab, all services will be run from the same host.

Business benefits

SmartPlan is now able to securely open their APIs to third-parties like Electric Green Cabs company and ensure that data access is done with the permission of the data owner.

Access to the API can be controlled through permissions and revoked at any time.

Partners and customers are able to develop innovative new services based on these APIs.

SmartPlan gets competitive advantage and possible additional revenue streams from this service.

Customers are happy that they authorise access to the API using their familiar, existing account.

Instructions

The diagram below shows the main steps on this lab.

Part 1: Install Apache HTTP server

First you need to install Apache HTTP server on your own instance.

1. To install Apache HTTP server, copy the file httpd-2.4.39-win64-VC14.zip (at the bottom of this page) to Downloads folder.
2. Unzip the compressed file so it will create a subdirectory \Downloads\Apache24
   
   

Part 2: Install SimpleAPI

Next you have to install SimpleAPI, a simple API example built for testing purposes that requires an OAuth2 token to use.

Step 1: Install SimpleAPI

1. Unzip the package SimpleAPI (at the bottom of this page) to Downloads\Apache24 folder. It will create the folder "C:\Users\StudentX\Downloads\Apache24\SimpleAPI-smartplan"
   
   

   Replace username

   Remember to replace "StudentX" with the real username that the instructor has assigned you (e.g. Student1). Keep it in mind for coming steps in this lab.

2. Modify file C:\Users\StudentX\Downloads\Apache24\SimpleAPI-smartplan\conf\httpd.conf. Append following lines to the end of file:

   Downloads\Apache24\SimpleAPI-smartplan\conf\httpd.conf

   LoadModule ssl_module ${ModulesDir}/mod_ssl.so
   <VirtualHost _default_:5001>
   ServerName greencabs.com:5001
   SSLEngine on
   SSLCertificateFile "${ServerRoot}/conf/server.crt"
   SSLCertificateKeyFile "${ServerRoot}/conf/server.key"
   </VirtualHost>

Step 2: Install mod_auth_openidc

mod_auth_openidc is an authentication/authorisation module for the Apache 2.x HTTP server that authenticates users against an OpenID Connect Provider. It can also function as an OAuth 2.0 Resource Server, validating access tokens presented by OAuth 2.0 clients against an OAuth 2.0 Authorization Server. Source: https://www.mod-auth-openidc.org/

1. Install mod_auth_openidc from the given file mod_auth_openidc-2.3.8-apache-2.4.x-win64.zip. You will find it at the bottom of this page too. Simply extract the zip file to Downloads folder so it will create the folder "C:\Users\StudentX\Downloads\mod_auth_openidc-2.3.8-apache-2.4.x-win64".
2. The next step is adding login.smartplan.com certificate to mod_auth_openidc's trusted root store. This is required because login.smartplan.com has a self-signed certificate and by default is not trusted. First you must export login.smartplan.com certificate as a *.crt file.
3. In Firefox, go to your browser tab and open https://login.smartplan.com:8443/ubilogin
   
4. Click the padlock
   
5. Expand "Connection" option
   
   
   
6. Click on "More Information"
   
   
   
7. Click "View Certificate." This will open a new tab on your browser. Scroll down until you find the option "Download."
   
   
   
   
8. Click on "PEM (cert)" link and save the file to Download folder.
   
   
   
   
9. Save it as "login_smartplan_com.pem" and open it with Notepad++
10. Now let's find mod_auth_openidc's trusted root store, a file titled "curl-ca-bundle.crt"
11. Open it with Notepad++ (its location is C:\Users\StudentX\Downloads\mod_auth_openidc-2.3.8-apache-2.4.x-win64\Apache24\bin).
12. Copy the full contents of "login_smartplan_com.pem" and paste it at the end of "curl-ca-bundle.crt"
13. Save "curl-ca-bundle.crt"

14. Generate a self-signed certificate. Open a command prompt and execute these two commands:
    
    

    cd \Users\StudentX\Downloads\Apache24\conf 
    
    ..\bin\openssl req -new -x509 -nodes -out server.crt -keyout server.key -config C:\Users\StudentX\Downloads\Apache24\conf\openssl.cnf

15. You wil be prompted to enter values several times and press "Enter" to continue. The values you must fill are:

    Country Name (2 letter code) [AU]:	FI
    Organization Name (eg, company) [Internet Widgits Pty Ltd]:	Greencabs
    Common Name (e.g. server FQDN or YOUR name) []:	greencabs.com

    All the other fields you can leave empty.
    After successful completion will look like this:
    
    
    
    
    

Step 3: Invoke SimpleAPI

1. Open the command prompt

2. Run cd %USERPROFILE%\Downloads\Apache24\SimpleAPI-smartplan

3. Then execute run-apache.cmd to start Apache HTTP server

4. The API is now running in https://greencabs.com:5001/simple. Open the URL on a browser and accept the security warnings. You will get a 401 Unauthorized error.  That is fine because you still need a client to invoke the API. In next section (Part 3) you will install a single page application (the client) to invoke the API and get a response from it.
5. Keep the command prompt window running. Don't close it until asked.
   
   

Part 3: Customise SimpleAPI to your authorisation server

Your local SSO installation will become the authorisation server. Now you must customise SimpleAPI to connect it with SSO (authorisation server) via OAuth2.

On SSO Management Console

1. In SmartPlan site, create new application "SimpleAPI." Select type "OAuth 2.0," tick Enabled box and press OK button.
2. Under "ID and Activation" press "Activate" button. This will generate a client_id and client_secret.
3. Save generated file as simpleapi.json in a temporary folder (e.g. Downloads).
4. Press "Update" at the bottom

5. You must also upload metadata. First, create a JSON file with the minimum metadata needed using the example below. As this is an API, it's important that redirect_uris and grant_types are empty.
   
   

   metadata-api-client.json

   {"redirect_uris":[] ,
   "grant_types":[] 
   }

6. Save this JSON file as metadata-api-client-json and then upload the file as seen below.
   
   
   
   
7. Press "Update" at the bottom
8. Next, add "CustomerID Password" in Allowed Methods, and "eIDMUser" in Allowed To tab.
9. Our SimpleAPI uses mod_auth_openidc for validating the access tokens and mod_auth_openidc expects the user identity as the "sub" claim when validating the tokens. To achieve this, add an Authorization Policy "SmartPlan API Policy" to the SmartPlan site and configure it as follows.
   Go to "Single Value Attributes" and write "sub" at the bottom (without quotation marks, as shown in the image below). Then click on "Add" button, and press "Update" at the bottom.
   
   
   
   Then go to "Attributes" tab and add the attribute sub with value user:mail as shown below
   
   
   
   
   
   
10. On the Applications tab, assign the SmartPlan API Policy to SimpleAPI
    

On the Simple API

We'll now configure client_id and client_secret to the SimpleAPI configuration, to integrate SSO and the SimpleAPI. 

1. Edit httpd.conf file with the values of your server. Open C:\Users\StudentX\Downloads\Apache24\SimpleAPI-smartplan\conf\httpd.conf in Notepad++.

2. Below you can see the three lines to be edited. Replace YOUR-CLIENT-ID and YOUR-CLIENT-SECRET with the actual values from simpleapi.json
   
   

   C:\Users\StudentX\Downloads\Apache24\SimpleAPI-smartplan\conf\httpd.conf

   # OAuth 2.0 resource server
   
   OIDCOAuthIntrospectionEndpoint https://login.smartplan.com:8443/uas/oauth2/introspection 
   
   OIDCOAuthClientID YOUR-CLIENT-ID
   OIDCOAuthClientSecret YOUR-CLIENT-SECRET
   
   

3. Save the file. Now the simple API is configured to connect to your SSO installation.

When an API request comes with an access token, the mod_auth_openidc module in front of the SimpleAPI app will call the OAuth2 Token Instrospection Endpoint ( https://login.smartplan.com:8443/uas/oauth2/introspection ), using the client_id and client_secret and credentials. In response, information about the token will be returned in JSON format - if the token is valid, access will be granted and the API will return results.

Part 4: Install and start SimpleSPA

Now you need a client that connects to the API. For this purpose, Ubisecure has designed a single page application called SimpleSPA, which runs on Apache HTTP Server too. 

As you have Apache already installed, you can copy the single page application to your computer

1. Unzip the package SimpleSPA-greencabs.zip (at the bottom of this page) to Downloads\Apache24 folder. It will create the folder "C:\Users\StudentX\Downloads\Apache24\SimpleSPA-greencabs"

2. Modify file C:\Users\StudentX\Downloads\Apache24\SimpleSPA-greencabs\conf\httpd.conf. Append following lines to the end of the file:

   Downloads\Apache24\SimpleSPA-greencabs\conf\httpd.conf

   LoadModule ssl_module ${ModulesDir}/mod_ssl.so
   <VirtualHost _default_:5000>
   ServerName greencabs.com:5000
   SSLEngine on
   SSLCertificateFile "${ServerRoot}/conf/server.crt"
   SSLCertificateKeyFile "${ServerRoot}/conf/server.key"
   </VirtualHost>
   
   

3. Modify file C:\Users\StudentX\Downloads\Apache24\SimpleSPA-greencabs\docs\spa.html. Open the file with Notepad++ and in line 12 change from "http://greencabs.com:5001/simple" to "https://greencabs.com:5001/simple"
   
   
4. Open another command prompt without closing the one used for SimpleAPI.
5. Run cd %USERPROFILE%\Downloads\Apache24\SimpleSPA-greencabs
6. Then execute run-apache.cmd to start this other Apache HTTP server instance
7. Now the single page application is running. Open https://greencabs.com:5000/spa.html in a browser
8. You can load the application, but can't login yet. The next step is configuring the authorisation server.

Part 5: Register SimpleSPA to the Authorisation Server

Now that the single page application is running, we will configure it to connect to our local SSO installation (login.smartplan.com).

On SSO Management Console

The first part of the configuration is done in SSO Management Console (https://login.smartplan.com:8443/ubilogin).

1. In SmartPlan site, create new application "SimpleSPA." Select type "OAuth 2.0," tick "Enabled" box and press OK button.
   
   
   
   
2. Under "ID and Activation" press "Activate" button. This will generate a client_id and client_secret.
   
   
   
   
3. Save generated file simplespa.json on a temporary folder such as Downloads. You will use it for next step.
4. Press "Update" at the bottom

5. Also under "ID and Activation" you will see "Application Metadata." Click "Upload" button and in the pop up windows that opens enter the following text:
   
   

   {"redirect_uris":["https://greencabs.com:5000/spa.html"],"grant_types":["authorization_code"]}

6. Click "OK"

   
   
   

7. Press "Update" at the bottom.
8. This has specified the redirect URI of the application and that Authorization Code is the OAuth2 grant type that will be used.
9. Finally, add "CustomerID Password" in Allowed Methods, and "eIDMUser" in Allowed To tab.

On the Single Page Application

We will now use the client_id and client_secret generated in the previous step. This will complete the integration between SSO and the single page application, so the single page application will get an access token for API calls.

The single page application's logic is on file C:\Users\StudentX\Downloads\Apache24\SimpleSPA-greencabs\docs\spa.html. You need to edit a few lines on it to match the authorisation server.

1. First, edit line 9:

   spa.html

   var issuer = "https://login.smartplan.com:8443/uas";

2. The next step is to add the client_id and client_secret values, which are inside the file simplespa.json you saved earlier.

3. Edit line 229 as explained in the table below
   
   
   
   

   Parameter	Replace it with
   SimpleSPA	value of client_id on simplespa.json
   public	value of client_secret on simplespa.json

   
   Below is an example how the line will look after the changes:
   
   
   
   

4. When the single page application request the access token, it must specify the target application of that access token. In this case is the SimpleAPI. Finally, edit line 273 as explained in the table below
   
   
   
   

   Parameter	Replace it with
   SimpleSPA	value of client_id on simplespa.json
   api	value of client_id on simpleapi.json  (← Obs. this value comes from SimpleAPI's JSON file)

   
   Below is an example how the line will look after the changes:
   
   
   
   

5. Now the single page application is configured. 

Part 6: Connect from your single page application to the protected API

1. First, restart both the API and the single page application. Do Ctrl-Z on the two command prompts, and then start them again as when were invoked for the first time.
2. Open https://greencabs.com:5000/spa.html on your browser:
   
   
   
   
3. Click "Login" button and authenticate with your CustomerID user account. Use Karl Kearnes (karl@kokomedia.local) account which was created in Lab 2.2: CustomerID Workflow Configuration. Password: Qwerty1234
4. You will see your ID Token on the upper box.
5. Next, invoke the API
6. You will get a response from the API
   

Part 7: Create an authorisation policy

At this point, all CustomerID users can log in to Green Cabs Mobile and from there can call SmartPlan API. The next step is to make that only a group of authorised users can access the application and API.

Another inconvenience you might have noticed is that the "sub" field in the ID Token reveals too much information about the data structure of the authorisation server .We'll use Persistent ID Mapping to solve this challenge.

Let's do the following two improvements:

1. Mask user distinguished name by creating and assigning a Persistent ID Mapping. Thus the authorisation server will send that persistent ID instead of the distinguished name, and will appear in ID token's "sub" field. 
2. Create an authorisation policy that:
   1. Allows access to the application and API only to a new group called "SmartPlan API users." Include only Karl Kearnes in this group.
   2. Has two attributes so you can visualize name and surname along with the ID token fields.

Step 1: Create a Persistent ID Mapping

Open SSO Management Console.

Go to SmartPlan site

Mappings

New Mapping ...

Name: Green Cabs persistent ID

NameID Format: Persistent ID (UUID format)

Finally, connect the Persistent ID Mapping to the SimpleSPA application

Step 2: Create an authorisation policy

Go to SmartPlan site

Groups

New Group

Create group: SmartPlan SPA users

Users

Add Karl Kearnes

In Allowed Applications, add both SimpleAPI and SimpleSPA

Go to SmartPlan site

Authorization Policies

New policy

Create "SmartPlan SPA Policy"

In Attributes add name and surname

In "Applications" tab add SimpleSPA

You still need to do a final step. At this point all users on CustomerID repository will be able to log in, as earlier in this lab you authorised them all. Now, remove eIDMUser group from both applications SimpleSPA and SimpleAPI. After that, only users from the new group "SmartPlan API users" will be authorised.

Once this is done, verify that Karl Kearnes can access the API but other normal users can't. Use Mary Smith (the user you created on Lab 2.2: CustomerID Workflow Configuration, Part 1)

Additional Exercise (Optional): Use Postman to view the access tokens

SimpleSPA (Green Cabs Mobile) has allowed you to see the contents of ID tokens.

Now use Postman as the client to authenticate yourself and visualize the access tokens.

Use the access token to get response from SmartPlan API.

*** END OF THIS LAB ***

Files needed for this lab:

Apache HTTP Server installation package

httpd-2.4.39-win64-VC14.zip

SimpleAPI

SimpleAPI-smartplan.zip

mod_auth_openidc

mod_auth_openidc-2.3.8-apache-2.4.x-win64.zip

SimpleSPA

SimpleSPA-greencabs.zip