Document Gov.uk One Login Jobseekers integration

documentation/govuk-one-login.md

@@ -0,0 +1,53 @@
+# Jobseekers Authentication
+
+Jobseekers authenticate via the [GOV.UK One Login](https://www.sign-in.service.gov.uk/) service.
+
+Different environments talk to different GOV.UK One Login environments:
+
+- Local development -> Integration GOV.UK One Login
+- QA -> Integration GOV.UK One Login
+- Staging -> Integration GOV.UK One Login
+- Production -> Production Integration GOV.UK One Login
+
+- Review Apps:
+  Due to the ephemereal nature of these environments, they cannot be automatically configured to connect with GOV.UK One Login.
+  They use a magic link sent via email to authenticate.
+
+
+## GOV.UK One Login flow
+
+For extensive information,check the GOV.UK One Login [tech documentation](https://tech-docs.account.gov.uk/)
+
+The basic flow is as follows:
+
+1. When a jobseeker needs to sign-in/sign-up, gets sent to a Teaching Vacancies page informing them they're about to be redirected to GOV.UK One Login.
+2. After confirmation, they get redirected to the GOV.UK One Login service.
+3. On GOV.UK One Login the jobseeker either register a new account or sign-in with their existing One Login account.
+4. After a successfull sign-in/sign-up, they get redirected back to Teaching Vacancies.
+5. Teaching Vacancies matches/create the internal Jobseeker associated with the GOV.UK One Login account, and signs-in the user session.
+
+
+The detailed flow of requests/responses between Teaching Vacancies and GOV.UK One Login can be found in the [tech documentation](https://tech-docs.account.gov.uk/how-gov-uk-one-login-works/#understand-the-flow-gov-uk-one-login-uses)
+
+## Implementation in Teaching Vacancies
+
+The Jobseeker session is still managed by Devise gem.
+
+Teaching Vacancies configures OneLogin as an Omniauth provider through the [Devise Omniauth configuration](../config/initializers/omniauth.rb).
+
+There are a few paths in our service related with GovUK One Login:
+- `/jobseekers/sign-in` --> Bridge page in our service that, upon confirmation, sends the non-signed jobseeker to sign through GOV.UK One Login.
+- `/jobseekers/auth/govuk_one_login/callback` --> GOV.UK One Login redirects jobseekers back to this path after signing-up/in through their service. All the heavy lifting in our side is done here.
+- `/jobseekers/sign_out` --> Signs the jobseeker out from our service. GOV.UK One Login redirects jobseekers back to this path after signing users out in their service.
+
+
+## GOV.UK One Login configuration
+
+### Set environment variables
+
+```
+GOVUK_ONE_LOGIN_CLIENT_ID=
+GOVUK_ONE_LOGIN_BASE_URL=
+```
+
+## Account transfer