Skip to main content

Integrate Visual Passcodes with Keycloak

This guide explains how to integrate your Visual Identity Provider (Visual Passcodes) as an OpenID Connect (OIDC) identity provider in your Keycloak instance. By following these steps, you will connect both platforms securely using client credentials, metadata, and OIDC scopes.

Prerequisites​

  • A Visual Passcodes tenant and an admin user (provided by our team).
  • Access to the Visual Passcodes BackOffice.
  • Admin access to your Keycloak instance.

Step 1 - Log into Visual Passcodes BackOffice​

  1. Go to the Visual Passcodes BackOffice and sign in.

  2. Navigate to the Clients section.

  3. Click the "Add Client" button. Create Client

  4. Fill in the form:

    • Name: any label for identification.
    • Client ID: a unique identifier for the integration.
    • Redirect URIs: leave blank for now (will be completed later).
    • Client Type: Confidential

  5. Click Create and copy the generated Client ID and Client Secret.

Client Credentials

Step 2 - Copy Metadata URL & Scopes​

  1. In the left menu, click Tenant Config.
  2. Copy the Metadata URL and the OAuth Scopes.

Copy Scopes and Metadata

Step 3 - Add the Identity Provider in Keycloak​

  1. Log into your Keycloak Admin Console.
  2. Go to the realm where you want to integrate Visual Passcodes.
  3. Navigate to Identity Providers > Add provider > OpenID Connect.

Create IDP in Keycloak

  1. Fill in the required fields:

    • Alias: e.g. visualauth
    • Display Name: Test Visual Passcodes
    • Discovery Endpoint: paste the Metadata URL from Visual Passcodes.

Keycloak will automatically fill in all the URLs (Auth, Token, JWKS, etc.)

  1. In the Client Authentication section:

    • Method: Client secret sent as post
    • Client ID & Secret: paste what you copied from the Visual Passcodes BackOffice.
    • Signature Algorithm: EdDSA

Step 4 - Enable Trust Email & Set Scopes​

  1. Once created, go to Advanced Settings of the new provider.
  2. Enable Trust Email.

Toggle Trust Email

  1. In the OpenID Connect Settings, paste the OAuth scopes you copied earlier:
openid profile email

Paste Scopes

  1. Click Save.

Step 5 - Copy Redirect URI and Update Visual Passcodes Client​

  1. In your new Keycloak Identity Provider details, copy the Redirect URI.

Get Redirect URI

  1. Go back to the Visual Passcodes BackOffice > Clients section.
  2. Edit the client you previously created.
  3. Paste the Keycloak Redirect URI into the Redirect URIs field. Add Client

Paste Redirect URI in BO

  1. Save the changes.

Finished!​

Your integration is now complete. Keycloak will now redirect users to authenticate via your Visual Passcodes using OIDC with secure visual authentication and EdDSA signatures.

If you experience any issues, please verify:

  • Your client credentials are correctly set.
  • The redirect URI is properly updated.
  • The discovery endpoint is reachable.
  • Trust Email and Scopes are correctly configured.

For support, contact your integration lead or support team.

🔗 Related Resources​