Skip to main content

Frequently Asked Questions

General​

What is Visual Passcodes?​

Visual Passcodes (VP) is Secrets Vault’s Visual Authentication Identity Provider (VIdP), a secure identity service built on the OpenID Connect (OIDC) standard. It enhances security by replacing traditional passwords with a unique visual authentication method that uses a personal image (called Keepic) and a PIN.

How does Visual Passcodes improve security?​

Visual Passcodes enhances security through several mechanisms:

  • Visual Passcode: Replaces traditional passwords with a visual system based on zero-knowledge proofs.
  • Strong Cryptography: Uses the EdDSA signing algorithm for all JWTs (ID Tokens, Access Tokens), ensuring high cryptographic security.
  • Post-Quantum Cryptography: Uses ML-DSA and ML-KEM for the zero-knowledge proof and ciphering some content.
  • Standard Protocols: Implements secure, standard-based OIDC flows like the Authorization Code Flow with PKCE.
  • Endpoint Protection: All endpoints are protected with rate limiting to prevent abuse.
  • Secure Credential Handling: Enforces strict separation of client types and secure storage for credentials like the client_secret.

Can I use Visual Passcodes for both primary and second-factor authentication?​

Yes. Visual Passcodes is designed to be flexible. It can be integrated as the primary authentication system for your application or as a strong second factor (2FA) to augment an existing login process.

Technical Concepts​

What is the difference between a Confidential and a Public client?​

  • Confidential Clients are applications that can securely store credentials (like a client_secret) on a server-side backend (e.g., Node.js, Python, Java).
  • Public Clients cannot keep credentials confidential because their code is publicly accessible. This includes Single-Page Applications (SPAs) running in a browser (React, Vue, Angular) and native mobile apps. Public clients must use PKCE to secure the authentication flow.

What is PKCE?​

PKCE (Proof Key for Code Exchange) is a security extension for the Authorization Code Flow. It is mandatory for public clients and prevents authorization code interception attacks by ensuring that only the application that initiated the login flow can exchange the authorization code for tokens.

What authentication flows does Visual Passcodes support?​

Visual Passcodes supports the Authorization Code Flow, which is the most secure OIDC flow for web and mobile applications. For public clients, the use of PKCE with this flow is mandatory.

What signing algorithm does Visual Passcodes use for tokens?​

Visual Passcodes uses EdDSA to sign all tokens. Ensure your OIDC client library or token validation logic supports this algorithm.

Integration & Setup​

How do I register my application with Visual Passcodes?​

You can register a new application (client) through the Visual Passcodes Admin Portal. Navigate to the "Clients" section, click "Add Client," and provide the required details, such as the application name, client type (Confidential or Public), and one or more Redirect URIs.

What are client_id and client_secret?​

  • client_id: A public, unique identifier for your application, used in all OIDC flows.
  • client_secret: A confidential credential used by Confidential Clients to authenticate themselves to the token endpoint. It must be stored securely on your backend and never exposed in client-side code.

Where do I find my tenant's OIDC Discovery URL?​

You can find the Metadata URL (the OIDC Discovery URL) for your tenant in the Visual Passcodes Admin Portal under the "Tenant Config" section. It typically follows the format: https://your-server.com/api/oidc/{tenant_id}/.well-known/openid-configuration.

Can I use Visual Passcodes as a Second Factor (2FA)?​

Yes. To initiate a 2FA flow, include the scope openid 2fa in your authorization request. It is also strongly recommended to include the login_hint parameter with the user's identifier. In a 2FA flow, Visual Passcodes will only issue an id_token.

What scopes should I request?​

Request only the scopes your application needs. Common scopes include:

  • openid: (Required for OIDC) Signals an OIDC request to get an id_token.
  • profile: Grants access to default user profile claims like name.
  • email: Grants access to the user's email and email_verified claims.
  • 2fa: Triggers the second-factor authentication flow.

API & Tokens​

What is an id_token vs. an access_token?​

  • id_token: A JSON Web Token (JWT) intended for the client application. It contains claims about the user and the authentication event itself (e.g., user ID, email, when they authenticated). Your application must validate it to confirm the user's identity.
  • access_token: A credential (often a JWT) that your application uses to access protected resources on a server, such as your own backend API or the Visual Passcodes userinfo endpoint.

How do I validate tokens?​

You must always validate tokens received from Visual Passcodes:

  1. Verify the Signature: Use Visual Passcodes' public keys, available from the JWKS endpoint (/.well-known/jwks), to verify the token's signature. This ensures the token is authentic and was not tampered with.
  2. Validate the Claims: Check the iss (issuer), aud (audience, which should be your client_id), and exp (expiration time) claims to ensure the token is valid, intended for your app, and has not expired.
  3. Validate the Nonce: For id_tokens, you must also validate that the nonce claim matches the nonce value you sent in the initial authorization request to prevent replay attacks.

Troubleshooting​

What should I check if I encounter errors during the authentication flow?​

If you experience errors, verify the following common configuration issues:

  • Redirect URI Mismatch: Ensure the redirect_uri in your authorization request is exactly the same as one of the URIs registered for your client in the Visual Passcodes Admin Portal.
  • Incorrect Credentials: Double-check that your client_id is correct. If you have a confidential client, ensure the client_secret is correct and sent from your backend.
  • Invalid Scopes: Make sure you are requesting scopes that are supported by the tenant.
  • PKCE Failure: For public clients, ensure you are correctly generating and sending the code_verifier during the token exchange.
  • State Mismatch: Ensure the state parameter you receive on the callback matches the one you sent in the initial request to prevent CSRF attacks.