How to configure Connect

Owned by Esther Saurí
Last updated: May 18, 2023
8 min read

Setting up the component

Once the Connect Component has been deployed (and also the Admin component), the administrator should configure the Connect component through the Admin. So, the administrator should access to the admin panel, and then the configuration screen is shown.

Configuration Screen

 If it’s the first time the client configures the component, Gataca recommends selecting the 'automatic configuration.’ This configuration allows the administrator to access and configure the component easily.

Automatic configuration

When an administrator clicks on Automatic configuration, the screen below is shown. In this screen, the administrator must enter the ‘License Token’ provided by Gataca.

Note: The license token is a JWT token with, commonly, 24 hours to be used. Please contact help@gataca.io to receive your license token.

Note: The license token is a JWT token with, commonly, 24 hours to be used. Please contact help@gataca.io to receive your license token.

Then the administrator clicks on Autoconfigure button, and the process is launched. Once the process has been executed, it’s time to create the first administrator account.

Create the first administrator account

Just for the first time, we must create a new Admin user. For this purpose, the administrator must get a Registration Token provided by the Connect component that can be obtained using the command below.

curl --request GET 'https://[CONNECT_URL]/admin/v1/users/status' \ --data-raw ''

Just for the first time, as there is no administrator account created yet, the service provides a token to register the first account. So, when the request is triggered, the server returns an error code (503 Service Unavailable) with a token in the headers.

The administrator must use that token to create the first admin account.

curl --request POST 'https://[CONNECT_URL]/admin/v1/users' \ --header 'Authorization: jwt [TOKEN]' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "[ADMIN_USER]","password":"[ADMIN_USER_PASSWORD]"}'

At this point, the administrator can sign in to the Administrator Panel.

Note: Avoid using the 'Easy Login' authenticator until Gataca support suggests it.

Note: Avoid using the 'Easy Login' authenticator until Gataca support suggests it.

Configuring menu items

The administrator shall have access to the following menu:

  • Tenants

  • Apps

  • Access Management

Access Management

At this point, the administrator should be able to see the admin user created in the previous step for the first admin user.

Administrators may have two roles:

  • Administrator - they have no restrictions

  • Tenant administrators - they can only see and manage specific Tenants listed in the Tenants section

Creating additional administrators via de Admin Panel

The administrator can create as many new administrators as desired via the New Role button on the top right corner.

Using the administrator panel, the current administrator must enter information about the new username, the password, and the role used by this new user.

Creating additional administrators via APIs

Using the API, two different commands must be executed to create a new User.

The first command is to create a token to register a new user. In this command, it is necessary to indicate the tenant where the new user will be attached (by default: Admin) and the role for that user (by default: ADMIN).

curl --request GET '[CONNECT_HOST]/admin/v1/token/register?tenant=Admin&role=ADMIN' \ --header 'Authorization: jwt [TOKEN]' \ --data-raw ''

The second command is used to create the new administrator using the token previously generated.

Tenants

Each tenant defines a set of authentication requirements. That is, for each different Presentation Request (a set of Verifiable Credentials requested from a user for authentication or application requirements), a new tenant should be configured.

When the administrator accesses this menu for the first time, this section is empty. The administrator should create a new Tenant via the blue button on the top right corner.

Note: By default, a tenant with ID “Admin” is created during the installation process.

Note: By default, a tenant with ID “Admin” is created during the installation process.

Configuring a new Issuance process using the Admin Panel

A new Issuance Configuration must be performed in three steps:

  • Basic Information

  • Credentials

  • Security Mechanisms

Basic information

  • Tenant ID - A name for tenant (e.g. MasterApplication)

  • DID - The DID that the user will see as associated with the Service Provider (an organization may have several DIDs, for each business unit)

  • Domain – The domain for the Connect server

Credential Configuration

The administrator configures in this section the claims that will be requested from the user for this specific authentication process. That is, the administrator configures the Presentation Request.

The administrator may add as many credentials as desired from the Add Credentials drop-down menu at the bottom of the page.

Note: At Gataca we work with mono-claim credentials in order to enable selective disclosure. We group Credentials in what we call Credential Groups for better user experience. As such, an Academic Diploma is a Credential Group composed of multiple Verifiable Credentials, each of then containing one single claim. Administrators may select in this menu specific claims, not entire Credential Groups.

