Two-factor authentication

Two-factor authentication (2FA) adds an extra layer of security by requiring users to verify their identity with an additional code.

Key takeaway

With a standard integration via Authorization Code Flow (+ PKCE), your application does not implement 2FA at all. The entire two-factor verification process is handled by Klubero SSO on its hosted sign-in page.

2FA in the Authorization Code Flow

When using the Authorization Code Flow (the recommended and only supported integration method for third-party applications), 2FA is automatically part of the sign-in process on the SSO side. Your application doesn't have to deal with 2FA:

1. The user is redirected to the Klubero SSO sign-in page
2. They enter their email and password (or use an external provider / magic link)
3. If they have 2FA enabled, they complete verification directly on the SSO screen:
   • Authenticator: enter the current code from the app
   • Email: receive a code by email and enter it
   • or use a recovery code
4. Only after 2FA is completed successfully is the authorization code (code) delivered to your application at the registered redirect_uri

Your application therefore receives the authorization code only after the entire sign-in, including 2FA, is complete. No special implementation is required — no additional endpoints and no handling of "2FA required" states — everything happens on the Klubero SSO side.

info

Because 2FA takes place entirely on the hosted SSO sign-in page, the outcome for your application is always the same as a regular sign-in: you either receive an authorization code (sign-in succeeded), or the user is redirected back with an OAuth error. For error details, see troubleshooting.

Supported methods

Method	Description	Recommendation
Authenticator app	TOTP code from Google/Microsoft Authenticator	Recommended – most secure
Email	6-digit code sent by email	Fallback for users without a smartphone

Users choose and configure these methods in their profile on the Klubero SSO side. From the integrating application's perspective, this is internal behavior of the sign-in page.

Recommended method

An authenticator app (Google Authenticator, Microsoft Authenticator, Authy) is the most secure and convenient method:

• Works offline
• Codes are generated locally
• No waiting for email
• Free

How an authenticator app works (TOTP)

TOTP (Time-based One-Time Password) generates 6-digit codes that change every 30 seconds:

1. The user activates 2FA by scanning a QR code in their profile
2. The app (Google/Microsoft Authenticator) stores a shared secret key
3. At sign-in, the user enters the current 6-digit code from the app
4. Klubero SSO verifies the code against the shared secret key

The authenticator is compatible with all standard apps that support RFC 6238 TOTP (Google Authenticator, Microsoft Authenticator, Authy, 1Password, Bitwarden, and others).

---

Managing 2FA via the REST API (M2M)

For server-side (machine-to-machine) integration, Klubero SSO offers endpoints for managing users' 2FA settings. These endpoints are optional and are intended, for example, for administration tools on your application's side — they are not part of the sign-in flow.

Authorization

All 2FA management endpoints require an access token obtained via client_credentials with the api scope. User tokens (obtained via the Authorization Code Flow) cannot call these endpoints.

In all examples, {guid} is the user's GUID. The JSON uses camelCase, and enum values are serialized as numbers.

Numeric values of the 2FA method

The 2FA method (TwoFactorMethodType) is passed and returned in the API as a number:

Value	Method
2	Email
3	Authenticator (TOTP)

Getting the 2FA status

Endpoint: GET /api/twofactor/{guid}/status

curl https://your-sso-domain.com/api/twofactor/USER_GUID/status \
  -H "Authorization: Bearer M2M_ACCESS_TOKEN"

Response:

{
  "enabled": true,
  "primaryMethod": 3
}

The primaryMethod field is a number (2 = Email, 3 = Authenticator) or null if the user does not have 2FA enabled.

Enabling 2FA

Endpoint: POST /api/twofactor/{guid}/enable

curl -X POST https://your-sso-domain.com/api/twofactor/USER_GUID/enable \
  -H "Authorization: Bearer M2M_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "method": 3 }'

Response:

{
  "enabled": true,
  "recoveryCodes": ["ABC12345", "DEF67890", "GHI11213"]
}

The recoveryCodes field contains single-use recovery codes that the user must store securely.

Disabling 2FA

Endpoint: POST /api/twofactor/{guid}/disable

curl -X POST https://your-sso-domain.com/api/twofactor/USER_GUID/disable \
  -H "Authorization: Bearer M2M_ACCESS_TOKEN"

Sending a code

Endpoint: POST /api/twofactor/{guid}/send-code

Sends a verification code using the chosen method. Both the method and purpose fields are numbers.

curl -X POST https://your-sso-domain.com/api/twofactor/USER_GUID/send-code \
  -H "Authorization: Bearer M2M_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "method": 2, "purpose": 1 }'

Generating new recovery codes

Endpoint: POST /api/twofactor/{guid}/recovery-codes

curl -X POST https://your-sso-domain.com/api/twofactor/USER_GUID/recovery-codes \
  -H "Authorization: Bearer M2M_ACCESS_TOKEN"

Response:

{
  "recoveryCodes": ["ABC12345", "DEF67890", "GHI11213"]
}

Recovery codes

Each recovery code can be used only once. Once a new set is generated, the previous codes are invalidated.

Verification code properties

Authenticator (TOTP)

Property	Value
Format	6 digits
Lifetime	30 seconds
Tolerance	±30 seconds (for clock-sync differences)
Algorithm	HMAC-SHA1 (RFC 6238)

Email

Property	Value
Format	6 digits (000000–999999)
Lifetime	10 minutes
Delivery	Email

Compatible apps

The TOTP authentication method is compatible with all standard authenticators:

• Google Authenticator (Android, iOS)
• Microsoft Authenticator (Android, iOS)
• Authy (Android, iOS, Desktop)
• 1Password (integrated)
• Bitwarden (integrated)
• Any app that supports RFC 6238 TOTP