Skip to main content
  1. Home
  2. Applications
Warning This document has not been updated for a while now. It may be out of date.
Last updated: 2 Nov 2022

Add authentication to an application

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 and 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, 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.

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 Technical 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.

More in the Applications section

Learn

How to...