Skip to main content

Core Concepts

Before writing any code, it helps to understand a few key OIDC concepts you’ll encounter when working with Visual Passcodes.

Client types​

In OIDC, your application is a “client.” Visual Passcodes needs to know what type of application you’re registering because it affects how security is handled. The primary distinction is between confidential and public clients.

  • Confidential clients: Applications that run on a secure server, such as backends written in Python, Node.js, or Java. Because they are server‑side, they can keep credentials confidential, including a client_secret. They use this secret to authenticate directly to the Visual Passcodes token endpoint.

  • Public clients: Applications that cannot keep credentials confidential because their code is accessible to end users. Examples include single‑page applications (SPAs) running in the browser (React, Angular, Vue) or native mobile apps. Since they cannot securely store a client_secret, they rely on PKCE to secure the authentication flow.

Authorization Code Flow with PKCE​

Visual Passcodes uses the standard OIDC Authorization Code Flow, a secure method for handling authentication. It adds an extra layer of protection by not sending tokens directly to the browser in the first step.

The flow works like this:

  1. Authorization request: Your application redirects the user to Visual Passcodes’ authorization endpoint.
  2. Visual auth challenge: Instead of a password, the user completes Visual Passcodes’ unique visual authentication challenge.
  3. Authorization code grant: After successful authentication, Visual Passcodes redirects back to your application with a temporary, one‑time authorization_code.
  4. Token exchange: Your backend sends this authorization_code to Visual Passcodes’ token endpoint to obtain an access_token and id_token.

PKCE (Proof Key for Code Exchange)​

PKCE is a security extension that is mandatory for public clients. It protects against authorization‑code interception.

It works like this:

  1. Your app creates a secret string called the code_verifier.
  2. It derives a code_challenge from the code_verifier (typically using SHA‑256).
  3. The code_challenge is sent in the initial authorization request.
  4. When your app exchanges the authorization_code for tokens, it must also send the original code_verifier.
  5. Visual Passcodes verifies that the code_verifier matches the code_challenge from the first step before issuing tokens.