MFA docs

[rishabhpoddar]

Summary of change

(A few sentences about this PR)

Related issues

• TOTP / MFA login discussions supertokens-core#554

Checklist

• Algolia search needs to be updated? (If there is a new sub docs project, then yes)
• Sitemap needs to be updated? (If there is a new sub docs project, then yes)
• Checked for broken links? (Run cd v2 && MODE=production npx docusaurus build)
• Changes required to the demo apps corresponding to the docs?

Remaining TODOs for this PR

• Link MFA docs in other recipes (in additional features section)
• Link multi tenancy / b2b org docs in other recipes (in additional features section)
• Migration (in general and of totp devices): https://supertokens.slack.com/archives/C051BN9QJUX/p1702061857434489
• Recovery codes implementation: https://supertokens.slack.com/archives/C051BN9QJUX/p1701077548495559?thread_ts=1701076782.735219&cid=C051BN9QJUX
• Legacy / free version implementation
• Storybook link: https://6571be2867f75556541fde98-xieqfaxuuo.chromatic.com/?path=/story/auth-page--playground
• Pre built UI and custom UI
• Add with email verification
• Link and description of example app in introduction page - make sure that that is correct.
• Remember device customisation: https://supertokens.slack.com/archives/C051BN9QJUX/p1702287457383659
• Security considerations
  • Remember to talk about when users are allowed to setup a factor and why thats important
