Table of contents

Add authentication to an application

This document aims to provide instructions for adding authentication to both new applications and an existing application. The process of adding authentication is much simpler (and less scary) when the application is new.

The process outlined here relies on the data sync to synchronise credentials between production and staging which will mean that you will have to wait overnight from starting this to completing.

Setting up authentication for your Ruby application

Prior to merging authentication into an existing application there are a number of steps that need to be performed so that users/applications can access the app immediately.

To set up an application:

  1. Install GDS-SSO gem as per the gem instructions.
  2. Determine whether the whole application or just particular routes need authentication.
  3. Configure the application to require authentication. If you’re using a non-Rails app it’d be prudent to check Omniauth documentation (GDS-SSO uses Omniauth).
  4. Update the application tests so that there is a user created or mocked for tests. Example commit.
  5. If the application is part of Publishing End-to-end Tests then you may need to add user creation to the database seeds. Example commit.

Before an application can be deployed with authentication

  1. Your application will need to be registered as an application in signon in production and integration. Staging is not required as it will be synced with production as part of the data sync.
    • Create the application in signon with a rake task
    • Make a note of the oauth_id and oauth_secret for each environment
  2. API application only: Create bearer tokens for all the applications that will need authenticated access to your application.
    • Identify each of the applications that communicate with your application, the Architectural overview of GOV.UK applications may help, and determine whether they need authenticated access.
    • For each of these:
      • Find or create an API user for the application in Production and Integration;
      • Run the “Add application token” action to create a token for the application added in step 1;
      • Make a note of the created token;
      • Add any necessary app permissions to the application access.
  3. Add the tokens and oauth credentials you have created to govuk-secrets. This is so they can be used in Puppet hieradata. The production tokens should also be added to the staging secrets. Example PR.
  4. Create environment variables in govuk-puppet for the tokens you have created. Example PR.
    • If your application runs on the draft stack you’ll also need to ensure it can communicate with signon. Example PR.
  5. API application only: Use the bearer tokens in applications that need to authenticate with your application.
    • Applications differ in how they configure bearer token.
    • The ideal approach is for the bearer token to be set automatically in GDS API Adapters.
    • You may need to update lib/services.rb or find where GdsApi classes are initiailised.
  6. Once all these changes are merged and deployed you should see the environment variables set up in the appropriate environments.

Deploying

If you are adding authentication to an existing application the deployment process should be approached with caution as a mistake in copying the tokens could break the app in any of the environments.

Once you have completed all the steps above you should start by deploying the branch of your application to integration and check that:

  • Authentication is enabled - this can be achieved by doing a curl request on the box against a known authenticated route of the application;
  • Check the logs to ensure the application is successfully processing requests.

Once this is verified the branch can be merged.

Prior to deploying to staging and production you should inform 2nd line so they are prepared for any problems. For each environment you deploy to you should repeat the same checks that authentication is enabled and that the application is still successfully processing requests.

This page was last reviewed on 18 December 2018. It needs to be reviewed again on 18 June 2019 by the page owner #govuk-2ndline .
This page was set to be reviewed before 18 June 2019 by the page owner #govuk-2ndline. This might mean the content is out of date.