Note: At Gataca we work with mono-claim credentials in order to enable selective disclosure. We group Credentials in what we call Credential Groups for better user experience. As such, an Academic Diploma is a Credential Group composed of multiple Verifiable Credentials, each of then containing one single claim. Administrators may select in this menu specific claims, not entire Credential Groups.

Administrators may, for each requested credential, select the required security level. That is, whether it will be mandatory or not and the purpose for requesting this information.

Note: there are 3 security levels:

  • Level 0 - self-attested credentials

  • Level 1 - credentials validated by a third party (e.g. a KYC provider)

  • Level 2 - credentials validated by its legitimate/authoritative issuer

Note: there are 3 security levels:

  • Level 0 - self-attested credentials

  • Level 1 - credentials validated by a third party (e.g. a KYC provider)

  • Level 2 - credentials validated by its legitimate/authoritative issuer

Finally, for each requested claim, the administrator shall choose the legal purpose for the request. There are currently five available purposes:

  • Authentication

  • Non Repudiation (for contractual purposes)

  • Regulation

  • Application logic (for the provisioning of the service)

  • Analysis (for analytic purposes)

  • Third Party sharing (to share it with third parties)

Security Mechanisms

The security mechanisms offered by Gataca are additional security measures designed to help the enforcement and tracking of frequent authentication operations. The possible mechanisms available are:

  1. AppAuthentication: guarantee a request comes from a legit Gataca Wallet application. This relies on signing specific information with a key securely embedded in the application.

  2. AuthNFactor: authNFactors aim to be an adaptation of FIDO-U2F second factors to the Verifiable Credentials standard model. authNFactors are a specific type of verifiable credentials with the following properties:

    1. They always have trust level 1 validated by Gataca

    2. They contain a public key

    3. The matching private key is securely stored on the device with the Gataca Wallet.

    4. In order to retrieve the private key, a specific operation associated with each auth factor must be performed. When selecting an authNfactor as a security mechanism, the CONNECT application will receive as proof that the required operation has successfully performed a challenge signed with the corresponding private key.

    At the moment, there are four implemented authentication factors:

    1. Biometric authentication

    2. Silent authentication (requires no other user input than having the wallet currently opened)

    3. OTP SMS

    4. OTP email

Configuring a new Tenant process using APIs

Using the API, the following command must be executed to create the new Tenant configuration.

  • CONNECT_HOST: URL where Connect has been deployed

  • TENANT_ID: Tenant identifier. It’s a free text identifier.

  • DID: It must be one of the DIDs that belong to Connect.

  • credentials: Section to write the configuration for each VC requested. In this example, it’s being requested an email.

  • security: Section to write the configuration for each N-Factor. In this case, the section is empty. This feature is recommended for advanced users.

Administrators will be able to include the Presentation Request credentials included in the public catalog. Available credentials can be retrieved using this API.

Apps

An App refers to any backend system that the Administrator wants to integrate with Connect. This integration requires the configuration of a new App in Connect.

When the administrator accesses it for the first time, this section is empty. The administrator should create a new App to integrate the client systems with Connect.

Note: Before creating a new App, it’s preferable to create a new Tenant Configuration and attach the Tenant created in that step. By default, Connect creates a tenant called Admin.

Note: Before creating a new App, it’s preferable to create a new Tenant Configuration and attach the Tenant created in that step. By default, Connect creates a tenant called Admin.

Configuring a new App via de Admin Panel

The administrator can create as many new Apps as desired via the New App button on the top right corner.

Using the administrator panel, the current administrator must enter the following information:

  1. Application ID - An name for the App that represents the backend system to be integrated with Connect

  2. Password - a password to protect this connection

  3. Tenants - The tenants that this App will be authorized to use

Configuring a new App via APIs

Using the API, two different commands must be executed to create a new App.

The first command is executed to get a token to register a new App. In this command, it is necessary to indicate the tenant ID that the App will be authorized to use and the role for that app (In Connect, the role must always SERVICE_PROVIDER).

The second command is to create the app using the token previously generated.