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:
Discovery Document
Authorization
User Info
JWKS (public keys)
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:
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)
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.
Last updated