From fa7dbec646f01f3c9a5b7931323fc959b8453ed2 Mon Sep 17 00:00:00 2001 From: Michiel Kodde Date: Tue, 8 Aug 2023 12:30:45 +0200 Subject: [PATCH] Update CHANGELOG and SsoOn2Fa docs --- CHANGELOG.md | 6 ++++++ docs/SsoOn2Fa.md | 24 +++++++++++++++++++++++- 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c6177023..6bc8958c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## 4.2.0 +Add single sign-on on second factor tokens feature. + +- For additional details see `docs/SsoOn2Fa.md` +- And https://www.pivotaltracker.com/epic/show/5024251 + ## 4.1.3 - Fix ADFS error handling not invoked for errors from a GSSP #287 diff --git a/docs/SsoOn2Fa.md b/docs/SsoOn2Fa.md index 41d03814..65dd2943 100644 --- a/docs/SsoOn2Fa.md +++ b/docs/SsoOn2Fa.md @@ -1,8 +1,30 @@ # SSO on Second Factor Authentications +When the feature is enabled for the institution, when using a MFA token we create a cookie containing information about the token that was used during MFA. +On every successive authentication presented to the Stepup-Gateway we check if the cookie contains a valid authentication for the specified LoA. +If the cookie meets the requirements, the authenticating user is not asked for the second factor authentication. +When the service requires MFA, this can still be forced regardless of the SSO cookie, by adding the ForceAuthn attribute on the AuthnRequest element. + +## The cookie +The cookie contains several values, used to ascertain if SSO can be given. These values are: + +| __Parameter name__ | __Description__ | +|----------------------------------|--------------------------------------------| +| `Second Factor Identifier` | The identifier of the second factor token | +| `Identifier` | IdentityId associated to the SecondFactor | +| `LoA` | The LoA of the second factor | +| `Timestamp` | The timestamp taken during authentication. | + +The cookie is used to verify the SSO is issued to the correct identity (user). And to check if the LoA requirement is satisfied by the SSO cookie. The timestamp is kept mainly for audit reasons. + +The cookie value contains sensitive data, and its contents are authenticated and encrypted for that reason. We use the Paragonie Halite library for this. Halite uses XSalsa20 for encryption and BLAKE2b for message Authentication (MAC). + +If your encryption requirements differ from ours, you can simply provide a different encryption method by implementing a different `Surfnet\StepupGateway\GatewayBundle\Sso2fa\Crypto\CryptoHelperInterface` + +See [CookieValue](https://github.com/OpenConext/Stepup-Gateway/blob/3c3149b0e68daa1abcdf9a8e6009667d470c8d2d/src/Surfnet/StepupGateway/GatewayBundle/Sso2fa/ValueObject/CookieValue.php) for details ## Configuration options When using SSO on second factor authentications (SSO on 2FA), you are allowed to configure three configuration -parameters. The configuration options are configured in `config/legacy/parameters.yanml` +parameters. The configuration options are configured in `config/legacy/parameters.yaml` | __Parameter name__ | __Description__ | __Data type__ | |-----------------------|----------------------------------------------------------------------------------------|--------------------------------------------------------|