account-api: One Login to GOV.UK pipeline
One Login is an OpenID Connect (OIDC) provider, which GOV.UK accounts are based on. Currently the only thing that a GOV.UK account handles is email alert subscriptions. Subscriptions are handled in two ways, one that requires a GOV.UK account, one that does not. (As of time of writing, there are 2.5 million subscribers using the old no-account method, 211,000 using the new account-based method).
So a user who has subscribed to email alerts will create records in 3 places if an account is required:
- A One Login account record in One Login
- An account record in account-api
- A subscriber record in email-alert-api
…but only one (a subscriber record in email-alert-api) if an account is not required (this is the magic-email path)
Therefore not all Subscriber records in email-alert-api will have a corresponding account record in account-api, but currently all account-api records have a corresponding subscriber record in email-alert-api.
How Email Alert records are created
There are a series of paths in email-alert-frontend which end up with an email subscription being made. The exact path depends on the component used for signup, and how that component is configured.
Single Page Notification Button Component
This component is the more complicated, and renders as a box with a bell icon and text inside. It’s progressively enhanced with the ability to query whether the user already has a subscription (in which case it allows them to cancel it).
If the user is logged in, this component calls the account api endpoint /api/personalisation/check-email-subscription from the browser, passing it the base path of the current page. If the logged-in user already has a subscription to that page, it will alter the action of the button to unsubscribe.
The behaviour of the button when pressed depends on the skip_account parameter passed to the component. If true, the button acts to create a subscription by POSTing to the email-alert-frontend endpoint /email-signup with the details of the subscription to be created in the request body. This causes a magic-email subscription to be created (ie one with no account-api record)
If skip_account is false, though, the button POSTs to the email-alert frontend endpoint /email/subscriptions/single-page/new . This endpoint requires the user to be logged in with a One Login account. If they are not logged in, it will redirect them to a login/create account page (after which they’ll be directed back). If logged in, it calls the email-alert-api methods “authenticate_subscriber_by_govuk_account” and “get_subscriptions” to get the existing subscriptions for that account holder for that page, then toggles that subscription (if it doesn’t exist, it will make one. If it already exists, it will end it).
Subscription Links Gem Component
This component is a simple link that creates a subscription with a GET to /email-signup passing the link as a query parameter. This causes a magic-email subscription to be created (ie one with no account-api record)
Application-specified Subscription Links
These links aren’t in a component, and are generated by Collections and Finder Frontend. They GET the email-alert-frontend endpoint /email/subscriptions/new, which again requires the user to be logged in with a One Login account, and will redirect them to login/create an account if they do not already have one. It then calls the email-alert-api methods “link_subscriber_to_govuk_account” and “subscribe” to create the subscription. This is not a toggle, as with the single page notification button - it will not unsubscribe an existing subscription.
How Account records are created
When one of the email alert paths above requires an account but doesn’t find it, it redirects the user to the One Login endpoint “https://signin.account.gov.uk/sign-in-or-create”. The One Login account is logged into or created at that point, and then the user is redirected back to the /callback endpoint on account-api that creates the account-api record and then redirects to the subscription path with the user already logged in.
How Email Alert / Account records are updated
When a user is logged into their One Login account (at home.account.gov.uk/your-services), they can see a list of services attached to that account. If one of them is GOV.UK email subscriptions, there is a link to https://www.gov.uk/email/manage?from=your-services, which is the email management page on email-alert-frontend. This is a simple link, but the query parameter tells email-alert-frontend that the user is already logged in.
Moving to the security tab, the user gets the option to change their email address, their password, and to delete their account.
- Email address changes should affect Account API / Email Alerts (they should change where the email alerts go to)
- Password changes should not affect GOV.UK (as an OIDC relying party, we shouldn't be privy to password information from the provider)
- Deleting the account should affect Account API / Email Alerts (they should remove both the account and the subscriber record, and any subscriptions attached to the subscriber)
Email Address Changes:
When the user changes the email address in One Login a direct call is made to the account api PUT /api/oidc_users, which causes the user to be looked up by the OneLogin subject_identifier field (or created, if it doesn’t exist). Then the email and verified email fields are updated (these appear to be the only fields that can be updated by this call). Problems can occur if the subject_identifier for a user has changed in One Login - then we’ll try to create a new account api record with the new subject_identifier, but it will fail to create because the email field has to be unique. Emails also have to be unique in One Login, so theoretically this shouldn’t happen, but if a user is deleted in One Login but not in Account API, it can.
Once the account API record has been changed, a call is made from account API to email alert API to update the attached email alert api subscriber record (if one exists).
One Login Account Deletions:
When an account is deleted (either by user or support agent) in One Login, a pub/sub message is created, then picked up by a service which makes the call to the account api DELETE /api/oidc_users/. This causes the user to be looked up by the OneLogin subject_identifier. If it exists, a call is made to email alert api to unsubscribe the subscriber record (making it eligible for historic account deletion). After that, the Account API account record is destroyed.
If the service call to Account API fails, the message goes into a Dead Letter Queue, which causes the One Login team to get an alert by email (they then go and manually investigate the problem). If the call between Account API and Email Alert API fails, we are notified by Sentry.