Update CHANGELOG and SsoOn2Fa docs

OpenConext · Aug 8, 2023 · fa7dbec · fa7dbec
1 parent 4e8c9b7
commit fa7dbec
Show file tree

Hide file tree

Showing 2 changed files with 29 additions and 1 deletion.
diff --git 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
@@ -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__                                          |
 |-----------------------|----------------------------------------------------------------------------------------|--------------------------------------------------------|