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:

Purpose	Endpoint URL
Discovery Document	https://vouch.gataca.io/.well-known/openid-configuration
Authorization	https://vouch.gataca.io/oauth2/auth
Token	https://vouch.gataca.io/oauth2/token
User Info	https://vouch.gataca.io/userinfo
JWKS (public keys)	https://vouch.gataca.io/.well-known/jwks.json

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	https://vouch.gataca.io
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.