Getting started with Vouch

1. Overview

This guide shows an example on how to configure an OIDC-compliant client to authenticate users through Vouch, Gataca Identity Provider (IdP). The steps below assume that the client has already been registered and has received their credentials (client_id and client_secret) along with their configured redirect_uri. (Configuring Vouch).

It also asumes a prior knowledge and understanding of OIDC: for a more complete description of the protocol and its configurations, please refer to the technical documentation.

Among others, Vouch supports the Authorization Code Flow, and is fully compliant with the OpenID Connect 1.0 standard.

2. Endpoints

Vouch exposes the following OIDC endpoints:

We recommend that clients use the Discovery Document to automatically configure endpoints.

3. Using an OIDC Client Library

If you are using a standard OIDC client library — such as openid-client in Node.js, python-oidc, spring-security-oauth2, or similar — you do not need to manually implement the authorization flow (redirects, token exchanges, validations, etc.).

These libraries take care of:

• Redirecting the user to the authorization endpoint.

• Handling the callback and exchanging the authorization code for tokens.

• Validating the ID token, including signature and claims (like iss, aud, exp, etc.).

• Optionally retrieving user information via the userinfo endpoint.

• Managing session state, token storage, and refresh logic.

All you need to do is configure the library with the correct settings from Vouch:

Setting
Value

OIDC Provider URL

Client ID

Provided during registration

Client Secret

Provided during registration

Redirect URI

Must match what was registered (e.g., https://app.example.com/callback)

Response Type

code

Grant Type

authorization_code

Scopes

openid (minimum), optionally legalAge, email, ...

Example (Node.js)

javascript
const { Issuer } = require('openid-client');

(async () => {
  const issuer = await Issuer.discover('https://vouch.gataca.io');

  const client = new issuer.Client({
    client_id: 'your-client-id',
    client_secret: 'your-client-secret',
    redirect_uris: ['https://yourapp.com/callback'],
    response_types: ['code'],
  });

  // Use client.authorizationUrl() and client.callback() as needed
})();

By relying on the client library, you avoid dealing with protocol-level details, reduce errors, and follow security best practices by default.

Make sure the library you use supports OIDC Discovery and follows the OIDC Core 1.0 spec.

Last updated