tech documentation updates

DFE-Digital · Dec 18, 2023 · 20bd33e · 20bd33e
1 parent f6ec230
commit 20bd33e
Show file tree

Hide file tree

Showing 4 changed files with 26 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -1,9 +1,10 @@
 # teaching-record-system
 
 Provides an API over the Database of Qualified Teachers (DQT). Provides the core Teaching record and will eventually replace the Database of Qualified Teachers (DQT).
-[trs containers diagram](docs/c4-diagrams-as-code/trs-containers.png)
-
+[trs containers diagram](docs/c4-diagrams-as-code/trs-containers.png). The "To Be" Teacher Pensions and EWC (Teaching Council) integration is shown [here](docs/c4-diagrams-as-code/trs-data-integration.png).
 
+## Authorising Access using GOV.UK One Login
+All DfE services will adopt the standard GOV.UK One-Login service to provide standard access to citizen facing services. However, for Teacher Services digital services, it is sometime necessary to implement further authorisation to access a teaching record (e.g. for a teacher to view certificates). TRS will provide this authorisation seamlessly (from a user POV) by handling the redirection between calling service --> GOV.UK OneLogin sign in screen -->TRS (to check access) and back to the calling service. More detail can be found [here](docs/trs-gov.one-login-flow.md).
 ## Calling the API
 
 The API is versioned and each endpoint is prefixed with the version number e.g. `/v2/`. You can view the API specifications for each version by visiting `/swagger` (see [Environments](#environments) below for the base addresses).

diff --git a/docs/c4-diagrams-as-code/trs-containers.png b/docs/c4-diagrams-as-code/trs-containers.png
diff --git a/docs/c4-diagrams-as-code/trs-data-integration.png b/docs/c4-diagrams-as-code/trs-data-integration.png
diff --git a/docs/trs-gov.one-login-flow.md b/docs/trs-gov.one-login-flow.md
@@ -0,0 +1,23 @@
+# High level flow of signing in to a service that requires authorisation to the teaching record via GOV.UK One Login
+
+The `start` represents the point at which a user visits a service domain for example [Access Your Teaching Qualifications](https://access-your-teaching-qualifications.education.gov.uk/qualifications/start).
+They would be re-directed to [GOV.UK One Login](https://www.sign-in.service.gov.uk/) to sign in. The Teaching Record System will handle the OAUTH flow between GOV.UK One Login and the calling service, as part of this flow it will provide authorisation against the teaching record. Allowing the calling service to grant access depending on finding a match and passing any other access rules needed to access the teaching record data.
+
+```mermaid
+  flowchart TD
+  Start[Start] --> OneLogin[Sign in with One Login]
+  OneLogin --> Verified{Identity verified?}
+  Verified -->|Yes| TrnKnown{TRN known for user?}
+  TrnKnown -->|Yes| Done
+  TrnKnown -->|No| Nino[Ask for NINO & lookup record]
+  Nino --> FoundAfterNino{Teaching record found?}
+  FoundAfterNino -->|Yes| RecordTrn[Record TRN for user]
+  RecordTrn --> Done
+  FoundAfterNino -->|No| Trn[Ask for TRN & lookup record]
+  Trn --> FoundAfterTrn{Teaching record found?}
+  FoundAfterTrn -->|Yes| RecordTrn
+  FoundAfterTrn -->|No| LookupFailed[Support ticket & error page?]
+  Verified -->|No| VerificationFailed[Error page?]
+  Done[Done: redirect to calling service]
+```
+