Quick start

Using this page is optional but can be helpful to see how a typical integration with GOV.UK One Login works.

You’ll create an example service using either a local copy of the GOV.UK One Login simulator or the GOV.UK One Login integration environment.

You’ll be able to test authentication-only or authentication and identity journeys, and see the responses from these endpoints:

You have 3 different options to create an example service, depending on your needs and how much code you want to view.

Method to run the example service	Approximate time	Result
With the GOV.UK One Login simulator using Docker Compose.	3 minutes	You’ll see the simulated response from GOV.UK One Login without viewing additional code.
With the GOV.UK One Login simulator using source code.	10 minutes	You’ll see the simulated response from GOV.UK One Login and view additional code.
Using the GOV.UK One Login integration environment.	15 minutes	You can use test user data to interact with the integration environment.

Prerequisites

On the command line, run git clone https://github.com/govuk-one-login/onboarding-examples && cd onboarding-examples/clients/nodejs. This will get the example Typescript code and set your working directory.
On the command line, run docker compose up.
Open http://localhost:8080.
Select Make a request for authentication.
If you want to run an identity journey, select Make a request for authentication and identity.
Select the Sign out link in the top header.

On the command line, run git clone https://github.com/govuk-one-login/onboarding-examples && cd onboarding-examples/clients/nodejs. This will get the example Typescript code and set your working directory.
Run nvm install 22.11.0 && nvm use 22.11.0. This makes sure you’re using the correct version of Node.js.
Run npm run simulator:start to start the simulator in a Docker container.
Check the simulator is working by running npm run simulator:config. You should see the simulator configuration appear.
Run npm ci && npm run dev:sim to build and run the example.
View the example service by going to http://localhost:8080 in your browser.
Select Start by logging in.
You should see the response from the /userinfo and /token endpoints: ID and access tokens and user attributes.
If you want to run an identity journey, select Verify again and you should see a successful identity response including the coreIdentityJWT, returnCode (empty), address claims.
Select Sign out in the top header.
You’ll see a page which says Logged out.

Before you start, make sure you have a:

On the command line, run git clone https://github.com/gov-uk-one-login/onboarding-examples && cd onboarding-examples/clients/nodejs. This will get the example Typescript code and set your working directory.
Run nvm install 22.11.0 && nvm use 22.11.0. This makes sure you’re using the correct version of Node.js.
Run npm run generatekeys. This generates a key pair if one does not exist yet.
Launch the GOV.UK One Login admin tool.
Follow on-screen instructions to register and manage your service in the integration environment.
Configure your service name or names as onboarding-example - {DEPARTMENT} - {SERVICE_TEAM_NAME}
Find your Client ID value and make a record of it. You’ll need this later when configuring the example application.
Configure your service including (at a minimum):
- a redirect URI: http://localhost:8080/oidc/authorization-code/callback
- a public key (copy the static public key you created earlier from the ./public_key.pem file, excluding the headers)
- scopes: openid, email, phone
- a post logout redirect URI: http://localhost:8080/oidc/logged-out
- there’s further guidance on registering and managing your service if you want to include additional fields

Create a .env.integration configuration file by copying the .env.integration.example file to .env.integration.
Edit .env.integration in your preferred source editor and update:
- the {CLIENT_ID} placeholder to contain the Client ID from the GOV.UK One Login admin tool
- the {PRIVATE_KEY} placeholder with the contents of the ./private_key.pem file you created earlier (excluding the headers)

Run npm ci && npm run dev:int – this installs the dependencies and runs the application.
View the example service by going to http://localhost:8080 in your browser.
Select Start by logging in.
- if you see a prompt asking for a username and password, you can find the credentials by scrolling down to the bottom of your service’s homepage on the GOV.UK One Login Admin tool
Follow the on-screen instructions to create a GOV.UK One Login.
You should see the response from the /userinfo and /token endpoints: ID and access tokens and user attributes.

If you want to run an authentication-only journey, you can stop here.

If you want to run an authentication and identity journey, you should do the following additional steps as well as the steps above.

Update your client configuration in the integration environment using the GOV.UK One Login admin tool:
- set Prove user’s identities to Yes
- set the claims to coreIdentityJWT, returnCode and address
Follow the guidance to test a successful identity proving journey, starting at step 3.
You need to request fictional users and their knowledge-based verification (KBV) answers to help you test your journeys. Contact GOV.UK One Login to access this test user data.
Using this test user data, you should see a successful identity response including the coreIdentityJWT, returnCode (empty), address claims. If you do not, get in touch.

If you have any issues:

This page was last reviewed on 21 January 2025.