Create a configuration for each service you’re integrating
GOV.UK One Login is an OpenID Connect (OIDC) provider. An OIDC ‘relying party’ is a client application that outsources its user authentication function to an identity provider, which in this instance is GOV.UK One Login.
To interact with GOV.UK One Login, you must first register each of your services with GOV.UK One Login. You need to do this for each of the services that you want to integrate with GOV.UK One Login.
Understanding the client identifier
The client identifier is a unique value GOV.UK One Login requires to identify your services. GOV.UK One Login generates the client identifier for each of your services, when you register your service with GOV.UK One Login. GOV.UK One Login uses the client identifier to:
- retrieve configurations
- audit events
- capture performance analytics
- perform fraud prevention and data sharing
Why you should use a specific configuration for each service
You must use individual configurations for each of your services to get the following benefits:
- service specific reports with information about success rates and volumes
- protection for each service if another service has an outage - your other services will not be affected
- effective monitoring and detection of fraudulent activity
- better help for your users because the support team will have more detailed information on user activity
If you do not use individual configurations for each of your services, GOV.UK One Login cannot:
- monitor or detect fraudulent activities as effectively
- give you service specific analytics - we cannot generate this retrospectively if you later switch to individual configurations
- provide your users with a simpler and more personalised user journey
Organisations with multiple services may have additional requirements such as:
- sharing users across services - to enable this, set up a common sector identifier
- users that want to switch between services - to support users switching between services, your service must call the
/authorizeendpoint each time a user requests access to a new service
Once you have chosen which attributes your service can request, you can set up your service’s configuration with GOV.UK One Login.
Configure your service’s attributes
This is an index of all the attributes you can configure within GOV.UK One Login. You can find further details about each attribute below the tables.
There are also attributes configurable only by GOV.UK One Login.
| Name | Field | Configuration method | Description |
|---|---|---|---|
| Backchannel logout URI | BackChannelLogoutUri |
GOV.UK One Login admin tool | The endpoint GOV.UK One Login calls to send logout notifications. |
| Claims | Claims |
GOV.UK One Login admin tool | The claims your service may request from GOV.UK One Login. |
| Client ID | ClientID |
Generated by GOV.UK One Login admin tool | Your unique client ID. You must configure this into your service. |
| Client LOCs (level of confidence) | ClientLoCs |
Generated by GOV.UK One Login admin tool | Currently, GOV.UK One Login only supports P0 and P2. |
| Client name (Service name) | ClientName |
GOV.UK One Login admin tool | The name of your service, visible to users in the sign in journey. |
| Client Secret | ClientSecret |
By request - contact GOV.UK One Login | Only valid if you’ve set the authentication method to client_secret_post. |
| Contacts | Contacts |
GOV.UK One Login admin tool | Email addresses of your service’s technical contacts. |
| ID token signing algorithm | IdTokenSigningAlgorithm |
GOV.UK One Login admin tool | Either RS256 or ES256. Defaults to ES256. |
| Identity verification supported | IdentityVerificationSupported |
GOV.UK One Login admin tool | Whether your service can use identity verification. |
| JAR validation required | JarValidationRequired |
By request - contact GOV.UK One Login | Whether your service must send a signed authorisation request (JAR). This is false by default. |
| Jwks URL | JwksUrl |
GOV.UK One Login admin tool | The URL of your JWKS endpoint. Needed if using JWKS to provide your public keys. |
| Landing page URL | LandingPageUrl |
GOV.UK One Login admin tool | The page you’ll redirect your users to after their in-person identity check. |
| Max age enabled | MaxAgeEnabled |
GOV.UK One Login admin tool | Only available to services not on the GOV.UK domain and those handling particularly sensitive data. |
| Permit missing nonce | PermitMissingNonce |
By request - contact GOV.UK One Login | Defaults to false. |
| PKCE enforced | PKCEEnforced |
GOV.UK One Login admin tool | Whether your service must use Proof Key for Code Exchange (PKCE). |
| Post-logout URLs | PostLogoutRedirectUrls |
GOV.UK One Login admin tool | The set of URLs you may request your user is redirected to at the end of their logout journey. |
| Public key | PublicKey |
GOV.UK One Login admin tool | Needed if using private_key_jwt or a signed authorisation request (JAR). |
| Public key source | PublicKeySource |
GOV.UK One Login admin tool | Either STATIC or JWKS. Only required if the TokenAuthenticationMethod is private_key_jwt or you’re sending a signed authorisation request (JAR). |
| Rate limit | RateLimit |
By request - contact GOV.UK One Login | The number of authorise requests per minute allowed before GOV.UK One Login will start rejecting requests. |
| Redirect URLs | RedirectUrls |
GOV.UK One Login admin tool | The URL GOV.UK One Login returns your user to after they complete their journey. |
| Scopes | Scopes |
GOV.UK One Login admin tool | The scopes your service may request. You must include openid. |
| Sector identifier URI | SectorIdentifierUri |
GOV.UK One Login admin tool | Your service’s sector identifier. You must not change the sector identifier once your service has started to sign up or migrate users. Doing this will change the subject IDs GOV.UK One Login creates for each individual user, which may mean you have to rebind your users. Proceed with caution. |
| Token authentication method | TokenAuthMethod |
By request - contact GOV.UK One Login | Either private_key_jwt or client_secret_post. |
Configurable by GOV.UK One Login only
| Name | Field | Configuration method |
|---|---|---|
| Channel | Channel |
Not applicable - internal use only. |
| Client type | ClientType |
Not applicable - internal use only. |
| Cookie consent shared | CookieConsentShared |
Not applicable - internal use only. |
| Is active | IsActive |
Not applicable - internal use only. |
| Is deprecated | IsDeprecated |
Not applicable - internal use only. |
| One Login service | OneLoginService |
Not applicable - internal use only. |
| Service type | ServiceType |
Not applicable - internal use only. |
| Smoke test | SmokeTest |
Not applicable - internal use only. |
| Subject type | SubjectType |
Not applicable - internal use only. |
| Test client | TestClient |
Not applicable - internal use only. |
| Test client email allow list | TestClientEmailAllowlist |
Not applicable - internal use only. |
Backchannel logout URI
Specify the URI of the endpoint you want GOV.UK One Login to call when sending logout notifications to your service.
There’s further guidance on requesting logout notifications from GOV.UK One Login.
Channel
Internal use only. The value is always web.
Claims
If you’re doing identity verification, you’ll need to specify which claims your service requires.
You can choose one or more of the following:
https://vocab.account.gov.uk/v1/passporthttps://vocab.account.gov.uk/v1/drivingPermithttps://vocab.account.gov.uk/v1/addresshttps://vocab.account.gov.uk/v1/coreIdentityJWThttps://vocab.account.gov.uk/v1/returnCode
We recommend also including https://vocab.account.gov.uk/v1/returnCode to make your error handling clearer.
There’s further [guidance on return codes][integrate.return-codes].
If you’re requesting identity verification, you must include: https://vocab.account.gov.uk/v1/coreIdentityJWT
There’s further guidance on choosing which claims your service can request.
Client ID
Your client ID is unique to your service. You’ll create your client ID when you register your service. You must configure this into your service to make requests to GOV.UK One Login.
You cannot change your client ID. If you need a new one, you must register a new client.
Client LOCs
The level of confidence (LOC) at which your service can request GOV.UK One Login verifies a user’s identity.
Currently, GOV.UK One Login only supports P0 and P2.
Client name
Choose your client name.
The client name appears in the user interface when GOV.UK One Login redirects your user back to your service. You should choose something your users will recognise.
There’s further guidance on naming your service.
Client secret
The client secret to validate /token requests made using your ClientID. Only valid if you’ve set the authentication method to client_secret_post.
Client type
The client type is always web. You cannot change this value.
Contacts
Enter the email addresses of your service’s technical contacts. This can be a group email or multiple separate email addresses, or a combination of both.
GOV.UK One Login uses these to notify your team about service changes or incidents.
Cookie consent shared
Cookie consent shared is always false. You cannot change this value.
Contacts
Email addresses of your service’s technical contacts.
ID token signing algorithm
By default, GOV.UK One Login signs the id_token JSON Web Token (JWT) using the ES256 algorithm but some third-party tooling does not support ES256. If your service needs an alternative algorithm, we can sign your id_token JWT using the RS256 algorithm.
Identity verification supported
Set this to:
trueif your service uses GOV.UK One Login to prove your users’ identitiesfalseif your service only uses authentication
Is active
Whether the service is active or deactivated.
Is deprecated
Internal use only. Defaults to false.
JAR validation required
This is always false by default. You cannot change this value.
JWKS URL
The URL of your JWKS endpoint. Needed if using JWKS to provide your public keys.
Landing page URL
LandingPageUrl is only needed if you are making identity requests. Your service will redirect your users to this landing page after their in-person identity check.
There’s further guidance on helping your users after their in-person identity check.
Send an email to govuk-one-login@digital.cabinet-office.gov.uk if you need to configure this.
Max age enabled
Whether your service enforces a maximum authentication age. Only available to services not on the GOV.UK domain and those handling particularly sensitive data.
One Login service
This is always false. You cannot change this value.
Permit missing nonce
This option is only for authentication-only services and the default is false. You’ll use this if your service cannot send nonce as part of the authentication request, for example if your platform cannot configure it.
Where possible, use PKCE instead and set PKCEEnforced to true.
PKCE enforced
Specify whether your service must provide the parameters needed for Proof Key for Code Exchange (PKCE) protocol in the authorize and token requests.
You can read more about PKCE in RFC 7636.
Post-logout URLs
If you want to redirect your users after they log out, enter one or more URLs. These are where you redirect your users to after you have logged them out.
There’s further guidance on logging your user out of GOV.UK One Login.
Public key
To provide your public keys via a JWKS endpoint (strongly recommended for production) set the Key source in the GOV.UK One Login Admin Tool to the JWKs URL and provide the URL for your publicly available JWKS endpoint.
To provide a static public key, set the Key source to Static key and enter the contents of your public key Privacy Enhanced Mail (PEM) file (or whichever file was created when you created your key pair).
There’s further guidance on creating a key pair.
Public key source
The mechanism by which you’ll share the public key to check the signature of any signed JWTs sent in requests made to GOV.UK One Login.
Either STATIC or JWKS.
Only required if the TokenAuthenticationMethod is private_key_jwt or you’re sending a signed authorisation request (JAR).
Rate limit
If you want to test a rate limit you can get in touch with GOV.UK One Login to request it being set in integration.
Redirect URLs
Enter one or more of your service’s redirect URLs. These are the URLs GOV.UK One Login returns your user to after they complete their journey.
Scopes
Enter the scopes your service needs. You must include the openid scope.
You may choose one or more of the following:
emailphone
There’s further guidance on choosing which user attributes your service can request.
Sector identifier URI
There’s further guidance on choosing your sector identifier.
If your service has more than one redirect_uri, you must set the sector identifier in line with the OpenID Connect Core 1.0 specification.
Service type
The service type is always MANDATORY. You cannot change this value.
Smoke test
Internal use only. The value is either true or false.
Subject type
The subject type is always pairwise. You cannot change this value.
Test client
This is always false. You cannot change this value.
Test client email allow list
Internal use only. Defaults to empty.
Token authentication method
Specify the token authentication method your service is using. This will be private_key_jwt or client_secret_post.
There’s further guidance on using the correct token authentication method for your service.