From 4c032cfc345904775fe6fc9467e33cf86f6cbdec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sindre=20M=C3=B8gster=20Braaten?= Date: Thu, 11 Mar 2021 10:35:05 +0100 Subject: [PATCH] Added documentation for the verification solution --- README.md | 2 +- verification-solution.md | 94 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 95 insertions(+), 1 deletion(-) create mode 100644 verification-solution.md diff --git a/README.md b/README.md index 8b31d6d..75d4a12 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ The solution consists of a number of new components created specifically for thi - Smittestopp Backend - Smittestopp App -- Smittestopp Verification +- [Smittestopp Verification](verification-solution.md) In addition, the solution reuses a number of existing components/solutions diff --git a/verification-solution.md b/verification-solution.md new file mode 100644 index 0000000..13c57fa --- /dev/null +++ b/verification-solution.md @@ -0,0 +1,94 @@ +# Verification solution + +## OpenID Connect and OAuth 2.0 + +The verification solution uses [Identity server](https://identityserver4.readthedocs.io/en/latest/) to implement the OpenID connect and OAuth 2.0 specifications. + +## Configured clients + +The only client that is intended to use the verification solution is the Smittestopp exposure notification app. +As a result, this client is configured through [appsettings.json](https://github.com/folkehelseinstituttet/Fhi.Smittestopp.Verification/blob/7521b71d84593b09a4f4e4c28dfcb1ee790dfca0/Fhi.Smittestopp.Verification.Server/appsettings.json#L21) with the client id `smittestopp`. +For the dev-, test- and QA-environments, a client with id `test-spa-client` is also included to faciliate easier isolated testing of the verification solution. + +## Verified access to notify contacts + +To be able to notify you contacts through the Smittestopp app, you must fullfill the following criterias +- Have a positive COVID-19 test within the last 14 days +- Be at least 16 years old +- Have NOT already performed the verification flow 3 times the last 24 hours + - These values are for production, and may vary for other environments + +The first two criterias are handled internally by the MSIS-lookup, while the latter is tracked by the verification solution itself (through the VerificationRecords DB-table which stores a hash of the ID-porten pseudonym of the user logged in for 24 hours). + +If you fullfill all these criterias, the JWT access token issued to you will contain the claim `role=upload-approved`. + +To avoid replay attacks, one can store the `jti`-claim for the valid period of the claim (given by the `exp`-claim). + +## Compatibility with Smitte|Stop (DK) + +Since the norwegian Smittestopp is based on the danish Smitte|Stop, the decision was made to use JWTs compatible with the existing DK-implementation. + +To request a DK-compatible JWT access token from the Smittestopp Verification, one should request the scope `smittestop`. + +A user which *does not have* a positive COVID-19 test within the last 14 days, or *is below* 16 years of age, will then have the following claims + +``` +covid19_status=negativ +``` +If there is an unexpected error during the processing of a token request, the following claim will be given provided, +which then should trigger a message to the user in app informing them of the error, and asking them to try again later. +``` +covid19_status=ukend +``` +A user which *does have* a positive COVID-19 test within the last 14 days, *is at least* 16 years old, +and has not performed the verification flow more than the allowed number of times will have the following claims. +``` +covid19_status=positiv +covid19_smitte_start=yyyy-MM-dd // sampling date of COVID-19 test +covid19_blokeret=false +``` +If a user satisfies the requirements for age and positive test, but has been blocked due to too many attempts at performing the verification flow, +the blocking claim changes value, and some additional claims are added informing the app of the duration and number of attempts configured for the blocking limit. +``` +covid19_blokeret=true +covid19_limit_duration=24 +covid19_limit_count=3 +``` +Thus, to authorize a user to upload their diagnosis keys using only the DK-compatible claims, +one must require that the `covid19_status` claim is present with a value `positiv` and that the `covid19_blokeret` claim is present with a value `false`. + +## Anonymous tokens + +When anonymous tokens are enabled, an additional claim is introduced in the JWT access token: `covid19_anonymous_token=v1_enabled` + +This claims is intended to communicate to the client (Smittestopp app), that anonymous tokens are available, +and should therefore exchange the JWT for an anonymous token when uploading diagnosis keys. +[This is described further here](anonymous-tokens.md) + +## Internal dependencies + +The verification solution has the following internal dependencies +- [ID-porten](https://www.digdir.no/digitale-felleslosninger/id-porten/864): External identity provider used to authenticate users and retrieve national identifier to perform the verification for +- [MSIS](https://www.fhi.no/en/hn/health-registries/msis/): Used to check that both the infection status requirement and the age requirement is fullfilled for a provided national identifier + +## Environments + +- Azure-dev + - Url: https://dev-smittestopp-verification.azurewebsites.net/.well-known/openid-configuration/ + - ID-porten [ver1](https://docs.digdir.no/oidc_func_wellknown.html) environment ([test users](https://docs.digdir.no/idporten_testbrukere.html)) + - [Fixed test cases for MSIS check and block limit](https://github.com/folkehelseinstituttet/Fhi.Smittestopp.Verification/blob/7521b71d84593b09a4f4e4c28dfcb1ee790dfca0/Fhi.Smittestopp.Verification.Server/appsettings.AzDev.json#L71) +- NHN-test + - Url: https://test-vl-op.ss2np.fhi.no/.well-known/openid-configuration/ + - ID-porten [ver1](https://docs.digdir.no/oidc_func_wellknown.html) environment ([test users](https://docs.digdir.no/idporten_testbrukere.html)) + - MSIS-check against test data + - Block limit increased, block duration decreased +- NHN-qa + - Url: https://qa-vl-op.ss2np.fhi.no/.well-known/openid-configuration/ + - ID-porten [ver1](https://docs.digdir.no/oidc_func_wellknown.html) environment ([test users](https://docs.digdir.no/idporten_testbrukere.html)) + - MSIS-check against test data + - Block limit and duration as prod +- NHN-prod + - Url: https://vl-op.ss2.fhi.no/.well-known/openid-configuration/ + - ID-porten [production](https://docs.digdir.no/oidc_func_wellknown.html) environment + - MSIS-check against production data + - Block limit max 3 attempts per 24 hours \ No newline at end of file