diff --git a/docs/docs/guides/integrate/login-ui/_browser_register_webauthn.mdx b/docs/docs/guides/integrate/login-ui/_browser_register_webauthn.mdx new file mode 100644 index 0000000000..d5570a3e08 --- /dev/null +++ b/docs/docs/guides/integrate/login-ui/_browser_register_webauthn.mdx @@ -0,0 +1,12 @@ +Now that you have started the registration within ZITADEL, you have to register the credentials in the browser. +This requires a call to the browser api and looks something like the following. +Make sure to send the public key credential creation options you got in the previous request from ZITADEL. + +```bash +const credential = await navigator.credentials.create({ + publicKey: publicKeyCredentialCreationOptions +}); +``` + +For more information about WebAuthN and registering credential flow, read the following guide: +[Registering a WebAuthN Credentials](https://webauthn.guide/#registration) \ No newline at end of file diff --git a/docs/docs/guides/integrate/login-ui/_list-mfa-options.mdx b/docs/docs/guides/integrate/login-ui/_list-mfa-options.mdx new file mode 100644 index 0000000000..ec454bc5c1 --- /dev/null +++ b/docs/docs/guides/integrate/login-ui/_list-mfa-options.mdx @@ -0,0 +1,46 @@ +Your user has successfully authenticated, and now you ask him if he wants to setup MFA to have a more secure account. +When he starts the configuration, first you want him to show the possible methods. +You can either list it implicitly or call the settings service from ZITADEL to get what is configured on the login settings. + +More detailed information about the API: [Get Login Settings Documentation](/apis/resources/settings_service/settings-service-get-login-settings) + +Request Example: + +```bash +curl --request GET \ + --url https://$ZITADEL_DOMAIN/v2alpha/settings/login \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer '"$TOKEN"'' +``` + +Response Example: +The relevant part for the list is the second factor and multi factor list. + +```bash +{ + "details": { + "sequence": "293", + "changeDate": "2023-03-29T14:16:55.570482Z", + "resourceOwner": "163840776835432705" + }, + "settings": { + "allowUsernamePassword": true, + "allowRegister": true, + "allowExternalIdp": true, + "passkeysType": "PASSKEYS_TYPE_ALLOWED", + "passwordCheckLifetime": "864000s", + "externalLoginCheckLifetime": "864000s", + "mfaInitSkipLifetime": "2592000s", + "secondFactorCheckLifetime": "64800s", + "multiFactorCheckLifetime": "43200s", + "secondFactors": [ + "SECOND_FACTOR_TYPE_OTP", + "SECOND_FACTOR_TYPE_U2F" + ], + "multiFactors": [ + "MULTI_FACTOR_TYPE_U2F_WITH_VERIFICATION" + ], + "resourceOwnerType": "RESOURCE_OWNER_TYPE_ORG" + } +} +``` \ No newline at end of file diff --git a/docs/docs/guides/integrate/login-ui/mfa.mdx b/docs/docs/guides/integrate/login-ui/mfa.mdx new file mode 100644 index 0000000000..c2ae9d80e0 --- /dev/null +++ b/docs/docs/guides/integrate/login-ui/mfa.mdx @@ -0,0 +1,191 @@ +--- +title: Multi-Factor (MFA) +sidebar_label: Multi-Factor (MFA) +--- + +import MfaOptions from './_list-mfa-options.mdx'; +import BrowserRegisterWebAuthN from './_browser_register_webauthn.mdx'; + + +Multi-factor authentication (MFA) is a multi-step account authentication which requires to user to enter more than only the password. +It is highly recommended to use MFA or [Passkeys](./passkey) to make your user accounts more secure. + +ZITADEL supports two different Methods: +- Time-based one time password (TOTP), which are Authenticator apps like Google/Microsoft Authenticator, Authy, etc +- Universal Second Factor (U2F), which is authentication with your device like Windows Hello, Apple FaceID, Fingerprint, FIDO2 keys, Yubikey, etc. + +## TOTP Registration + +### Flow + +![Register TOTP](/img/guides/login-ui/register-totp-flow.png) + +### List the Possible Methods + + + +### Start TOTP Registration + +The user has selected to setup Time-based One-Time-Password (TOTP). +To show the user the QR to register TOTP with his Authenticator App like Google/Microsoft Authenticator or Authy you have to start the registration on the ZITADEL API. +Generate the QR Code with the URI from the response. +For users that do not have a QR Code reader make sure to also show the secret, to enable manual configuration. + +More detailed information about the API: [Start TOTP Registration Documentation](/apis/resources/user_service/user-service-register-totp) + +Request Example: + +```bash +curl --request POST \ + --url https://$ZITADEL_DOMAIN/v2alpha/users/$USER_ID/totp \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer '"$TOKEN"'' + --header 'Content-Type: application/json' \ + --data '{}' +``` + +Response Example: + +```bash +{ + "details": { + "sequence": "2", + "changeDate": "2023-06-28", + "resourceOwner": "69629023906488334" + }, + "uri": "otpauth://totp/ZITADEL:minni-mouse@mouse.com?algorithm=SHA1&digits=6&issuer=ZITADEL&period=30&secret=TJOPWSDYILLHXFV4MLKNNJOWFG7VSDCK", + "secret": "TJOPWSDYILLHXFV4MLKNNJOWFG7VSDCK" +} +``` + +### Verify TOTP Registration + +When the user has added the account to his authenticator app, he has to enter the code from the App to finish the registration. +This code has to be sent to the verify endpoint in ZITADEL. + +More detailed information about the API: [Verify TOTP Documentation](/apis/resources/user_service/user-service-verify-totp-registration) + +Request Example: + +```bash +curl --request POST \ + --url https://$ZITADEL_DOMAIN/v2alpha/users/$USER_ID/totp/_verify \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer '"$TOKEN"'' + --header 'Content-Type: application/json' \ + --data '{ + "code": "123456" +}' +``` + +## U2F Registration + +### Flow + +![Register U2F](/img/guides/login-ui/register-u2f-flow.png) + +### List the Possible Methods + + + +### Start U2F Registration + +The user has selected to setup Universal Second Factor (U2F). +To be able to authenticate in the browser you have to start the u2f registration within ZITADEL. + +More detailed information about the API: [Start U2F Registration Documentation](/apis/resources/user_service/user-service-register-u-2-f) + +Request Example: + +```bash +curl --request POST \ + --url https://$ZITADEL_DOMAIN/v2alpha/users/$USER_ID/u2f \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer '"$TOKEN"'' + --header 'Content-Type: application/json' \ + --data '{ + "domain": "acme.com" + }' +``` + +Response Example: + +```bash +{ + "details": { + "sequence": "2", + "changeDate": "2023-07-03", + "resourceOwner": "69629023906488334" + }, + "u2fId": "163840776835432705", + "publicKeyCredentialCreationOptions": { + "publicKey": { + "attestation": "none", + "authenticatorSelection": { + "userVerification": "required" + }, + "challenge": "XaMYwWOZ5hj6pwtwJJlpcI-ExkO5TxevBMG4R8DoKQQ", + "excludeCredentials": [ + { + "id": "tVp1QfYhT8DkyEHVrv7blnpAo2YJzbZgZNBf7zPs6CI", + "type": "public-key" + } + ], + "pubKeyCredParams": [ + { + "alg": -7, + "type": "public-key" + } + ], + "rp": { + "id": "localhost", + "name": "ZITADEL" + }, + "timeout": 300000, + "user": { + "displayName": "Minie Mouse", + "id": "MjE1NTk4MDAwNDY0OTk4OTQw", + "name": "minie-mouse" + } + } + } +} +``` + +### Register new U2F on current device + + + +### Verify U2F Registration + +In the next request you have to verify the U2F within ZITADEL. +Include the public key credential you got from the browser in your request. +You can give the U2F a name, which makes it easier for the user to identify the registered authentication methods. +Example: Google Pixel, iCloud Keychain, Yubikey, etc + +More detailed information about the API: [Verify U2F Documentation](/apis/resources/user_service/user-service-verify-u-2-f-registration) + +Example Request: + +```bash + +curl --request POST \ + --url https://$ZITADEL_DOMAIN/v2alpha/users/$USER_ID/u2f/$PASSKEY_ID \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer '"$TOKEN"''\ + --header 'Content-Type: application/json' \ + --data '{ + "publicKeyCredential": { + "type": "public-key", + "id": "pawVarF4xPxLFmfCnRkwXWeTrKGzabcAi92LEI1WC00", + "rawId": "pawVarF4xPxLFmfCnRkwXWeTrKGzabcAi92LEI1WC00", + "response": { + "attestationObject": "o2NmbXRmcGFja2VkZ2F0dFN0bXSiY2FsZyZjc2lnWEcwRQIgRKS3VpeE9tfExXRzkoUKnG4rQWPvtSSt4YtDGgTx32oCIQDPey-2YJ4uIg-QCM4jj6aE2U3tgMFM_RP7Efx6xRu3JGhhdXRoRGF0YVikSZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzzuoMdl2NFAAAAADju76085Yhmlt1CEOHkwLQAIKWsFWqxeMT8SxZnwp0ZMF1nk6yhs2m3AIvdixCNVgtNpQECAyYgASFYIMGUDSP2FAQn2MIfPMy7cyB_Y30VqixVgGULTBtFjfRiIlggjUGfQo3_-CrMmH3S-ZQkFKWKnNBQEAMkFtG-9A4zqW0", + "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiQlhXdHh0WGxJeFZZa0pHT1dVaUVmM25zby02aXZKdWw2YmNmWHdMVlFIayIsIm9yaWdpbiI6Imh0dHBzOi8vbG9jYWxob3N0OjgwODAifQ" + } + }, + "tokenName": "Google Pixel" +}' +``` + +You have successfully registered a new U2F to the user. \ No newline at end of file diff --git a/docs/docs/guides/integrate/login-ui/passkey.mdx b/docs/docs/guides/integrate/login-ui/passkey.mdx index 8a529a64c3..bec0a2d603 100644 --- a/docs/docs/guides/integrate/login-ui/passkey.mdx +++ b/docs/docs/guides/integrate/login-ui/passkey.mdx @@ -166,18 +166,7 @@ Response Example: ### Register new Passkey on current device -Now that you have started the registration within ZITADEL, you have to register the credentials in the browser. -This requires a call to the browser api and looks something like the following. -Make sure to send the public key credential creation options you got in the previous request from ZITADEL. - -```bash -const credential = await navigator.credentials.create({ - publicKey: publicKeyCredentialCreationOptions -}); -``` - -For more information about WebAuthN and registering credential flow, read the following guide: -[Registering a WebAuthN Credentials](https://webauthn.guide/#registration) + ### Verify Passkey in ZITADEL diff --git a/docs/sidebars.js b/docs/sidebars.js index c85ea1ca64..bdebfe180a 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -199,6 +199,7 @@ module.exports = { "guides/integrate/login-ui/username-password", "guides/integrate/login-ui/external-login", "guides/integrate/login-ui/passkey", + "guides/integrate/login-ui/mfa", "guides/integrate/login-ui/select-account", "guides/integrate/login-ui/password-reset", "guides/integrate/login-ui/logout", diff --git a/docs/static/img/guides/login-ui/register-totp-flow.png b/docs/static/img/guides/login-ui/register-totp-flow.png new file mode 100644 index 0000000000..75a4da5c1d Binary files /dev/null and b/docs/static/img/guides/login-ui/register-totp-flow.png differ diff --git a/docs/static/img/guides/login-ui/register-u2f-flow.png b/docs/static/img/guides/login-ui/register-u2f-flow.png new file mode 100644 index 0000000000..2e1c39d02e Binary files /dev/null and b/docs/static/img/guides/login-ui/register-u2f-flow.png differ