How to secure your static or single page app using Pivotal SSO & Apache Web Server

Products

• VMware Tanzu Application Service for VMs

Issue/Introduction

It is common to have static sites. Perhaps these sites are generated by a static site generator, such as Hugo or they are single page Javascript applications, which need to limit who can access them. An easy way to do this is by using the Pivotal SSO Tile and its support for OpenID Connect (OIDC). Then you can use the Apache Web Server and mod_auth_openidc to serve files only to authorized users.

Environment

Resolution

This procedure walks you through securing a demo application, which has been preconfigured to work. Once you have the demo application working as desired, you can copy the configuration from the demo application to any other application you'd like too secure.

To get started

• Run `git clone https://github.com/dmikusa-pivotal/static-site-oidc-example`. This will download the demo app. Then change directory to `static-site-oidc-example`.
• Copy `vars-uaa-sso.yml` and rename it `vars.yml`. Don't worry about editing the name right now. Note: These instructions are for using Pivotal SSO and UAA, but they will work with any OIDC compliant provider. See the other `vars.yml` templates for help with other providers.
• Edit `manifest.yml` and add a route to the `routes:` block. The route will be the base for some of the SSO configuration options you'll enter when creating the SSO App.

Create your Pivotal SSO Service

• You can create the service in Apps Manager or using the cf cli. Pick any service plan that has been made available by your platform operator, it should not matter. For example, `cf create-service p-identity some-plan sso-service`.
• Navigate to Apps Manager, select your org and space and select the service instance you created in the previous step. You do not need to bind it to the app, just click the "Manage" link. This will take you to the Pivotal SSO Service Instance UI.
• We will now use the UI to create a new App. For Application type, select "Web". The "Application Launch URL" should be the route that you're assigning to your application. "Auth Redirect URIs" must contain the route that you'll be using for your app + "/redirect_url".
• For example: 
  • Application Launch URL:  https://static-site-oidc.cfapps.io/
  • Identity Providers: select where user information will be obtained
  • Auth Redirect URIs: https://static-site-oidc.cfapps.io/redirect_url
  • Scopes: openid
  • Auto Approved: none
  • Token Validity: default
• Create your app and leave the resulting screen open.

Configure mod_auth_openidc

• After you create the app, you'll be taken to a screen that shows the information you need to configure your `vars.yml` file. If you don't see this screen, click "Edit" on your app in the Pivotal SSO UI. Then without making any changes, click "Save" again. That will bring the screen back up.
• Open `vars.yml` in your favorite text editor and populate it based on the included comments using the information from the Pivotal SSO UI screen.
• In `vars.yml`, the last setting is `oidc-require-claim`. This dictates the claim that will be required for a user to be considered authorized to access the site. The default example is `email:admin` , which allows access to a single user with the email of "admin". To get started, change "admin" to the user you'll be using to login to the site.

Note: Use the exact credentials you use will relate to the Identity Provider you selected when you created the app. See Additional Information below.

• You can expand the list of authorized claims later. It helps to get in and try the demo app out first. This is because the demo app will show you the id_token, which lets you see all the information available on which you can base your claims. See the docs here for more details on the syntax that is supported.

Other Configuration Options

There are a few other options you might want to configure. See the list below and adjust based on your environment.

• If you are using Pivotal SSO and deploying to a Cloud Foundry (CF) foundation that is using self-signed TLS certs, edit `.bp-config/httpd/extra/httpd-php.conf` and uncomment the line, `OIDCSSLValidateServer Off`. This disables validation of the TLS cert used by the OIDC provider.
• Edit `.bp-config/options.json` and configure `ADMIN_EMAIL`. This is the email address that will be displayed on error pages generated by Apache Web Server.

Deploy the App

The last step is to run `cf push --vars-file vars.yml`. This will deploy your app using the custom `vars.yml` file that you created.

When the application starts, access the route that you mapped to the application in your browser. It should redirect you to the Pivotal SSO Service (you may need to authenticate with your identity provider first, if you're not already logged in) and ask you to verify the scopes requested by the application. When you confirm that, you should be redirected back to the application and authenticated.

If you would like to view the access token or your id_token, click the link at the bottom where it says `Click here to see a single page app demo`. The resulting page will provide you with a Javascript snippet that you can use to obtain the token. It also runs the Javascript and prints the actual token information for your user.

If you are still trying to figure out what you want to use for your authorization claim, you can review the id_token which provides the data against which you can make claims.

Additional Information

What Credentials do I use to Login?

The answer to this is that it depends on what you selected for an Identity Provider when you created your SSO App in the Pivotal SSO GUI. In most cases, you'll be selecting your company's corporate Identity Provider and should require you to login with your company credentials. In many cases, you may already be logged in so you won't even be asked to authenticate.

If you're using this in a test environment where you do not have a corporate Identity Provider configured, you can use the system or UAA provider, which allows you to authenticate with users that exist in UAA. If you go this route, you will need to create some users before you can login. Instructions for doing this can be found at this link .

Applying to Your Applications

When you are satisfied with the way the demo application behaves, you can move the configuration to another app by taking the following steps:

• Create a new project folder.
• Create a `site/` folder under the root of your project folder. Put all of your static files in this folder.
• Copy the `.bp-config/` folder, the `.profile` file, the `vars.yml` file and the `manifest.yml` file to the root of your new project.
• Edit the `manifest.yml` file and change your application name & routes.
• Create a new Pivotal SSO App for the new site.
• Edit `vars.yml` to contain the information from your new Pivotal SSO App.
• Run `cf push` to deploy your new application.