How to configure Certify

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

Setting up the component

Once the Certify Component has been deployed (and also the Admin component), the administrator should configure the Certify component through the Admin. So, the administrator should access 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.

 

License Token screen

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 Certify component that can be obtained using the command below.

curl --request GET 'https://[CERTIFY_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://[CERTIFY_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:

  • Credentials

  • Issuances

  • 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 '[CERTIFY_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.

Issuances (tenants)

This section allows administrators to configure the specific Issuance process requirements for a given Credential type.

Note: each Issuance Configuration in Certify sets up a new tenant. Therefore, when configuring Certify, the concept of tenant ID = Issuance ID.

Note: each Issuance Configuration in Certify sets up a new tenant. Therefore, when configuring Certify, the concept of tenant ID = Issuance ID.

When the administrator accesses this menu for the first time, this section is empty. The administrator should create a new Issuance Configuration.

Configuring a new Issuance process using the Admin Panel

A new Issuance Configuration must be performed in three steps:

  • Basic Information

  • Credentials

  • Security Mechanisms

Generic settings

The administrator should configure:

  • Issuance ID - the name for this specific Issuance process (e.g. AcademicDiplomaAwesomeMaster)

  • DID - the DID that will appear as the issuer (signatory) of the credentials issued through this process (note: an organization may have multiple DIDs, one for each business unit)

  • Domain - the domain of the Certify server

  • eIDAS Qualified Signature - Whether credentials issued through this process will be signed with an eIDAS qualified certificate (note: eIDAS certificates can be configured from the generic Certify Settings

  • Polling - Deprecated. It will be removed in the next Admin Panel version

  • Feedback - it is the feedback provided to the user once he/she requests the issuance of the credential. This can be one of two options:

    • A push notification to the user’s Wallet

    • A hook - that is a service endpoint to launch callbacks upon session completion

Credentials

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.

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.

In this step, the administrator configures three different sections:

  1. Credential Group - the administrator selects here the Credential Group from the Registry for which this issuance process will apply.

  2. Claims in Credential Group - which claims included in a Credential Group will be issued in this process (e.g. a Credential Group Academic Diploma may have ten generic claims in its schema, but in this issuance process, the administrator is configuring the issuance of a specific master diploma that will only use 6 of the available claims)

  3. Requested Claims - that is, which credentials that the user shall already have in his/her wallet will be requested for authentication purposes (e.g. a Verifiable ID or email) previous to the issuance of this new Credential.

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 authnfactor 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 Issuance process using APIs

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

Note: Please refer to the previous section (Configuring a new Issuance process using the Admin Panel) to see full descriptions of each parameter.

Note: Please refer to the previous section (Configuring a new Issuance process using the Admin Panel) to see full descriptions of each parameter.

Apps

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

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 Certify.

Note: Before creating a new App, it’s preferable to create a new Issuance Configuration and attach the Issuance Configuration created in that step.

Note: Before creating a new App, it’s preferable to create a new Issuance Configuration and attach the Issuance Configuration created in that step.

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 Certify

  2. Password - a password to protect this connection

  3. Tenants - The tenants (issuance processes) 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 is, the Issuance Process ID) that the App will be authorized to use and the role for that app (In Certify, the role must always ISSUER).

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

Credentials

When the administrator accesses it for the first time, this section is empty. In this section, the administrator will visualize the list of credentials that have been issued with this Certify instance.