• Mention that the c array is not guaranteed to be completed for existing sessions.
• Enabling a factor for all users in a tenant
• Confirm that the curl command here is correct: http://localhost:3000/docs/mfa/backend-setup for multi tenancy and first factor config
• Confirm on this page (http://localhost:3000/docs/mfa/backend-setup) that we can set firstFactors to undefined in mfa.init in case of multi tenancy use
• To remove firstFactors from tenant config, we set it to null and explain what that means
• Legacy MFA method does not need to worry about overwriting the session anymore. Decided not to do this cause it doesn't matter is users do this.
• Protecting API and frontend and talk about validators
• Migration of existing sessions and its effect on validators and the logic in getMFARequirementsForAuth
• Is returning undefined supported in getMFARequirementsForAuth?
• Change link to legacy example app to point to older version in github cause the mfa app will be replacede now.
• Forcing the frontend pre built UI into setup mode (when would this be useful? and how to do it?)
• For case of email otp being used as an email verification method, users also need to add email verification recipe cause the email for email-otp is selected on the frontend, and someone malicious can bypass that and use their own email instead of the first factor's email. In this case, the email verification claim would fail since that uses the first factor's email ID.
• about step up auth:
  • need to override checkAllowedToSetupFactorElseThrowInvalidClaimError
  • need to throw error only if n array is empty.
• Specific example use cases like totp for all users, totp for selected users (custom and pre built UI)
• Instead of using hard coded factor ids like email-otp, use constants exported by the sdk
• Fix docs for session claim validator in interface of SessionClaim (removing ? from userContext), and changing to use UserContext type: https://supertokens.com/docs/thirdpartyemailpassword/common-customizations/sessions/claims/claim-validators#on-the-backend
• Make sure that links to storybook are correct and that they point to the master branch. Global search for "chromatic.com" to find all links
• Support cases
• Access denied screen is there or no?
• In the "Handling misconfigurations" case in pre built UI, is the following point true?

You may have enabled otp-email for a user that is a part of a tenant as a secondary factor, but did not set passwordlessEnabled: true for that tenant in which the user is a part of. 

• Allow devs to change factors entirely? For example, if users in the app all have totp enabled, but then the dev decides to change the mfa requirement to not have totp anymore, but have otp-email, then how will that work? Cause then, all users will end up in a case where they can’t really set that factor up.. (same goes for any other change as well..)
  • This is not an issue cause the only factors that are considered for is already setup are the ones returned from the getMFARequirementForAuth anyway
• About access denied factor ID on the frontend and backend setup sections..
  • This is not needed as we have removed this special factor ID
• Add about calling mfa info endpoint in the custom UI frontend setup docs
• All custom code snippets for sign in / up being called in all recipes must handle new statuses that are generated cause of MFA
• MFA docs for protecting APIs should also mention about if not using getSession, which claim to check and how
• how are we doing to tackle migration for mobile apps? If the backend wants to change to enforcing that TOTP is needed for all users, but some clients still have an older version of the mobile app, how would the backend be configured to do this given that some frontends won’t be able to show a totp setup screen?
  • Users have to run the validator conditionally, and also add the requirement conditionally based on client version
• In pre built UI, talk about access denied screen and where all it's shown: https://supertokens.slack.com/archives/C051BN9QJUX/p1704315564703339?thread_ts=1703508522.185239&cid=C051BN9QJUX
• Talk about email template of MFA in MFA docs + email delivery docs
• Support codes screenshots
• Account linking support code need to change.
• Write about different configureations for totp like changeing name, skew time etc
• check that in web-js, supertokensMultiFactor is correct.
• In the post signin up callback we need to tell users to check for if a session exists or not to check if it's a first or second factor for their override logic.
• In MFA route protecting on the backend and frontend when not using our validators, we should handle the case of undefined by calling await Claim.refresh() on the frontend, and await session.fetchAndSet(claim) on the backend.
• In /docs/thirdpartyemailpassword/advanced-customizations/frontend-hooks/handle-event, we need to also check for isFirstFactor to make sure that events only get fired once.
• In /docs/thirdpartyemailpassword/pre-built-ui/auth-redirection, we need to mention that getRedirectURL with success context is only called for the first factor. and not all factors.
• Write about frontend event hooks and redirection control in frontend setup for mfa -> pre built UI -> specifically for totp recipe sinc thats not there anywhere else.
• In backend setup docs for MFA, we needd to talk about change in post sign in / up callback logic to check for session.
• Add that thirdparty as a secondary factor is not possible in the limitations section.
• Wherever we are using getLoginMethods, we need to consume firstFactors as well before checking for whats enabled and what is not.
• For the docs in emailpassword as second factor, we have to tell people about email verification being required for MFA to happen. This can happen if they do a passwordless otp flow before asking users to set a password. Also mention, that in case there is a fake email, then the emailpassword will recipe will mark as verified on its own. In case there is no email (like the first factor is phone otp), then the sdk will generate a fake email on its own.
• For emailpassword as secondary factor, we should reset them via backup codes, or by entering the existing password and then resetting it.. and not via password reset flow without login. This is cause these ep accounts can be associated with fake emails and then there i no way of sending a password reset link
• If there is any mention of fake email format, we should change that in the docs
• Change the auth redirection page to use the new getredirection function on the root level. To detect sign in / up we have to check action == "SUCCESS" and newSessionCreated
• migration docs for older mfa method to new one
• Account linking needs to be initialised as well for mfa to work. So docs need to change to state that.
• In the legacy vs new docs for MFA, we need to modify it to remove that new is only supported by non node SDKs as and when we add more SDK support.
• docs for MFA migration from legacy to new MFA
• In 2fa when calling createCode, we have to pass in the factor id, but not in first factor.. Not needed anymore cause no first factors as an input to createCode
• Enabling MFA without first factor automatic account linking
• In account linking docs, need to mention about adding social accounts to existing session, and how to do that.
• Embedding pre built UI docs
• Add link to emailpassword based step up auth
• check that the backup codes docs links to the right places in the example app
• add about smsType in smsDelivery impl, similar to how we have emailType
• onHandleEvent of frontend in the docs also needs to change.
• Changes phone password recipe to be phone otp + password as opposed to just phone password (this should be done via MFA) Decided not to do this cause the older method works and is free.
• change the password reset docs to use verifyCredentials instead of signIn
• Add docs for update phone number in passwordless using the new verifyCode
• Write about totp device management (like listing, removing devices)
• add link to storybook for pre built UI everywhere (in the getting started page etc)
• Mention that calling consumeCode with a session will mark the email of the session user as verified if the email is the same
• Update recover code docs to make use of Session claim for recovery code so that a user always has that.
• add docs for e2e testing with MFA

[netlify]

✅ Deploy Preview for admiring-bhabha-7b1be9 ready!

Name	Link
🔨 Latest commit	0add4b1
🔍 Latest deploy log	https://app.netlify.com/sites/admiring-bhabha-7b1be9/deploys/65eff942a85baf00088adde0
😎 Deploy Preview	https://deploy-preview-763--admiring-bhabha-7b1be9.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.