@greensecurity/javascript-sdk 0.45.0-beta.16 → 0.45.0-beta.17

package/src/sdk/users.ts

@@ -148,6 +148,43 @@ export class Users extends ClientSDK {
    * 3. Site redirects to your selected `return_url`
    * 4. The `user_token` will be appended as a query string parameter to your `return_url` - you must parse this token and store it
    * 5. Fetch the user object from `/users/me` using the token
+   *
+   * ## Finishing a "Login with Green Security" flow
+   *
+   * Green Security is also a SAML2 **identity provider**. When a third-party service provider sends a user to
+   * `/saml/idp/sso` to sign in with their Green Security account, the user lands on a Green Security login screen
+   * carrying an `sso_state` query string parameter. That parameter is a signed, five-minute record of which service
+   * provider is waiting, where its assertion consumer service lives, and what `RelayState` it sent.
+   *
+   * Authentication itself is unchanged - the user may still need a password, an MFA code, a magic link or a round trip
+   * to their own SAML IdP, and every `requires` value above applies as normal. The only difference is that you must
+   * echo `sso_state` back on **every** call in the sequence, unchanged, including the follow-up that carries the
+   * `mfa_code`.
+   *
+   * Each `202` response carries the verified blob back to you in its own top-level `sso_state` field. Send back the
+   * value from the response you just received rather than the one you started with. The two are normally the same
+   * string, but re-sending your original copy is how a blob the server has already rejected gets resent, and it forces
+   * you to hold login state you would otherwise not need.
+   *
+   * 1. Read `sso_state` from the query string of the login screen you were sent to
+   * 2. Run the login exactly as you would otherwise, adding `sso_state` to each request body and taking the value for
+   *    the next request from the previous `202` response
+   * 3. On the `200` response, read `sso.continue_url`
+   * 4. Navigate the browser to `sso.continue_url` - a full page navigation, not a background fetch. It answers with a
+   *    self-submitting form that delivers the signed `SAMLResponse` and the original `RelayState` to the service
+   *    provider
+   * 5. The service provider validates the assertion and the user is signed in on their side
+   *
+   * On the `password_reset` leg the blob is **also** appended to `redirect_url` as a query parameter, alongside
+   * `return_url`. The browser follows that redirect and leaves the JSON body behind, so anything the remaining legs of
+   * the login still need has to ride the URL. Preserve the query string exactly as given.
+   *
+   * An invalid `sso_state` never fails a login. A forged, edited or expired blob is silently dropped and the request is
+   * then treated as an ordinary login, so valid credentials still return `200` - just with no `sso` object. Check for
+   * `sso` explicitly rather than reading `200` as proof the hand-off survived. When it is absent, do not retry with the
+   * same blob; the user has to start again from the service provider. See the
+   * [Login with Green Security](https://greensecurity.apidocumentation.com/guides/sso-login-with-green-security)
+   * guide for the service provider half of this flow.
    */
   async postAuthenticate(
     request: operations.PostAuthenticateRequestBody,