Identity verification with GBG-greenID

Marketplace Request Integration
1

Looking for any integration references with GBG-greenID.

We are currently working for a customer who’s looking to integrate Auth0 with GBG-greenID for document verification and liveness checks.

2 Likes
3

While there is no official, pre-built “one-click” partner integration for GBG-greenID (formerly Vix Verify) inside the Auth0 Marketplace, integrating the two platforms is a common architectural pattern, particularly in Australia and New Zealand for AML/KYC and 100-point identity checks.

To successfully connect Auth0 with GBG-greenID for document verification and liveness checks, implement the Redirect Protocol using Auth0 Actions.

:building_construction: Recommended Architecture: The Redirect Action Pattern

When a user signs up or attempts to access a privileged route, you intercept the login flow in Auth0, redirect them to a secure frontend route to perform the greenID verification (including capturing documents and performing liveness checks), and then resume the login flow once greenID returns a verification payload.

Step-by-Step Integration Guide

1. Define the Trigger Condition

Determine when the verification should occur. For example, during sign-up (event.stats.logins_count === 1) or when a user tries to access a feature that requires a higher level of assurance (Step-up Verification).

2. Create an Auth0 Post-Login Action

Create a new Post-Login Action in your Auth0 dashboard. This Action checks if the user has already completed verification. If not, it redirects them to your custom routing portal.

/**
* Handler that will be called during the execution of a PostLogin flow.
*/
exports.onExecutePostLogin = async (event, api) => {
  // 1. Check if the user is already verified in their app_metadata
  const isVerified = event.user.app_metadata?.greenid_verified;

  if (isVerified) {
    return; // Already verified, continue normal login
  }

  // 2. Generate a secure, cryptographically signed token to send to your gateway
  // This prevents users from tampering with payload parameters or bypassing verification
  const sessionToken = api.redirect.encodeToken({
    secret: event.secrets.REDIRECT_SECRET,
    payload: {
      userId: event.user.user_id,
      email: event.user.email,
    },
  });

  // 3. Redirect to your web application hosting the greenID SDK / Web integration
  api.redirect.sendUserTo("https://your-app.com/verify-identity", {
    query: { session_token: sessionToken }
  });
};

/**
* Handler that will be called when returning from your redirect portal.
*/
exports.onContinuePostLogin = async (event, api) => {
  let payload;
  try {
    // Verify the signed token coming back from your application gateway
    payload = api.redirect.validateToken({
      secret: event.secrets.REDIRECT_SECRET,
      token: event.request.query.session_token,
    });
  } catch (error) {
    return api.access.deny("Identity verification token was invalid.");
  }

  // Check the verification status passed back by your secure backend
  if (payload.status === "VERIFIED") {
    // Persist status to Auth0 user metadata so they aren't prompted again
    api.user.setAppMetadata("greenid_verified", true);
    api.user.setAppMetadata("greenid_verification_date", new Date().toISOString());
  } else {
    api.access.deny("Identity verification with greenID failed.");
  }
};

3. Set Up Your Verification Portal & greenID SDK

Your hosted web application (e.g., /verify-identity route) acts as the bridge:

  • Token Validation: Decode the session_token received from Auth0 on your backend to extract the user’s Auth0 user_id.

  • The greenID Handshake: Use the greenID Web API or mobile greenID SDK (which handles liveness detection via the camera and OCR document capture) .

  • Process Flow: The greenID platform checks the submitted credentials against Australian/NZ government databases (DVS, etc.) and performs biometric matching .

  • Callback to Auth0: Once greenID returns a successful match status, your backend signs a new JWT containing status: "VERIFIED" and your user ID, and redirects the browser back to Auth0’s resume endpoint:

    https://YOUR_AUTH0_DOMAIN/continue?state=THE_ORIGINAL_STATE_PARAM&session_token=SIGNED_RESPONSE_JWT

:warning: Implementation Gotchas & Best Practices

  1. Do Not Store Biometric / Document Data in Auth0:
    Due to Australian privacy principles and strict regulatory environments (AML/KYC), store only the assertion boolean (e.g., greenid_verified: true) and the greenID Verification Transaction ID (verificationId) in your Auth0 app_metadata. Do not store raw driver’s license numbers, passports, or facial liveness photos within Auth0.

  2. Handle the “Snooze” or Back-Out Path:
    If a user lands on the greenID screen and closes the browser or presses “Cancel,” they will be stuck in a redirect loop. Provide a “Cancel” button on your verification page that redirects back to Auth0 with an error state (e.g., api.access.deny("User aborted identity verification.")) so your app can handle the rejected session gracefully.

  3. Session Resumptions Limits:
    Auth0’s redirect state has a maximum expiration lifetime of 24 hours. Users must complete their document uploads and liveness checks within this window, otherwise, the callback will fail with an expired state error.

Kind Regards,
Nik

1 Like