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:
- Install GDS-SSO gem as per the gem instructions.
- Determine whether the whole application or just particular routes need authentication.
- 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).
- Update the application tests so that there is a user created or mocked for tests. Example commit.
- 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
- 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_secretfor each environment
- 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:
- 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.
- 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.
- API application only: Use the bearer tokens in applications that need to authenticate with your application.
- Once all these changes are merged and deployed you should see the environment variables set up in the appropriate environments.
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.