Gataca Vouch Integration

This document explains how Gataca Vouch works and how to integrate it into a third party application.

Introduction

Gataca Vouch is a product within Gataca Studio that helps organizations (hereto referred as Service Provider) verify the identity and other information of their end users. It uses standard Open ID Connect (OIDC) protocols for authentication and allows users to provide their information through ID Wallets and verifiable credentials.

The main difference between Vouch and other federated identity systems like Google, Facebook, X, and LinkedIn is that Vouch does not store users' information. Instead, users control, manage, and store their own identity information.

Solution comparison

Gataca Vouch is used to authenticate users and obtain verified user information using standard authentication protocols. Its primary use case today is the verification that a user is over a certain legal age. The following documentation applies to the age verification use case.

User Flow

Gataca Vouch's main objective is to enable user’s authentication using credentials stored in their ID wallets.

Overview

As depicted in figure 1 above, authentication in a Service Provider’s application would imply the following steps:

1. User requests authentication (steps 1-4)

The user initiates authentication on the Service Provider's website or application by pressing a button such as "Log In" or "Verify Age".

If the user is on a computer, a QR code will appear for them to scan with their ID Wallet. If the user is on a mobile device, the ID Wallet is triggered automatically, eliminating the need to scan a QR code.

Vouch landing

2. User shares necessary identity credentials and gains instant access (steps 5-8)

The ID Wallet displays the credentials the user needs to share. Once the user gives consent, they either gain instant access to the Service Provider's application (if the credentials are valid and authorized) or receive an immediate notification of unauthorized access.

ID Wallet

Integrating Gataca Vouch with your application

To execute these steps, Gataca Vouch communicates with both the user and the Service Provider. This bi-directional flow involves using two different communication protocols.

Vouch architecture

Vouch uses standard OIDC protocols to communicate with the Service Provider's systems.

OpenID Connect (OIDC) is an authentication protocol and identity layer on top of OAuth 2.0 used in many SSO solutions and adopted by many social logins (Google, Apple, Facebook, LinkedIn, etc). Its design focuses on security, flexibility, user experience, and interoperability. Together with its strong ecosystem support, makes it a powerful and versatile protocol for managing authorization across many applications and services. These qualities have led to its widespread acceptance and implementation worldwide.

On the other hand, Gataca Vouch uses OpenId4VP protocol to communicate with the end user’s Wallet.

OpenIDC4VP is the protocol officially accepted in the European Commission’s technical specifications for the European ID Wallet, and gaining strong popularity in other regions.

This architecture allows Service Providers to quickly and easily integrate their applications using widespread OIDC protocols without the need to understand Wallet-specific protocols.

You may use any commercial OIDC client to execute the integration, so you only need to configure the scopes and redirect URIs. A list of available OIDC clients can be found here.

1. Choose your OAuth 2.0 Flow

OIDC is a highly flexible protocol that supports various authentication flows. For using Gataca Vouch, we recommend the following flows:

Flow type	System architecture	When to choose this flow
Authorization Code Flow	Server-side web applications that can securely store a client secret.	Use this flow to ensure high security by keeping tokens and client secrets away from the user's browser.
Implicit Flow	Single-page applications (SPAs), where the application cannot securely store a client secret.	Opt for this flow for client-side applications needing immediate access to tokens.
Hybrid Flow	Applications requiring both immediate access and enhanced security.	Utilize this flow to combine the benefits of both the Authorization Code Flow and the Implicit Flow.

By following these guidelines, you can choose the appropriate OAuth 2.0 flow for your application's specific needs, ensuring secure and efficient authentication and authorization.

Authorization Code Flow

The Authorization Code Flow is a secure OAuth 2.0 flow primarily designed for server-side web applications. It involves a two-step process to obtain an access token and, optionally, a refresh token. This flow ensures that the client secret and tokens are never exposed to the user's browser, enhancing security.

Phases:

1. User Authorization: The user is redirected to the authorization server, where they log in and grant the application permission to access their resources.

2. Authorization Code: Upon successful authentication, the authorization server redirects the user back to the application with an authorization code.

3. Token Exchange: The application server exchanges the authorization code for an access token (and optionally a refresh token) by making a secure request to the authorization server, including the client secret.

Authorization Code flow

1. The user requests access to a restricted area (e.g. restricted to adults only +18, or log-in to an account) in a Service Provider’s Website.

2. The Website delegates identity verification to Gataca Vouch, redirecting the browser to a gataca.io domain

3. The browser requests specific authentication scopes predefined by the Service Provider on the Gataca Vouch administration platform

4. Gataca requests to the user’s ID Wallet the minimum necessary verifiable credentials to gather the information that will answer the scope. This request can be triggered using QR codes, dynamic links, or NFC technology.

