Skip to main content
Star OpenZiti on GitHub Star

MFA TOTP

OpenZiti authentication allows for n-factors of authentication - meaning that it is possible to support 1FA, 2FA, ...nFA authentication. One common setup for multi-factor authentication (MFA) is time-based one time passwords (TOTP). TOTP is commonly seen in "authenticator" applications (e.g. Google Authenticator, Authy, Microsoft Authenticator, etc). All "authenticator" applications support the same core TOTP RFC 6238 specification.

Enforcement​

OpenZiti allows individual clients to enroll or un-enroll from MFA TOTP. Administrators can enforce TOTP enrollment through Authentication Policies and Posture Checks.

Authentication Policies​

When enforced at authentication via an Authentication Policy, clients are unable to transition from partially authenticated to fully authenticated without enrolling in MFA TOTP - leaving them unable to list services or connect to them.

MFA Posture Check​

When enforced through the MFA Posture Check, clients still must become fully authenticated according to their Authentication Policy, however, access to services is determined by their policy and posture check access. If a service is granted only through a service policy that has an MFA posture check, they will not be able to connect to that service without enrolling in MFA TOTP.

Submitting TOTP during Authentication​

When TOTP is required during authentication, how the code is submitted depends on the authentication system in use:

Enrollment​

Enrollment associates a TOTP secret with an Identity. The controller generates a secret and 20 single-use recovery codes. Recovery codes can be used in place of a TOTP code during authentication and are consumed when used.

Enrollment can be performed at different points depending on the authentication system in use:

  • During an OIDC authentication flow - if the Authentication Policy requires TOTP but the Identity is not yet enrolled, enrollment can be completed mid-flow before the authorization code is issued. See OIDC Authentication - TOTP Enrollment for the OIDC-specific endpoints and flow.
  • Before or during legacy authentication - enrollment can be started and completed while partially authenticated during a legacy auth session (see Legacy Authentication - Partial Authentication). It can also be performed any time after becoming fully authenticated.
  • Any time when fully authenticated - available to both OIDC and legacy authenticated clients via the Edge Client API endpoints below.

Enrollment status​

Enrollment status can be checked by the client at any time when fully authenticated, or while enrollment is in progress during a legacy partial-auth session:

GET /edge/client/v1/current-identity/mfa

<empty body>

If enrolled:

{
  "isVerified": true
}

If enrollment is in progress (started but not yet verified):

{
  "isVerified": false,
  "recoveryCodes": ["code1", "..."],
  "provisioningUrl": "otpauth://totp/<identity-name>?issuer=ziti.dev&secret=<secret>"
}

If enrollment has not been started: HTTP 404 Not Found

Fields:

  • isVerified - true/false status for enrollment. If true only this value is returned. If false the current enrollment information is provided
  • recoveryCodes - an array of 20 single-use recovery codes that may be used in place of a TOTP code during Authentication. Each code is consumed when used and is then invalid. Only shown while enrollment has not been completed.
  • provisioningUrl - an otpauth url used by authenticator applications, normally shown as a QR code

Start Enrollment​

Enrollment is started by the client. This endpoint is available when fully authenticated and also during a legacy partial-auth session (when the Authentication Policy requires TOTP but the Identity has not yet enrolled):

POST /edge/client/v1/current-identity/mfa

{}

The response contains a provisioning URL, QR code URL, and 20 single-use recovery codes.

Verify and complete Enrollment​

Enrollment is completed by verifying the secret has been received by providing a currently valid TOTP code. Recovery codes are not treated as a valid value here. A live TOTP code is required.

POST /edge/client/v1/current-identity/mfa/verify

{
  "code": "<totp-code>"
}

Restart Enrollment​

If enrollment has been started but not completed, the in-progress enrollment must be cancelled before starting a new one. To cancel an in-progress enrollment:

DELETE /edge/client/v1/current-identity/mfa

{
  "code": ""
}

A new enrollment can then be started with POST /edge/client/v1/current-identity/mfa.

QR code​

To aid in enrollment, the current enrollment's provisioningUrl may be retrieved as a QR code. As long as an outstanding MFA TOTP enrollment is active an image is available at:

GET /edge/client/v1/current-identity/mfa/qr-code

Removing or unenrolling​

MFA TOTP can be removed by an administrator at any time on behalf of a client. Clients may remove MFA TOTP enrollment from their account as long as they have access to a recovery code or TOTP code.

Client removal​

DELETE /edge/client/v1/current-identity/mfa

{
  "code": "<totp-or-recovery-code>"
}

Administrative removal​

DELETE /edge/management/v1/identities/<id>/mfa

<empty body>

Viewing recovery codes​

At any time the current valid list of recovery codes may be viewed by the client by issuing the following request:

GET /edge/client/v1/current-identity/mfa/recovery-codes

{
  "code": "<totp-or-recovery-code>"
}

Regenerating recovery codes​

At any time the current valid list of recovery codes may be replaced by the client by issuing the following request:

POST /edge/client/v1/current-identity/mfa/recovery-codes

{
  "code": "<totp-or-recovery-code>"
}