From a17c3eb644a049e29bd7c31f63f44197db93f511 Mon Sep 17 00:00:00 2001 From: Alistair Davidson Date: Mon, 11 Aug 2025 08:17:52 +0100 Subject: [PATCH 1/4] Add docs for commissioner reporting authentication --- ...h-level-auth-flow-with-mavis-and-CIS2.puml | 37 ++++++++++ ...gh-level-auth-flow-with-reporting-app.puml | 67 +++++++++++++++++++ .../user-logs-in-to-mavis-with-local-pwd.puml | 33 +++++++++ .../user-visits-the-reporting-app.puml | 49 ++++++++++++++ docs/reporting-component-authentication.adoc | 47 +++++++++++++ 5 files changed, 233 insertions(+) create mode 100644 docs/diagrams/reporting_auth/high-level-auth-flow-with-mavis-and-CIS2.puml create mode 100644 docs/diagrams/reporting_auth/high-level-auth-flow-with-reporting-app.puml create mode 100644 docs/diagrams/reporting_auth/user-logs-in-to-mavis-with-local-pwd.puml create mode 100644 docs/diagrams/reporting_auth/user-visits-the-reporting-app.puml create mode 100644 docs/reporting-component-authentication.adoc diff --git a/docs/diagrams/reporting_auth/high-level-auth-flow-with-mavis-and-CIS2.puml b/docs/diagrams/reporting_auth/high-level-auth-flow-with-mavis-and-CIS2.puml new file mode 100644 index 0000000000..547d985e69 --- /dev/null +++ b/docs/diagrams/reporting_auth/high-level-auth-flow-with-mavis-and-CIS2.puml @@ -0,0 +1,37 @@ +@startuml +title "High-level Authentication Flow with CIS2 (OIDC)" +|User| +|CIS2| +|Mavis| +|Mavis Reporting| +|User| +start +:click 'Start' button; +|Mavis| +:redirect to CIS2; +|CIS2| +:respond with login form; +|User| +:provide credentials; +->credentials; +|CIS2| +:verify credentials; +:create user session; +:generate authorization code; +->redirect back with authorization code; +|User| +:request redirect URI; +|Mavis| +:verify authorization code; +->client_id & authorization code; +|CIS2| +:respond with access token; +|Mavis| +:use access token to get user info; +|CIS2| +->user info; +|Mavis| +:store user info in session; +:store access token against user in DB; +stop +@enduml \ No newline at end of file diff --git a/docs/diagrams/reporting_auth/high-level-auth-flow-with-reporting-app.puml b/docs/diagrams/reporting_auth/high-level-auth-flow-with-reporting-app.puml new file mode 100644 index 0000000000..de1eec09fd --- /dev/null +++ b/docs/diagrams/reporting_auth/high-level-auth-flow-with-reporting-app.puml @@ -0,0 +1,67 @@ +@startuml +title "High-level Authentication Flow with Reporting Component (OAuth 2.0)" +|User| +|CIS2| +|Mavis| +|Mavis Reporting| +|User| +start +:Visit reporting app; +|Mavis Reporting| +:redirect to Mavis; +|Mavis| +:redirect to CIS2; +|CIS2| +:respond with login form; +|User| +:provide credentials; +->credentials; +|CIS2| +:verify credentials; +:create user session; +:generate authorization code; +->redirect back with authorization code; +|User| +:request redirect URI; +->authorization code; +|Mavis| +:verify authorization code; +->client_id & authorization code; +|CIS2| +:verify authorization code; +:respond with access token; +->access token; +|Mavis| +:create user session; +:store access token against user in DB; +:generate reporting app authorization code for user; +:redirect back to reporting app with authorization code; +|User| +:request redirect_uri; +->authorization code; +|Mavis Reporting| +:verify authorization code; +->client_id & authorization code; +|Mavis| +:verify authorization code; +:generate JWT with user & role info & reporting_api_session_token; +:sign JWT with client_secret; +:store JWT against user in DB; +:respond with JWT; +->JWT; +|Mavis Reporting| +:decode JWT & verify signature; +:store user & role info & reporting_api_session_token in session; +:use JWT to authenticate Mavis API requests; +->API request, Authorization: "Bearer ""; +|Mavis| +:decode JWT & verify signature; +:verify reporting_api_session_token is valid for user; +:use user to restrict queries; +:return data as JSON; +|Mavis Reporting| +:render HTML; +->respond with HTML, status 200; +|User| +stop +@enduml \ No newline at end of file diff --git a/docs/diagrams/reporting_auth/user-logs-in-to-mavis-with-local-pwd.puml b/docs/diagrams/reporting_auth/user-logs-in-to-mavis-with-local-pwd.puml new file mode 100644 index 0000000000..bb37d85f44 --- /dev/null +++ b/docs/diagrams/reporting_auth/user-logs-in-to-mavis-with-local-pwd.puml @@ -0,0 +1,33 @@ +@startuml +title "User logs in to Mavis with email & password" +|User| +|CIS2| +|Mavis| +|Mavis Reporting| +|User| +start +:click 'Start' button; +|Mavis| +if (CIS2 login enabled?) is (N) then + repeat + :respond with login form; + |User| + :provide credentials; + |Mavis| + repeat while (valid credentials?) is (N) not (Y) + :respond with choose role page; + |User| + :choose role; + |Mavis| + :store user & role info in session as 'cis2_info'; + :store reporting_api_session_token in DB; + :respond with cookie and redirect; + |User| + :access redirected URL; + stop +else + |Mavis| + :(see other process); + stop +end +@enduml \ No newline at end of file diff --git a/docs/diagrams/reporting_auth/user-visits-the-reporting-app.puml b/docs/diagrams/reporting_auth/user-visits-the-reporting-app.puml new file mode 100644 index 0000000000..7866a6d58f --- /dev/null +++ b/docs/diagrams/reporting_auth/user-visits-the-reporting-app.puml @@ -0,0 +1,49 @@ +@startuml +title "User visits the Reporting app" +|User| +|CIS2| +|Mavis| +|Mavis Reporting| +|User| +start +->GET /reporting/...; +|Mavis Reporting| +if (has JWT in cookie?) is (Y) then + :API call with JWT as \n Authorization header; + |Mavis| + if (JWT is valid?) is (Y) then + :get the user with the JWT's session token; + if (user with that session token exists?) then + :use that user to filter returned data; + :respond with 200 & data; + |Mavis Reporting| + else (N) + |Mavis| + :respond with 401; + |Mavis Reporting| + endif + else (N) + |Mavis| + :respond with 401; + |Mavis Reporting| + endif + if (response status is 200?) is (Y) then + :render html; + :respond with 200 & html; + else (N) + |Mavis Reporting| + :clear user session; + :redirect to Mavis start \nwith redirect_uri param; + endif +else (N) + |Mavis Reporting| + :redirect to Mavis start \nwith redirect_uri param; + |User| +endif +|Mavis Reporting| +->response; +|User| +:process response; +stop + +@enduml \ No newline at end of file diff --git a/docs/reporting-component-authentication.adoc b/docs/reporting-component-authentication.adoc new file mode 100644 index 0000000000..8018c68d37 --- /dev/null +++ b/docs/reporting-component-authentication.adoc @@ -0,0 +1,47 @@ + +:imagesdir: images +:source-highlighter: pygments + +ifdef::env-github[] +// If on GitHub, define attributes so we can find our diagram files and render +// them. + +// The branch will be used to find the correct diagrams to render below. +// When PRing changes to the diagrams you can change this attributes +// temporarily to the name of the branch you're working on. But don't forget +// to change it back to main before merging!! +:github-branch: spike/MAV-1406-auth-sharing-with-reporting + +:github-repo: nhsuk/record-childrens-vaccinations + +// URL for PlantUML Proxy. Using an attribute mainly because it's just tidier. +:plantuml-proxy-url: http://www.plantuml.com/plantuml/proxy?cache=no&src= + +// Full path prefix we'll use for diagrams below. +:diagram-path-url: {plantuml-proxy-url}https://raw.githubusercontent.com/{github-repo}/{github-branch}/docs +endif::[] + + += Reporting Component Authentication + +The main Mavis application uses CIS2 to authenticate users, exchanging authorization codes & obtaining an access token for the user session using OpenID Connect (OIDC) - see the link:https://digital.nhs.uk/services/care-identity-service/applications-and-services/cis2-authentication/guidance-for-developers/openid-connect-overview[CIS2 documentation] for details. + +At a high-level, that flow works like this - (implementing link:../adr/00012-auth-pattern-for-commissioner-reporting-app.md[ADR00012]): + +ifdef::env-github[] +image::{diagram-path-url}/diagrams/reporting_auth/high-level-auth-flow-with-mavis-and-CIS2.puml[Mavis/CIS2 authentication flow diagram] +endif::[] + +Extending this process to include the reporting component is done in a very similar way, using link:https://datatracker.ietf.org/doc/html/rfc6749#section-4.1[OAuth 2.0 Authorization Code Grant] (upon which OIDC is based) + +ifdef::env-github[] +image::{diagram-path-url}/diagrams/reporting_auth/high-level-auth-flow-with-reporting-app.puml[Mavis Reporting/Mavis/CIS2 authentication diagram] +endif::[] + + +The reporting app can then use the JWT to authenticate future API requests to Mavis as follows: + + +ifdef::env-github[] +image::{diagram-path-url}/diagrams/reporting_auth/user-visits-the-reporting-app.puml[User visiting the reporting app diagram] +endif::[] \ No newline at end of file From 726737083b5863ded893cd8692ec54e792745c7e Mon Sep 17 00:00:00 2001 From: Alistair Davidson Date: Mon, 11 Aug 2025 09:31:44 +0100 Subject: [PATCH 2/4] Change github-branch in the reporting component auth adoc --- docs/reporting-component-authentication.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reporting-component-authentication.adoc b/docs/reporting-component-authentication.adoc index 8018c68d37..6590cf6aea 100644 --- a/docs/reporting-component-authentication.adoc +++ b/docs/reporting-component-authentication.adoc @@ -10,7 +10,7 @@ ifdef::env-github[] // When PRing changes to the diagrams you can change this attributes // temporarily to the name of the branch you're working on. But don't forget // to change it back to main before merging!! -:github-branch: spike/MAV-1406-auth-sharing-with-reporting +:github-branch: main :github-repo: nhsuk/record-childrens-vaccinations From 5874df0b074c3b6e8c2db64e08809a67a98cffd2 Mon Sep 17 00:00:00 2001 From: Alistair Davidson Date: Mon, 11 Aug 2025 12:53:17 +0100 Subject: [PATCH 3/4] remove the outdataed `:github-repo:` line from authentication adoc --- docs/reporting-component-authentication.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/reporting-component-authentication.adoc b/docs/reporting-component-authentication.adoc index 6590cf6aea..3812fe3d12 100644 --- a/docs/reporting-component-authentication.adoc +++ b/docs/reporting-component-authentication.adoc @@ -12,7 +12,6 @@ ifdef::env-github[] // to change it back to main before merging!! :github-branch: main -:github-repo: nhsuk/record-childrens-vaccinations // URL for PlantUML Proxy. Using an attribute mainly because it's just tidier. :plantuml-proxy-url: http://www.plantuml.com/plantuml/proxy?cache=no&src= From 5c1d393151422f20b5b1ddcabe89550f3229fe28 Mon Sep 17 00:00:00 2001 From: Alistair Davidson Date: Mon, 11 Aug 2025 12:59:47 +0100 Subject: [PATCH 4/4] put correct repo ref in, as it now shows a missing image --- docs/reporting-component-authentication.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/reporting-component-authentication.adoc b/docs/reporting-component-authentication.adoc index 3812fe3d12..c98cc2d82d 100644 --- a/docs/reporting-component-authentication.adoc +++ b/docs/reporting-component-authentication.adoc @@ -12,6 +12,7 @@ ifdef::env-github[] // to change it back to main before merging!! :github-branch: main +:github-repo: nhsuk/manage-vaccinations-in-schools // URL for PlantUML Proxy. Using an attribute mainly because it's just tidier. :plantuml-proxy-url: http://www.plantuml.com/plantuml/proxy?cache=no&src=