Written by Technical Team | Last updated 23.07.2026 | 22 minute read
Integrating GOV.UK One Login with an established public service is rarely a straightforward matter of replacing one sign-in screen with another. The OpenID Connect exchange may be comparatively small, but it sits at the boundary of a much larger system containing user records, service permissions, historic applications, business relationships, delegated access, support processes and security controls. A technically correct login flow can still produce a failed migration if users cannot recover their existing records, staff cannot resolve account-linking problems or legacy assumptions about identity remain embedded in the service.
The central architectural challenge is that authentication, identity, service accounts and authorisation are related but different concepts. GOV.UK One Login can authenticate a person and, where required, support an identity-checking journey. The public service remains responsible for deciding which internal record that person may access, what they are allowed to do and how their relationship with the service changes over time. That distinction becomes particularly important when a legacy system has historically treated an email address, username, customer number or case reference as though it were the person’s permanent identity.
A successful GOV.UK One Login integration therefore needs three connected designs. It needs a secure OpenID Connect implementation, a durable account-linking model and a controlled migration strategy. These must be designed together. Treating them as separate workstreams creates gaps at precisely the points where security incidents, user confusion and operational failure are most likely to occur.
Legacy public services often combine several responsibilities inside a single account table. One database row may represent login credentials, contact details, a citizen record, service preferences and access permissions. In a newer architecture, these responsibilities would normally be separated. Authentication establishes that a user controls an identity credential. A service-specific principal represents that user inside the application. Domain records describe applications, licences, cases or transactions. Authorisation determines what the principal can see and do. Migrating to GOV.UK One Login exposes any places where the legacy service has blurred those boundaries.
Consider a service that uses an email address as its username and primary database key. It may appear natural to match the email address returned by GOV.UK One Login to the existing account and grant access immediately. That approach is attractive because it minimises visible migration steps, but it is not a durable identity design. Email addresses can change, be recycled, contain historical errors or be shared by members of a household. A person may also use different addresses for different government services. Email is useful as a candidate-matching attribute, but it should not be treated as conclusive proof that two accounts belong to the same person.
The same problem appears in services used by businesses, representatives and professional agents. GOV.UK One Login authenticates an individual; it does not, by itself, establish that the individual is currently a director, employee, solicitor, accountant, landlord, carer or authorised representative of an organisation. Organisational authority must remain a separate service capability. The internal model should be able to express that a person has one or more roles, that those roles can expire or be revoked and that access may depend on a mandate, invitation or approval held elsewhere.
The migration programme must consequently begin with domain modelling rather than protocol configuration. Teams should identify the difference between a login, a person, a customer account, an organisation, a case and a permission. They should document which identifiers are stable, which can change and which were never intended to be identifiers at all. This exercise often reveals hidden one-to-many relationships: one person with several legacy accounts, several people using one household account, an agent managing many clients or a business account accessed by multiple staff members.
This analysis determines what GOV.UK One Login should bind to. In most services, it should bind to a service-owned user principal rather than directly to a case, an email address or a domain record. The service principal becomes the durable internal identity. It can then be associated with the GOV.UK One Login subject identifier, legacy credentials, organisational roles and relevant domain records. This indirection may look like an additional layer, but it is what allows the service to survive changed email addresses, deleted and recreated external identities, account recovery and future changes in authentication technology.
GOV.UK One Login acts as an OpenID Connect provider, while the integrating public service acts as the relying party. The service redirects the user to an authorisation endpoint, receives an authorisation code through a registered callback, exchanges that code for tokens and retrieves the permitted user information. In a modern application, this is normally handled by a well-supported OpenID Connect library. In a legacy estate, however, it is often safer to introduce a dedicated identity adapter or authentication edge rather than embedding the entire protocol directly inside an ageing application.
The identity adapter can be implemented as part of a backend-for-frontend, an authentication gateway or a narrowly scoped service. Its responsibility is to understand GOV.UK One Login, validate the protocol exchange and convert the result into an internal session understood by the existing service. The legacy application does not need to process external identity tokens or know the details of key discovery, signed requests and token exchange. It receives a service-controlled session identifier or an internal token containing only the claims it needs.
This boundary reduces the attack surface inside the legacy application. GOV.UK One Login access tokens should not be passed through the estate as general-purpose bearer credentials. They are issued for a specific relying-party interaction and should be handled on the server side. After validating the response, the identity adapter should establish a local session tied to the service’s internal principal. Downstream systems can then continue to apply service-specific permissions without becoming coupled to the external identity provider.
A robust implementation should use the provider’s discovery metadata rather than hard-coding endpoint behaviour. The discovery document and signing keys should be cached in accordance with their cache instructions, while allowing the service to continue safely during short-lived retrieval failures. Cache design matters because fetching metadata or keys for every sign-in introduces unnecessary latency and creates an avoidable dependency on synchronous network availability. At the same time, caches need refresh logic that recognises a previously unseen key identifier and obtains the latest key set without accepting an unverified token.
The authorisation request should be bound to the user’s browser session using cryptographically random state. A nonce should bind the returned identity token to the original request. Proof Key for Code Exchange should protect the authorisation code from interception and substitution. Redirect addresses must be registered precisely, and callback handlers should reject unexpected parameters, reused codes and responses that cannot be matched to an active authentication transaction. Signed authorisation requests add integrity to the request parameters, while private-key client authentication avoids relying on a long-lived shared secret for the token exchange.
At a minimum, the relying party should verify:
The precise configuration must be treated as environment-specific. Development, integration, user acceptance and production environments should not share client identifiers, redirect addresses, key material or session secrets. Separate configurations reduce the risk that a test callback is accepted in production or that a lower-assurance environment can impersonate the live service. They also make key rotation and incident containment more manageable.
Key management deserves particular attention. The service should publish public keys through a resilient JSON Web Key Set endpoint and keep private keys in an appropriate secrets-management or key-management facility. Rotation should use overlapping validity: publish the new public key before signing with its private counterpart, continue publishing the old key while cached requests may still refer to it and remove the old key only after the overlap period has passed. The key identifier must be unique and observable so that failed validations can be diagnosed without exposing key material.
Once the OpenID Connect response has been validated, the service should use the subject identifier as an external binding value, not as its master customer key. The external identity record should normally contain the issuer as well as the subject because a subject is only meaningful within its issuer and sector. A suitable model might record the internal principal identifier, external issuer, external subject, link status, linking method, linking time, assurance evidence, last-seen time and relevant audit references. Database constraints should prevent one external identity from becoming actively linked to two internal principals unless the domain explicitly requires that relationship.
The sector identifier is an architectural decision rather than a minor registration field. GOV.UK One Login uses it when producing pairwise subject identifiers. Services that intentionally need to recognise the same person across several related applications may use a shared sector arrangement, while unrelated services can remain separated. Changing the sector identifier after users have begun linking can change the subjects received by the service, which can make previously linked users appear new. It should therefore be agreed before migration and managed with the same care as a database key strategy.
Authentication and identity checking should also be modelled as separate steps. Many services need only to authenticate a returning user for routine access, while higher-risk journeys may require stronger identity confidence. Separating the initial authentication request from any subsequent identity request allows the service to establish the user’s migration state first, measure where users abandon the journey and avoid forcing identity checking into interactions that do not require it. It also creates a cleaner place to apply step-up controls before sensitive actions such as changing payment details, disclosing protected records or granting delegated access.
Account linking is the point at which the service decides that an authenticated GOV.UK One Login user is entitled to control an existing internal principal. This is usually the highest-risk step in the migration. A false negative causes inconvenience because a genuine user cannot find their records. A false positive can expose personal data or allow an attacker to take over an established account. The linking design should therefore be based on evidence, transaction controls and recoverability rather than a single database lookup.
The first branch in the linking journey is simple. When the service receives a valid subject identifier, it checks its external identity mapping store. If an active link already exists, the corresponding internal principal can be loaded and the normal authorisation process can begin. This is the steady-state path for returning users and should become the dominant route once migration matures.
If no link exists, the user is either new to the service, an existing user who has not migrated, a returning user whose previous external identity has changed or someone attempting to access another person’s account. The service must distinguish these conditions without revealing whether a particular email address, customer number or case exists. Error messages and support journeys should avoid creating an account-enumeration service for attackers.
Email matching can be used to locate a possible legacy account, particularly when users have been advised to use the same email address during migration. It should initiate a verification journey rather than complete the link automatically. The service might ask the user to authenticate with their old credentials, enter a one-time code sent to the contact channel already held by the legacy service, provide an account reference and answer a carefully chosen knowledge check, or complete a higher-assurance service-specific verification step.
Legacy password verification can be useful during a limited transition period because it proves control of the previous account. It should take place through a dedicated, rate-limited endpoint and should never cause the old password to be copied into the new identity system. Once a successful link has been created, the legacy credential can be retired according to the migration policy. Services should also consider whether their historic password quality, reset processes and account-sharing practices make the old credential sufficiently trustworthy to serve as the only linking factor.
One-time codes can provide a clearer experience, but only when the service has confidence in the historic contact channel. Sending a code to the same address returned by GOV.UK One Login adds little evidence because the user has already demonstrated control of that address. A stronger pattern sends the code to a previously verified channel independently held by the legacy service. Even then, the service must account for stale telephone numbers, inaccessible organisational mailboxes and users whose contact details were entered by staff rather than by the user.
Knowledge-based checks should be used cautiously. Questions based on public, easily guessed or broadly shared information create the appearance of verification without much security. Better checks rely on information generated through the user’s previous interactions with the service, are not displayed elsewhere in the journey and allow sensible alternatives for users who cannot remember exact historic details. Failed checks must be rate-limited, monitored and designed so that support staff cannot be manipulated into bypassing them casually.
The binding operation itself should be atomic. After the additional evidence has been accepted, the service should create the external identity mapping, mark the migration state and invalidate the one-time linking transaction in a single database transaction or equivalent consistency boundary. A uniqueness constraint should stop simultaneous browser tabs or concurrent requests from linking the same external subject to different accounts. The operation should be idempotent so that a network retry returns the already-completed result rather than producing a duplicate relationship.
A useful account-linking record contains more than the two identifiers. It should explain how and why the link was established. Recording the linking method, assurance level, timestamp, service version, correlation identifier and relevant support or risk decision makes later investigation possible. The audit trail should avoid storing unnecessary authentication secrets or identity evidence, but it must be sufficient to answer questions such as who initiated a rebind, which verification path succeeded and whether a support agent intervened.
Email must not become a synchronisation key after linking. The email returned by GOV.UK One Login may be useful as a current contact attribute if the service has a legitimate need for it, but a change should not create a new service user or sever an existing link. The service may also hold a different correspondence address for domain reasons. Those two concepts should be labelled clearly in the data model and user interface: one is associated with signing in; the other may be where the service sends operational communications.
Account recovery is where the value of the internal principal becomes most apparent. A user may delete their GOV.UK One Login and later create another, producing a new subject identifier. The public service should not create a second customer history merely because the external identifier changed. It needs a controlled rebinding journey that proves entitlement to the original internal principal, records the previous external relationship and links the new subject. High-risk rebindings may require manual review or stronger evidence than first-time migration because they can be targeted by account-takeover attempts.
Duplicate legacy accounts require an explicit policy. Some can be merged safely; others may represent distinct legal capacities, such as a person acting privately and as an authorised professional. The service should not merge records merely because names and email addresses are similar. Where consolidation is appropriate, domain data, retention rules, open transactions, debts, permissions and audit history must be considered. In some cases, the correct result is one authenticated person with access to several separate service profiles rather than one merged account.
Shared accounts create another difficult case. A household may historically have used one email address and password, while a business portal may have issued a single login to an entire team. GOV.UK One Login is centred on an individual user, so migration should not recreate shared credentials behind a newer sign-in screen. The service needs to introduce individual principals, invitations, delegated access and role management. This may involve more operational change than the OIDC integration, but it improves accountability and allows access to be removed from one person without disrupting everybody else.
For business-facing services, the post-login journey should resolve organisational authority separately. The service may ask the authenticated person to select an organisation, accept an invitation, provide an enrolment code or complete a mandate process. Permissions should be granted to the relationship between the person and the organisation, not to the person’s email domain. Employment and professional authority change frequently, so this layer needs effective dates, revocation, audit and administrative controls.
A safe migration begins with an inventory of account populations and sign-in journeys. Teams should quantify active and dormant users, duplicate emails, shared accounts, accounts without usable contact details, privileged users, business representatives and users who depend on assisted digital support. They should also identify every route through which credentials are created, reset or used, including mobile applications, call-centre tools, administrative portals and forgotten batch interfaces. A migration plan based only on the main website will miss precisely the channels most likely to cause disruption.
Each internal principal should have an explicit migration state rather than relying on a nullable GOV.UK One Login subject column. Useful states may include:
A state model allows journeys, support procedures and reporting to be designed deliberately. It also avoids ambiguous conditions in which an account appears linked in one system but remains eligible for legacy login in another.
The first production phase should usually be a controlled cohort rather than a universal cutover. Internal users, test users and low-risk customer groups can expose issues with browser behaviour, callback routing, contact data and support scripts. Later cohorts can include more complex users, such as representatives and people with several service profiles. Feature flags should control which users see the new route and which linking mechanisms are available, allowing the team to pause expansion without reversing links that have already been established.
Dual running can reduce immediate disruption, but it must have a clear security model. Offering both sign-in routes indefinitely creates two recovery processes, two sets of credentials and a larger attack surface. During coexistence, the service must decide whether a successfully migrated user can still use legacy credentials, whether doing so triggers an alert and how the two sessions interact. A sensible pattern is to disable legacy sign-in for an account after a confirmed link, while maintaining a controlled recovery route for exceptional cases.
Migration communications should start before the technical cutover. Users need to know that the sign-in method is changing, what information they may need and whether using the same email address will simplify the process. The message should be repeated at useful points rather than buried in a long start page. It should also avoid implying that GOV.UK One Login and the service’s own account records are the same thing. Users should understand that they are changing how they sign in while retaining access to their existing service information.
The service should measure the migration as a funnel rather than simply counting successful logins. Useful measures include the proportion of journeys reaching the authorisation callback, token-exchange success, recognition of existing links, candidate legacy matches, successful verification, duplicate-account detection, support referrals, recovery completion and abandonment at each step. These figures should be segmented by browser, device type, account population and linking method. A high overall success rate can conceal serious exclusion within a smaller but important user group.
Operational teams need tools that expose migration state without exposing security-sensitive data. A support agent should be able to see whether a link exists, when it was created, which approved method established it and whether the account is blocked or under review. They should not be able to view tokens, private identity claims or authentication secrets. Actions such as unlinking, rebinding or overriding a failed match should require appropriate permissions, reason codes and auditable approval.
Rollback planning must recognise that migration changes durable identity relationships. Re-enabling the old login page does not undo links already created, merged profiles or disabled credentials. A realistic rollback strategy preserves completed bindings, stops new cohorts, routes affected users through a known recovery path and allows the team to revert application releases without corrupting migration state. Database changes should be backwards compatible during the transition, and destructive credential removal should occur only after the service has demonstrated stable operation and acceptable recovery performance.
The final cutover should remove obsolete authentication code, password-reset functions and credential stores rather than leaving them dormant. Unused login routes are still attack surfaces, and retained password hashes still carry breach risk. Decommissioning should include scheduled jobs, administrative bypasses, call-centre scripts, monitoring rules, old documentation and supplier integrations. The service should retain only the migration evidence and audit information required for legitimate operational, security and legal purposes.
Go-live is the point at which the integration becomes an operational dependency. Teams must monitor more than endpoint availability. They need visibility of discovery and key retrieval, authorisation redirects, callback validation, token exchange, user-information retrieval, local session creation, account-link lookups, logout processing and recovery journeys. A single aggregate availability measure cannot distinguish an identity-provider incident from a broken callback deployment or an internal database constraint.
Logs should use correlation identifiers that connect the browser journey, OpenID Connect transaction, account-linking operation and service session without recording tokens or unnecessary personal information. Dashboards should expose failure categories rather than only HTTP status codes. For example, an invalid state response suggests a different problem from an unknown signing key, duplicate subject mapping, expired linking transaction or rejected legacy verification. Alerts should be tied to user impact and security significance so that expected user cancellations do not obscure attacks or systemic failures.
Session design must recognise that the GOV.UK One Login session and the service session are separate. The service chooses its own idle and absolute timeouts according to risk, but it must provide a clear route to sign out of both contexts. This matters on shared devices, where closing a browser may not be equivalent to ending every authenticated session. The service should terminate its local session first and then complete the configured logout journey, using a protected post-logout return address and state value.
Back-channel logout notifications can improve consistency when a user signs out elsewhere. The receiving endpoint should validate the signed logout token, issuer, audience, time claims, event structure and subject. It should also reject replayed token identifiers and terminate every active local session associated with the relevant external subject. Because the call is server-to-server, the endpoint must be resilient, monitored and able to process repeated delivery safely without treating an idempotent retry as an error.
The threat model should be maintained after launch. Particular risks include link hijacking, callback replay, cross-site request forgery, session fixation, token leakage, insecure support overrides, account enumeration and fraudulent rebinding. Changes to user journeys, identity claims, sector identifiers, client configuration and linking rules should receive security review because seemingly small alterations can invalidate earlier assumptions. A new mobile application or business role, for example, may create an additional relying party or require a different relationship model.
Testing should operate at several levels. Unit tests can validate state handling, token claims and migration transitions. Contract tests can verify the service’s interpretation of provider metadata and user-information responses. A local simulator can exercise deterministic error conditions, unusual claims and identity outcomes. The integration environment is still necessary for end-to-end testing against the real service behaviour. Production smoke tests should be narrow, controlled and designed so that they do not create misleading customer records.
Failure testing is especially valuable. The team should verify what happens when the discovery endpoint is temporarily unavailable, a signing key rotates, the token endpoint times out after processing a request, the user refreshes the callback page, a linking request is submitted twice or the database becomes unavailable after successful authentication. These scenarios determine whether the service fails securely and recoverably. They are more representative of real operational risk than testing only the ideal sign-in path.
Architecture governance should preserve the identity boundary over time. Product teams will be tempted to place additional service data into authentication tokens, use email as a convenient join key or grant permissions directly from sign-in claims. Those shortcuts gradually recreate the coupling the migration was meant to remove. The service should keep authentication claims minimal, maintain its own principal and entitlement model and expose identity functionality through a well-defined internal contract.
The long-term measure of success is not simply that GOV.UK One Login appears on the start page. It is that the public service can change authentication mechanisms without losing its understanding of users, that people retain access to their records through predictable recovery journeys and that organisational permissions remain accurate as relationships change. It is also that support staff can diagnose problems, engineers can rotate keys and deploy safely, and security teams can reconstruct important identity events without collecting excessive personal data.
When these elements are designed together, GOV.UK One Login integration becomes an opportunity to correct long-standing weaknesses in a legacy service. The project can replace shared credentials with individual accountability, separate identity from authority, introduce durable service principals and establish a controlled authentication boundary. The OpenID Connect implementation is essential, but the deeper value lies in creating an identity architecture capable of supporting the next generation of secure, joined-up public services.
Is your team looking for help with GOV.UK One Login integration? Click the button below.
Get in touch