5. Once the user shares these credentials with Gataca, Gataca validates their authenticity along with several other security checks and processes the information. If the validation is successful, Gataca returns an Authorization Code back to the web app, or an empty token if the validation is not successful.

6. Once the verification has been performed and the Authorization Code is received, the Web App requests for its Access Token.

7. Gataca generates the Access Token with the requested scopes (accordingly to the information received). This Access Token is sent to the Website.

8. The Website requests the user information to Gataca Vouch (/userdata).

9. Gataca Vouch provides user information in the form of an ID Token. This token contains all the details specified in the requested scopes.

Implicit Flow

The Implicit Flow is an OAuth 2.0 flow designed for client-side applications where the client secret cannot be securely stored. It simplifies the process by obtaining tokens directly from the authorization server without an intermediate authorization code exchange.

Phases:

1. User Authorization: The user is redirected to the authorization server, where they log in and grant the application permission to access their resources.

2. Token Directly Returned: Upon successful authentication, the authorization server redirects the user back to the application with an access token (and optionally an ID token) directly included in the URL fragment.

Implicit flow

1. The user requests access to a restricted area (e.g. restricted to adults only +18, or log-in to an account) in a Service Provider’s website.

2. The website delegates identity verification to Gataca Vouch, redirecting the browser to a gataca.io domain

3. The browser requests specific authentication scopes predefined by the Service Provider on the Gataca Vouch administration platform

4. Gataca requests to the user’s ID Wallet* the minimum necessary verifiable credentials to gather the information that will answer the scope. This request can be triggered using QR codes, dynamic links, or NFC technology.

5. Once the user shares these credentials with Gataca, Gataca validates their authenticity along with several other security checks and processes the information. If the validation is successful, Gataca returns an Authorization Code back to the web browser, or an empty token if the validation is not successful.

Hybrid flow

The Hybrid Flow is an OAuth 2.0 flow that combines elements of both the Authorization Code Flow and the Implicit Flow. This flow provides a more flexible approach, offering the benefits of immediate token access along with the enhanced security of an authorization code exchange.

Phases:

• User Authorization: The user is redirected to the authorization server, where they log in and grant the application permission to access their resources.

• Tokens and Authorization Code: Upon successful authentication, the authorization server redirects the user back to the application with an authorization code and, optionally, an access token and/or ID token.

• Token Exchange: The application can use the authorization code to request additional tokens (if not already provided) by making a secure request to the authorization server, including the client secret.

2. Integrate Vouch in your application

Once the Client ID has been defined, you should connect to your application, so depending on the OIDC client you are using, it's possible to use configure in different ways.

In all the cases it's necessary to fill up this fields:

• IDP host: It is the base URL of Gataca Vouch that is responsible for authenticating users. The IdP host handles the authentication process and issues tokens (such as access tokens and ID tokens) upon successful authentication.

  Example: https://vouch.gataca.io

• Client ID: It is a unique identifier assigned to a client application by Gataca Vouch when the application is registered. It is used to identify the application making the authentication request.

  Example: abc123xyz

• Client Secret: It is a confidential string that is used by the client application to authenticate itself to Gataca Vouch. It is used in conjunction with the Client ID and should be kept secure.

  Example: shhh-its-a-secret

• Redirect URI: It is the URL to which Gataca Vouch redirects the user after they have authenticated and authorized the client application. It is where the authorization code or tokens are sent. This URL must be registered with the Gataca Vouch to prevent redirection attacks.

  Example: https://myapp.example.com/oauth/callback

• Scope: It specifies the level of access that the client application is requesting. It defines the permissions that the client application is seeking from the user. Scopes are specified as a space-delimited list of strings.

  Example: openid over18

• Response Mode: It specifies how the authorization response is formatted and returned to the client application. Common response modes include query, fragment, and form_post.

  • query: The response parameters are returned in the query string of the redirect URI.

  • fragment: The response parameters are returned in the fragment portion of the redirect URI.

  • form_post: The response parameters are returned as HTML form values that are auto-submitted in the user's browser.

  Example: query

• Response Type: It determines the type of authorization flow the client application is initiating and what type of response it expects from Gataca Vouch. Common response types include:

  • code: Indicates that the client application is using the Authorization Code Flow, expecting an authorization code.

  • token: Indicates that the client application is using the Implicit Flow, expecting an access token.

  • id_token: Indicates that the client application is using OpenID Connect to obtain an ID token.

  • code token: Indicates that the client application is using a hybrid flow to receive both an authorization code and an access token.

  • code id_token: Indicates that the client application is using a hybrid flow to receive both an authorization code and an ID token.

  Example: code

---

Reference implementation

React-based and Nginx-Based implementation: https://github.com/gataca-io/ageverification-demo