Note
These notes are based on my initial contact with the tool and assume you are running MacOS.
The GOV.UK One Login simulator is a tool for developers working with GOV.UK One Login to enable the development of custom integrations and testing. The example application shows how a client integrates with the GOV.UK One Login simulator or integration environment.
The simulator can stand in for the integration environment.
It is a implemented in typescript and express, packaged with Docker using Node.js 22.9.0.
| container | url |
|---|---|
| simulator | https://github.com/govuk-one-login/simulator/pkgs/container/simulator |
| onboarding-example-nodejs | https://github.com/orgs/govuk-one-login/packages/container/package/onboarding-example-nodejs |
The supported API endpoints:
| category | method | endpoint | url | description |
|---|---|---|---|---|
| OPENID | GET | / |
http://localhost:3000/ | issuer |
| OPENID | GET | /.well-known/openid-configuration |
http://localhost:3000/.well-known/openid-configuration | OpenID configuration |
| CUSTOM | GET | /.well-known/did.json |
http://localhost:3000/.well-known/did.json | keys in DID format |
| OPENID | GET | /.well-known/jwks.json |
http://localhost:3000/.well-known/jwks.json | keys in JWKS format |
| OPENID | GET | /trustmark |
http://localhost:3000/trustmark | trustmark endpoint |
| OPENID | GET | /authorize |
http://localhost:3000/authorize | authorize endpoint |
| OPENID | GET | /userinfo |
http://localhost:3000/userinfo | userinfo endpoint |
| OPENID | GET | /logout |
http://localhost:3000/logout | logout endpoint |
| OPENID | POST | /token |
http://localhost:3000/token | token endpoint |
| CUSTOM | GET POST | /config |
http://localhost:3000/config | config |
The following features are not implemented:
- jar requests is not currently supported but is the subject of govuk-one-login/simulator#233
- backchannel logout
- the
client_secret_posttoken authentication method PermitMissingNonce- TLS (https://localhost)
You will need the following tools:
| package | description |
|---|---|
| curl | HTTP CLI |
| docker | Docker desktop containers |
| gnu-sed | GNU sed |
| homebrew | Homebrew package manager |
| gh | GitHub CLI |
| jq | JSON CLI tool |
| visual-studio-code | Developer IDE |
| humao.rest | Rest Client extension for Visual Studio Code |
I install the prerequisites using homebrew with the following commands:
brew install docker curl gh gnu-sed jq visual-studio-code
code --install-extension humao.rest-client
You need to enable Docker host networking.
docker - Settings - Resources - Network
Other permutations will probably work but this is what I am actually tested.
| package | version |
|---|---|
| bash | 5.2.37 |
| curl | 8.7.1 |
| docker | 4.35.0 |
| gh | 2.62 |
| jq | 1.7.1 |
| macOS | 14.7.1 |
| node | 22.9.0 |
| npm | 10.8.3 |
| nvm | 0.40.1 |
| visual-studio-code | 1.95.3 |
| wireshark | 4.4.3 |
This application stands in for the actual GOV.UK One Login OpenID Connect Provider (OP) and acts as a useful target for initial development.
It ships with a default configuration which is available to use out of the box. There are several ways it can be used depending on your needs.
git clone https://github.com/govuk-one-login/simulator
cd simulator
nvm install 22.11.0 && nvm use 22.11.0
npm ci && npm run build
npm run start
curl -sv http://localhost:3000
git clone https://github.com/govuk-one-login/simulator
cd simulator
docker build -t simulator .
run interactively with
docker run -ti -p 3000:3000 simulator
or run as a daemon with
docker run -d -p 3000:3000 simulator
Run interactively with
docker compose up --build
or run as a daemon with
docker compose up --build --detach
The official image is hosted at https://github.com/govuk-one-login/simulator/pkgs/container/simulator and is published to GitHub container registry by the publish-image.yml GitHub action whenever changes are merged to the main branch.
It has minimal dependencies and is the simplest way to run the simulator
docker run -d -p 3000:3000 ghcr.io/govuk-one-login/simulator:latest
test it is responding
curl -s localhost:3000
optionally check it is responding on port 3000, if not start the simulator
curl -s "localhost:3000" > /dev/null || docker run -d -p 3000:3000 ghcr.io/govuk-one-login/simulator:latest
To override the default port (3000) run
docker run -e SIMULATOR_URL='http://localhost:3333' -e PORT=3333 --rm -ti -p 3333:3333 ghcr.io/govuk-one-login/simulator:latest
a variation of 1. using a temporary configuration using a convenience script as a one liner
bash -c "$(curl -fsSl https://gist.githubusercontent.com/pauldougan/4824c689ad775a298af5e49d4aead309/raw/f0f45f56129e60a1529b3e33e48ffb6e6d151002/run-tmp-simulator.sh)"
using docker-compose.yaml
curl -s https://raw.githubusercontent.com/govuk-one-login/simulator/refs/heads/main/docker-compose.yml | docker compose -f - up
see https://github.com/govuk-one-login/simulator/blob/main/docs/interactive-mode.md
docker run -e INTERACTIVE_MODE=true -e SIMULATOR_URL='http://localhost:3333' -e PORT=3333 --rm -ti -p 3333:3333 ghcr.io/govuk-one-login/simulator:latest
running containers
resource usage
simulator image
images
logs
exec
files
stats
docker compose up --build --detach
docker ps
docker logs simulator
docker logs trusting_buck
> [email protected] start
> node dist/server.js
{"level":30,"time":1730996663709,"pid":19,"hostname":"e2dafe69d4f7","msg":"[server]: Server is running at http://localhost:3000"}
{"level":30,"time":1730996696331,"pid":19,"hostname":"e2dafe69d4f7","msg":"No prompt value included in authorisation request"}
{"level":30,"time":1730996696331,"pid":19,"hostname":"e2dafe69d4f7","msg":"No claims in authorisation request"}
{"level":30,"time":1730996696356,"pid":19,"hostname":"e2dafe69d4f7","msg":"Creating access token"}
{"level":30,"time":1730996696358,"pid":19,"hostname":"e2dafe69d4f7","msg":"Created Signed JWT with signing algorithm: \"ES256\" using keyId: b9162667-e025-4d93-8c5b-e538e6c792ac"}
{"level":30,"time":1730996696358,"pid":19,"hostname":"e2dafe69d4f7","msg":"Creating Id token"}
{"level":30,"time":1730996696359,"pid":19,"hostname":"e2dafe69d4f7","msg":"Created Signed JWT with signing algorithm: \"ES256\" using keyId: b9162667-e025-4d93-8c5b-e538e6c792ac"}
{"level":30,"time":1730996696359,"pid":19,"hostname":"e2dafe69d4f7","msg":"Id token created"}
{"level":30,"time":1730996696370,"pid":19,"hostname":"e2dafe69d4f7","msg":"No identity claims in access token."}
{"level":30,"time":1730996696370,"pid":19,"hostname":"e2dafe69d4f7","msg":"Successfully validated access token."}
there are two main approaches to configuring the simulator
- environent variables
- the configuration endpoint
need to add something about
- logging levels for node
- debugging node
might need to add some addtional targets for npm run
| name | description | default |
|---|---|---|
| CLIENT_ID | Client ID | HGIOgho9HIRhgoepdIOPFdIUWgewi0jw |
| PUBLIC_KEY | Public Key | -----BEGIN PUBLIC KEY-----MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAmXXR3EsRvUMVhEJMtQ1wexJjfQ00Q0MQ7ARfShN53BnOQEPFnS/I8ntBddkKdE3q+vMTI72w6Fv3SsMM+ciR2LIHdEQfKgsLt6PGNcV1kG6GG/3nSW3psW8w65Q3fmy81P1748qezDrVfaGrF4PDXALzX1ph+nz8mpKmck6aY6LEUJ4B+TIfYzlKmmwFe3ri0spSW+J5wE9mmT3VkR2ySuHRYHQlxlF9dfX7ltOTsbgJFzN6TO01ZQDhY0iLwzdGwhSxO6R6N/ZINYHCKFPaQD+tdKsrw7QDIYnx0IiXFnkGnizl3UtqSmXAaceTvPM2Pz84x2JiwHrp2Sml6RYLCQIDAQAB-----END PUBLIC KEY----- |
| SCOPES | Scopes | |
| REDIRECT_URLS | Redirect urls | http://localhost:8080/oidc/authorization-code/callback |
| CLAIMS | Claims | https://vocab.account.gov.uk/v1/coreIdentityJWT |
| IDENTITY_VERIFICATION_SUPPORTED | Identity supported | |
| TOKEN_SIGNING_ALGORITHM | Toem signing algorithm | |
| CLIENT_LOCS | Client levels of confidennce | ["P0", "P2"] |
| SUB | subject ID | urn:fdc:gov.uk:2022:56P4CMsGh_02YOlWpd8PAOI-2sVlB2nsNU7mcLZYhYw= |
[email protected] |
||
| EMAIL_VERIFIED | Email is verified | |
| PHONE_NUMBER | Phone number | 07123456789 |
| CORE_IDENTITY_ERRORS | ||
| ID_TOKEN_ERRORS | ||
| AUTHORIZE_ERRORS | ||
| SIMULATOR_URL | http://localhost:3000 |
display the current confituration
curl -s loclhost:3000/config | jq .
{
"clientConfiguration": {
"clientId": "HGIOgho9HIRhgoepdIOPFdIUWgewi0jw",
"publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAmXXR3EsRvUMVhEJMtQ1w\nexJjfQ00Q0MQ7ARfShN53BnOQEPFnS/I8ntBddkKdE3q+vMTI72w6Fv3SsMM+ciR\n2LIHdEQfKgsLt6PGNcV1kG6GG/3nSW3psW8w65Q3fmy81P1748qezDrVfaGrF4PD\nXALzX1ph+nz8mpKmck6aY6LEUJ4B+TIfYzlKmmwFe3ri0spSW+J5wE9mmT3VkR2y\nSuHRYHQlxlF9dfX7ltOTsbgJFzN6TO01ZQDhY0iLwzdGwhSxO6R6N/ZINYHCKFPa\nQD+tdKsrw7QDIYnx0IiXFnkGnizl3UtqSmXAaceTvPM2Pz84x2JiwHrp2Sml6RYL\nCQIDAQAB\n-----END PUBLIC KEY-----\n",
"scopes": [
"openid",
"email",
"phone"
],
"redirectUrls": [
"http://localhost:8080/oidc/authorization-code/callback"
],
"postLogoutRedirectUrls": [
"http://localhost:8080/signed-out"
],
"claims": [
"https://vocab.account.gov.uk/v1/coreIdentityJWT",
"https://vocab.account.gov.uk/v1/address",
"https://vocab.account.gov.uk/v1/returnCode"
],
"identityVerificationSupported": true,
"idTokenSigningAlgorithm": "ES256",
"clientLoCs": [
"P0",
"P2"
]
},
"errorConfiguration": {
"coreIdentityErrors": [],
"idTokenErrors": [],
"authoriseErrors": []
},
"responseConfiguration": {
"sub": "urn:fdc:gov.uk:2022:56P4CMsGh_02YOlWpd8PAOI-2sVlB2nsNU7mcLZYhYw=",
"email": "[email protected]",
"emailVerified": true,
"phoneNumber": "07123456789",
"phoneNumberVerified": true,
"maxLoCAchieved": "P2",
"coreIdentityVerifiableCredentials": {
"type": [
"VerifiableCredential",
"IdentityCheckCredential"
],
"credentialSubject": {
"name": [
{
"nameParts": [
{
"value": "GEOFFREY",
"type": "GivenName"
},
{
"value": "HEARNSHAW",
"type": "FamilyName"
}
]
}
],
"birthDate": [
{
"value": "1955-04-19"
}
]
}
},
"passportDetails": null,
"drivingPermitDetails": null,
"socialSecurityRecordDetails": null,
"postalAddressDetails": [
{
"addressCountry": "GB",
"buildingName": "",
"streetName": "FRAMPTON ROAD",
"postalCode": "GL1 5QB",
"buildingNumber": "26",
"addressLocality": "GLOUCESTER",
"validFrom": "2000-01-01",
"uprn": 100120472196,
"subBuildingName": ""
}
],
"returnCodes": []
},
"simulatorUrl": "http://localhost:3000"
}
the configuration endpoint at http://localhost:3000/config can receive HTTP POST requests to modify the configuration
explain how
curl -s http://localhost:3000/.well-known/openid-configuration | jq .
{
"authorization_endpoint": "http://localhost:3000/authorize",
"token_endpoint": "http://localhost:3000/token",
"issuer": "http://localhost:3000/",
"jwks_uri": "http://localhost:3000/.well-known/jwks.json",
"scopes_supported": [
"openid",
"email",
"phone"
],
"response_types_supported": [
"code"
],
"grant_types_supported": [
"authorization_code"
],
"token_endpoint_auth_methods_supported": [
"private_key_jwt",
"client_secret_post"
],
"token_endpoint_auth_signing_alg_values_supported": [
"RS256",
"RS384",
"RS512",
"PS256",
"PS384",
"PS512"
],
"ui_locales_supported": [
"en",
"cy"
],
"service_documentation": "https://docs.sign-in.service.gov.uk/",
"op_policy_uri": "https://signin.account.gov.uk/privacy-notice",
"op_tos_uri": "https://signin.account.gov.uk/terms-and-conditions",
"request_parameter_supported": true,
"trustmarks": "http://localhost:3000/trustmark",
"subject_types_supported": [
"public",
"pairwise"
],
"userinfo_endpoint": "http://localhost:3000/userinfo",
"id_token_signing_alg_values_supported": [
"ES256",
"RS256"
],
"claim_types_supported": [
"normal"
],
"claims_supported": [
"sub",
"email",
"email_verified",
"phone_number",
"phone_number_verified",
"https://vocab.account.gov.uk/v1/passport",
"https://vocab.account.gov.uk/v1/socialSecurityRecord",
"https://vocab.account.gov.uk/v1/drivingPermit",
"https://vocab.account.gov.uk/v1/coreIdentityJWT",
"https://vocab.account.gov.uk/v1/address",
"https://vocab.account.gov.uk/v1/returnCode"
],
"request_uri_parameter_supported": false
}
curl -s http://localhost:3000/.well-known/jwks.json | jq .
{
"keys": [
{
"kty": "EC",
"x": "_wIZUJApU2PhbmkFBKBr0zD2iauSEGNB2yLYhrYyxLs",
"y": "XxqUE4h8d9bwGCPKeVOZi-x0nT6wnzSvXhgOxs8GM1k",
"crv": "P-256",
"kid": "b9162667-e025-4d93-8c5b-e538e6c792ac"
},
{
"kty": "RSA",
"n": "wsDTGdvnDGO8aEoohAEfCAaS_7jebu4DNJpHOO0PVvggx6Sn5kkZmWWqOv5RNGO8COR3FwU5GH9oMj0iuElmtLhPhIsh8n8feC3CLaH_mjY0oHJCe2L-LWhtIqTn4R6Wd8fZCedSmZnaE5qWzLcSBKlD0AouoF7pTo1kBSKD2u6yTEa01CJ3zAGMq0nL2b2LtosK2WYci5Ka-jUF1Q20qlOR1fYkwQ6yTcHYHKjF9Qq2SDFwlyg-CYthNioul5d8TFg5kFbnQJMJOyPBQn0XV58U2XditDa9WNwXNZGhagrHscJhalD9GqgzWB5jHLQQj5vWd4-xs6j81D6dLnWOhw",
"e": "AQAB",
"kid": "7334b718-3f29-44ef-8b65-e266a17daea5"
}
]
}
curl -s http://localhost:3000/.well-known/did.json | jq .
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/jwk/v1"
],
"id": "did:web:localhost%3A3000",
"assertionMethod": [
{
"type": "JsonWebKey",
"id": "did:web:localhost%3A3000#1f1caabb-b0bb-45b2-93ee-f47bf098dc1d",
"controller": "did:web:localhost%3A3000",
"publicKeyJwk": {
"kty": "EC",
"x": "dgH3plJS09HqOu_AMSuHhlsaZJPfX4uaVfotrnanBsk",
"y": "VGGoEHBQ1-yOsfTd3zMa4DnLTJp7XmKNjVmDt48CcwQ",
"crv": "P-256",
"alg": "ES256"
}
}
]
}
curl -s http://localhost:3000/trustmark | jq .
{
"idp": "http://localhost:3000/",
"trustmark_provider": "http://localhost:3000/",
"C": [
"Cl",
"Cl.Cm"
],
"P": [
"P0",
"P1",
"P2"
]
}
There is a example application https://github.com/govuk-one-login/onboarding-examples/tree/main/clients/nodejs that can be used with the simulator or the integration environment.
The example can be run in a variety of ways.
# build the example
git clone https://github.com/govuk-one-login/onboarding-examples
cd onboarding-examples/clients/nodejs
nvm use 22.10.0
npm install
# ensure a fresh simulator is running on port 3000
npm run simulator:start
# open a the browser in 5 seconds
(sleep 5; open http://localhost:8080)
# run the sample client
npm run dev
As 5.1 but before running the example run
bash ../../../data/simulator-configuration/curl/identity/identityrequest.sh
INSERT SCREENSHOTS
# build the example and open in Visual Studio Code
git clone https://github.com/govuk-one-login/onboarding-examples
cd onboarding-examples/clients/nodejs
code .
In Visual Studio Code start a terminal window and ensure a fresh simulator is running on port 3000
npm run simulator:start
open the package.json file
launch the npm run build target
launch the npm run dev target
open http://localhost:8080 inside Visual Studio Code
Hit the green button
docker build -t onboarding-example-nodejs:latest
docker run -it --rm -p 8080:8080 onboarding-example-nodejs:latest
Interactively with
docker run -it --rm -p 8080:8080 ghcr.io//govuk-one-login/onboarding-example-nodejs:latest
or as a background daemon with
docker run -d -it --rm -p 8080:8080 ghcr.io//govuk-one-login/onboarding-example-nodejs:latest
git clone https://github.com/onboarding-examples
cd onboarding-examples/clients/node.js
Run interactively with
docker compose up
Or run as a background daemon with
docker compose up -d
using compose.yaml
curl -s https://raw.githubusercontent.com/govuk-one-login/onboarding-examples/refs/heads/main/clients/nodejs/compose.yaml | docker compose -f - up
bash -c "$(curl -fsSl https://gist.githubusercontent.com/pauldougan/4824c689ad775a298af5e49d4aead309/raw/459c2bb27766b9e7dca9c5765898e5ef18f3379a/run-sample-with-simulator.sh)"
Browse to
https://codespaces.new/govuk-one-login/simulator
Create codespace
npm run build
or alternatively run the official simulator image from GitHub container registry
https://codespaces.new/govuk-one-login/onboarding-examples/tree/refactor-and-bump
Two ways
reset.sh
turn it off and on again with
npm run simulator:restart
The onboarding-examples repository contains some convenient configuration files that can be applied to the running simulator to modify its configuration. These are in the data/simulator-configuration folder and come in two types:
httpformat compliant with RFC???, these can be executed in Visual Studio Code using the REST plugin.curlformat, these can be executed directly to send the request to the server usingbashor by sourcing the file usingsource filename.shin the bash shell
There are a number of convenience npm run targets in the exanple that can be used to work with the simulator.
npm run simulator:startensure the simulator is runningnpm run simulator:stopstop the simulatornpm run simulator:resetreset the simulatornpm run simulator:logsdisplay the logsnpm run simulator:shellrun a shell inside the simulator
for the full list of targets run npm run
- Start capturing traffic to port 3000 on lo0
- Hit the
/configendpoint withcurl -s localhost:3000/config - Inspect packets
- Filter using
http and tcp.dstport == 3000
- Follow HTTP stream
GET /config HTTP/1.1
Host: localhost:3000
User-Agent: curl/8.7.1
Accept: */*
0.010718s
HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 1915
ETag: W/"77b-QJAuzn8fxmsJxqJP/lHyzdW8UaE"
Date: Mon, 20 Jan 2025 08:10:51 GMT
Connection: keep-alive
Keep-Alive: timeout=5
{"clientConfiguration":{"clientId":"HGIOgho9HIRhgoepdIOPFdIUWgewi0jw","publicKey":"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAmXXR3EsRvUMVhEJMtQ1w\nexJjfQ00Q0MQ7ARfShN53BnOQEPFnS/I8ntBddkKdE3q+vMTI72w6Fv3SsMM+ciR\n2LIHdEQfKgsLt6PGNcV1kG6GG/3nSW3psW8w65Q3fmy81P1748qezDrVfaGrF4PD\nXALzX1ph+nz8mpKmck6aY6LEUJ4B+TIfYzlKmmwFe3ri0spSW+J5wE9mmT3VkR2y\nSuHRYHQlxlF9dfX7ltOTsbgJFzN6TO01ZQDhY0iLwzdGwhSxO6R6N/ZINYHCKFPa\nQD+tdKsrw7QDIYnx0IiXFnkGnizl3UtqSmXAaceTvPM2Pz84x2JiwHrp2Sml6RYL\nCQIDAQAB\n-----END PUBLIC KEY-----\n","scopes":["openid","email","phone"],"redirectUrls":["http://localhost:8080/oidc/authorization-code/callback"],"postLogoutRedirectUrls":["http://localhost:8080/signed-out"],"claims":["https://vocab.account.gov.uk/v1/coreIdentityJWT","https://vocab.account.gov.uk/v1/address","https://vocab.account.gov.uk/v1/returnCode"],"identityVerificationSupported":true,"idTokenSigningAlgorithm":"ES256","clientLoCs":["P0","P2"]},"errorConfiguration":{"coreIdentityErrors":[],"idTokenErrors":[],"authoriseErrors":[]},"responseConfiguration":{"sub":"urn:fdc:gov.uk:2022:56P4CMsGh_02YOlWpd8PAOI-2sVlB2nsNU7mcLZYhYw=","email":"[email protected]","emailVerified":true,"phoneNumber":"07123456789","phoneNumberVerified":true,"maxLoCAchieved":"P2","coreIdentityVerifiableCredentials":{"type":["VerifiableCredential","IdentityCheckCredential"],"credentialSubject":{"name":[{"nameParts":[{"value":"GEOFFREY","type":"GivenName"},{"value":"HEARNSHAW","type":"FamilyName"}]}],"birthDate":[{"value":"1955-04-19"}]}},"passportDetails":null,"drivingPermitDetails":null,"socialSecurityRecordDetails":null,"postalAddressDetails":[{"addressCountry":"GB","buildingName":"","streetName":"FRAMPTON ROAD","postalCode":"GL1 5QB","buildingNumber":"26","addressLocality":"GLOUCESTER","validFrom":"2000-01-01","uprn":100120472196,"subBuildingName":""}],"returnCodes":[]},"simulatorUrl":"http://localhost:3000"}
- https://github.com/govuk-one-login/simulator
- https://github.com/govuk-one-login/simulator/pkgs/container/simulator
- https://github.com/govuk-one-login/onboarding-examples
- https://github.com/govuk-one-login/onboarding-examples/tree/main/clients/nodejs
- https://github.com/govuk-one-login/onboarding-examples/tree/main/example-data/identities
- https://github.com/govuk-one-login/simulator?tab=readme-ov-file#configuration
- https://github.com/govuk-one-login/simulator/blob/main/package.json
- https://github.com/govuk-one-login/simulator/blob/main/src/config.ts
- https://github.com/govuk-one-login/simulator/blob/main/src/app.ts
- https://github.com/govuk-one-login/simulator/blob/main/src/constants.ts