Related Guides

This tutorial is currently not available in Ruby. Choose another language.

Set up authentication to make API calls to Virgil Services

This guide shows how to set up authentication using tokens that are based on the JSON Web Token standard but with some Virgil modification.

In order to make call to Virgil Services (for example, to publish user's Card on Virgil Cards Service), you need to have a JSON Web Token ("JWT"). Virgil SDKs let you use Virgil token-generation functionality without having to know how they're constructed.

Prerequisites for work

Install SDK and Setup Virgil Crypto

This language is only suitable for Server side.

# this language is not supported yet.

Collect your Virgil developer credentials

A unique string value that identifies your account at the Virgil developer portal

API_KEY

A Private Key that is used to sign API calls to Virgil Services. For security, you will only be shown the API Private Key when the key is created. Don't forget to save it in a secure location for the next step

To show how and why JWT is actually used, we will use a simple 3 entity example (see the below diagram). The entities in this example are the User, the Application server, and the Virgil Cards Service. The authentication server will provide the JWT to the user. With the JWT, the user can then safely communicate with the Virgil Services.

In this example, the user first signs into the Application server using the authentication server’s login system (e.g. username and password, Facebook login, Google login, etc). The Application server then creates the JWT and sends it to the user. When the user makes API calls to the Virgil Cards Service, the user passes the JWT along with the API call. The Cards Service is configured to verify that the incoming JWT is created by the Application server. So, when the user makes API calls with the attached JWT, Virgil can use the JWT to verify that the API call is coming from an authenticated user.

Let's see how we can set up authentication:

first, we'll set up a client side for sending JWT requests to a server side

second, we'll set up a server side with your Virgil account credentials and generate a JWT

Set up Client side and send a JWT request

After a user installs Virgil SDK you'll need to set up jwtProvider for providing a user with a JWT. You'll need to give your users a JWT that tells Virgil who they are and what they can do.

Requests to your app server must be authorized. You can use any kind of authentication, for example, Google auth.

Set up JWT provider

Use these lines of code to specify which JWT generation source you prefer to use in your project:

# this language is not supported yet.

Set up Server Side and Generate JWT

Next, you'll set up the JwtGenerator and generate a JWT using the Virgil SDK.

You'll use your API Key that was created at Virgil Dashboard. For security purposes, you have to generate JWT on your server side.

Each JWT is granted access to specific Application and has a limited lifetime that is configured by you. However, best practice is to generate JWT for the shortest amount of time feasible for your application.

Here is an example of how to generate a JWT:

# this language is not supported yet.

Manage a JWT

Each JWT consists of three parts: the header, the payload, and the signature.

// JWT Token structure
header.payload.signature

1. Header

The header contains information about how the JWT signature should be computed. The header is a JSON object in the following format:

{
// the type of token. It MUST be "JWT"
"typ": "JWT",
// Signature algorithm. Currently supports only "VEDS512" (Virgil EdDSA SHA512)
"alg": "VEDS512",
// the content-type. It MUST be "virgil-jwt;v=1
"cty": "virgil-jwt;v=1"
// fingerprint of public key, that will be used to verify token. Equals to first 8 bytes of SHA512 of Public Key in DER format
"kid": "70b447e321f3a0fd",
}

2. Payload

The payload is the data that‘s stored inside the JWT (this data is also referred to as the “claims” of the JWT). In our example, the Application server creates a JWT with the user information stored inside of it.

Keep in mind that the size of the data will affect the overall size of the JWT. This generally isn’t an issue but having excessively large JWT may negatively affect performance and cause latency.

3. Signature

The signature section is a signed hash that serves to prove the authenticity of the token. It is compiled by hashing the JWT header and payload together with your API Key secret, which should only be known to your application and Virgil.

base64url encodes the header and the payload that was created in steps 1 and 2. The algorithm then joins the resulting encoded strings together with a period (.) in between them. To get the JWT signature, the data string is hashed with the secret key using the hashing algorithm specified in the JWT header.

Then, using the joined encoded header and payload and applying the specified signature algorithm(HS256) on the data string with the secret key set as the string “secret”, we get the JWT Signature.

Now that we have created all three components, we can create the JWT. Remembering the header.payload.signature structure of the JWT, we simply need to combine the components with periods (.) separating them. We use the base64url encoded versions of the header and of the payload, and the signature.

It is important to understand that the purpose of using JWT is NOT to hide or obscure data in any way. The reason why JWT is used is to prove that the sent data was actually created by an authentic source.