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") that contains the user's identity which is a string that uniquely identifies each user in your application. For this tutorial we'll assume that your user records have a unique ID assigned by the database, known as uid, and we will use that as their identity.

Prerequisites for work

Install SDK and Setup Virgil Crypto

The Virgil С++ SDK is provided as a package named virgil_sdk.

Requirements

C++11 compatible compiler
CMake 3.10+

Virgil С++ SDK can be integrated using CMake in different ways.

One of them is to use custom CMake util You can find file called virgil_depends_local.cmake at sdk-cpp/cmake/utils. This is an in-house dependency loader based on pure CMake features.

Usage:

Create cmake configuration file for target dependency

cmake_minimum_required (VERSION @CMAKE_VERSION@ FATAL_ERROR)

project ("@VIRGIL_DEPENDS_PACKAGE_NAME@-depends")

include (ExternalProject)

# Configure additional CMake parameters
file (WRITE "@VIRGIL_DEPENDS_ARGS_FILE@"
"set (ENABLE_TESTING OFF CACHE INTERNAL \"\")\n"
"set (INSTALL_EXT_LIBS ON CACHE INTERNAL \"\")\n"
"set (INSTALL_EXT_HEADERS ON CACHE INTERNAL \"\")\n"
"set (UCLIBC @UCLIBC@ CACHE INTERNAL \"\")\n"
)

ExternalProject_Add (${PROJECT_NAME}
DOWNLOAD_DIR "@VIRGIL_DEPENDS_PACKAGE_DOWNLOAD_DIR@"
URL "https://github.com/VirgilSecurity/sdk-cpp/archive/v5.0.0.tar.gz"
URL_HASH SHA1=
PREFIX "@VIRGIL_DEPENDS_PACKAGE_BUILD_DIR@"
CMAKE_ARGS "@VIRGIL_DEPENDS_CMAKE_ARGS@"
)

add_custom_target ("${PROJECT_NAME}-build" ALL COMMENT "Build package ${PROJECT_NAME}")
add_dependencies ("${PROJECT_NAME}-build" ${PROJECT_NAME})

In the project, add the following code

include (virgil_depends)

virgil_depends (
PACKAGE_NAME "virgil_sdk"
CONFIG_DIR "${CMAKE_CURRENT_SOURCE_DIR}/dir_to_config_file_from_step_1"
)

virgil_find_package (virgil_sdk)

The Virgil .NET SDK is provided as a package named Virgil.SDK. The package is distributed via NuGet package management system.

Supported Platforms:

- .NET Standard 1.1+
- .NET Framework 4.5+
- .NET Core 1.0+
- Universal Windows Platform 10
- Windows 8.0+
- Windows Phone 8.1+
- Xamarin.Android 7.0+
- Xamarin.iOS 10.0+
- Mono 4.6+ for x86-64(AMD64)

Installing the package using Package Manager Console:

Run PM> Install-Package Virgil.Crypto
Run PM> Install-Package Virgil.SDK

This language is only suitable for the Server Side.

The Virgil Go SDK is provided as a package named virgil. The package is distributed via github.

The package is available for Go 1.10 or newer.

Installing the package:

go get -u gopkg.in/virgil.v5/...

Crypto library notice

The built in crypto library supports only following primitives:

ED25519 keys
SHA512 hashes
AES256_GCM encrypting

and is not recommended for production use.

On linux and macOS consider using external crypto library written in c++

Using external crypto library (c++)

If you are building from sources, install prerequisites as described here. and then

go get -u -d gopkg.in/virgilsecurity/virgil-crypto-go.v5
cd $(go env GOPATH)/src/gopkg.in/virgilsecurity/virgil-crypto-go.v5
make

If you use Linux x64 or Darwin x64 architecture, you can use the pre-built crypto binaries

for Linux:

CRYPTO_LIB=virgil-crypto-2.4.4-go-linux-x86_64.tgz

for MacOS

CRYPTO_LIB=virgil-crypto-2.4.4-go-darwin-17.4-x86_64.tgz

and then

go get -u -d gopkg.in/virgilsecurity/virgil-crypto-go.v5
wget https://cdn.virgilsecurity.com/virgil-crypto/go/$CRYPTO_LIB
tar -xvf $CRYPTO_LIB --strip-components=1 -C $(go env GOPATH)/src/gopkg.in/virgilsecurity/virgil-crypto-go.v5/

in your source code use crypto objects from this library as follows:



import (
    "gopkg.in/virgilsecurity/virgil-crypto-go.v5"
)

var (
    crypto      = virgil_crypto_go.NewVirgilCrypto()
    cardCrypto  = virgil_crypto_go.NewVirgilCardCrypto()
    tokenSigner = virgil_crypto_go.NewVirgilAccessTokenSigner()
)

The Virgil Java SDK is provided as a package named com.virgilsecurity.sdk. The package is distributed via Maven repository.

The package is available for:

Java 7 and newer
Android API 16 and newer

Prerequisites:

Java Development Kit (JDK) 7+
Maven 3+

You can easily add SDK dependency to your project, just follow the examples below.

Maven

Apache Maven is a software project management and comprehension tool.

To integrate Virgil SDK into your Java project using Maven, set up dependencies in your pom.xml:


    
        com.virgilsecurity.sdk
        crypto
        5.0.2
    
    
        com.virgilsecurity.sdk
        sdk
        5.0.2

Gradle

Gradle is an open-source build automation system that builds upon the concepts of Apache Ant and Apache Maven and introduces a Groovy-based domain-specific language (DSL) instead of the XML form used by Apache Maven for declaring the project configuration.

Server

To integrate Virgil SDK into your Java project using Gradle, set up dependencies in your build.gradle:

dependencies {
    compile 'com.virgilsecurity.sdk:crypto:5.0.2'
    compile 'com.virgilsecurity.sdk:sdk:5.0.2'
}

Android

To integrate Virgil SDK into your Android project using Gradle, add jcenter() repository if missing:

repositories {
    jcenter()
}

Set up dependencies in your build.gradle:

dependencies {
    compile 'com.virgilsecurity.sdk:crypto-android:5.0.2@aar'
    compile 'com.virgilsecurity.sdk:sdk:5.0.2'
}

Virgil SDK for JavaScript can be used both server-side in a Node.js application, and client-side in a web browser.

NPM

The recommended way is to install from npm, the Node package manager that lets you install the libraries you need. Simply fire up a terminal or command line interface on your machine that already has Node and npm installed, and run the following command in a new directory.

If you want to use Virgil Crypto library, you will also need to install the virgil-crypto package separately.

npm install virgil-sdk virgil-crypto

Important! You will need node.js version >= 6 to use virgil-sdk. If you have a different version, consider upgrade or use nvm (or a similar tool) to install Node.js of supported version alongside your current installation. If you only intend to use virgil-sdk in a browser, you can ignore this warning.

CDN

The pre-built versions of the libraries can also be added to an html page via <script> tag:

For the pre-built versions all name exports of virgil-sdk are available on the Virgil global namespace and all name exports of virgil-crypto on the VirgilCrypto global namespace.

This language is only suitable for the Server Side.

The Virgil SDK is provided as a package named virgil/sdk.

The package is distributed via Composer package management system.

The package is available for PHP version 5.6 and newer.

Installing the package using Package Manager Console:

composer require virgil/sdk virgil/crypto

Be aware virgil/crypto package requires installed php virgil crypto extension ext-virgil_crypto_php.

Get extension from CDN

Also there is avaliable [setup your own Crypto library][_own_crypto] inside of the SDK.

The Virgil Python SDK is provided as a package named virgil_sdk. The package is distributed via pip package manager.

The package is available for:

Python 2.7.x
Python 3.x

Installing the package:

The Virgil Python SDK is provided as a package named virgil_sdk. The package is distributed via Pypi package management system. To install the pip package use the command below:

pip install virgil_sdk

This language is only suitable for the Client Side.

Virgil SDK is provided as a set of frameworks. These frameworks are distributed via Carthage and CocoaPods.

All frameworks are available for:

iOS 9.0+
macOS 10.10+
tvOS 9.0+
watchOS 2.0+

COCOAPODS

CocoaPods is a dependency manager for Cocoa projects. You can install it with the following command:

$ gem install cocoapods

To integrate VirgilSDK into your Xcode project using CocoaPods, specify it in your Podfile:

target '' do
  use_frameworks!

  pod 'VirgilCrypto', '~> 5.0.0-alpha'
  pod 'VirgilSDK', '~> 5.7'
end

Then, run the following command:

$ pod install

Carthage

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.

You can install Carthage with Homebrew using the following command:

$ brew update
$ brew install carthage

To integrate VirgilSDK into your Xcode project using Carthage, create an empty file with name Cartfile in your project's root folder and add following lines to your Cartfile

github "VirgilSecurity/virgil-sdk-x" ~> 5.7
github "VirgilSecurity/virgil-crypto-x" ~> 5.0.0-alpha

Linking against prebuilt binaries

To link prebuilt frameworks to your app, run following command:

$ carthage update --no-use-binaries

This will build each dependency or download a pre-compiled framework from github Releases.

Building for iOS/tvOS/watchOS

On your application targets’ “General” settings tab, in the “Linked Frameworks and Libraries” section, add following frameworks from the Carthage/Build folder inside your project's folder:

VirgilSDK
VirgilCryptoAPI
VirgilCrypto
VirgilCryptoFoundation
VSCCommon
VSCFoundation

On your application targets’ “Build Phases” settings tab, click the “+” icon and choose “New Run Script Phase”. Create a Run Script in which you specify your shell (ex: /bin/sh), add the following contents to the script area below the shell:

/usr/local/bin/carthage copy-frameworks

and add the paths to the frameworks you want to use under “Input Files”, e.g.:

$(SRCROOT)/Carthage/Build/iOS/VirgilSDK.framework
$(SRCROOT)/Carthage/Build/iOS/VirgilCryptoAPI.framework
$(SRCROOT)/Carthage/Build/iOS/VirgilCrypto.framework
$(SRCROOT)/Carthage/Build/iOS/VirgilCryptoFoundation.framework
$(SRCROOT)/Carthage/Build/iOS/VSCCommon.framework
$(SRCROOT)/Carthage/Build/iOS/VSCFoundation.framework

Building for macOS

On your application targets’ “General” settings tab, in the “Embedded Binaries” section, drag and drop following frameworks from the Carthage/Build folder on disk:

VirgilSDK
VirgilCryptoAPI
VirgilCrypto
VirgilCryptoFoundation
VSCCommon
VSCFoundation

Additionally, you'll need to copy debug symbols for debugging and crash reporting on macOS.

On your application target’s “Build Phases” settings tab, click the “+” icon and choose “New Copy Files Phase”. Click the “Destination” drop-down menu and select “Products Directory”. For each framework, drag and drop corresponding dSYM file.

Integrating as subproject

It is possible to use carthage just for fetching right sources for further integration into your project. Run following command:

$ carthage update --no-build

This will fetch dependencies into a Carthage/Checkouts folder inside your project's folder. Then, drag and drop VirgilCrypto.xcodeproj, VirgilCryptoAPI.xcodeproj and VirgilSDK.xcodeproj from corresponding folders inside Carthage/Checkouts folder to your Xcode Project Navigator sidebar.

Next, on your application targets’ “General” settings tab, in the “Embedded Binaries” section add following frameworks from subprojects:

VirgilSDK
VirgilCryptoAPI
VirgilCrypto
VirgilCryptoFoundation
VSCCommon
VSCFoundation

Collect your Virgil developer credentials

Parameter	Description
APP_ID	ID of your Application at Virgil Dashboard
API_KEY_ID	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.

JSON WEB TOKEN Generation

You can use any string value for the user identity as long as it's unique for each user. However, for security reasons, avoid using fields that contain any personally identifiable information such as name or email address, especially if your product needs to comply with regulations such as HIPAA and GDPR.

JWTs must be generated on the server side for several reasons:

each JWT must be signed with your Virgil API Key to prove it was issued by you,
the client side should not have access to your sensitive API Key and
you need to authenticate the user making the request to get their identity.

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

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:

#include 

using virgil::sdk::jwt::TokenContext;
using virgil::sdk::jwt::providers::CachingJwtProvider;

// Get generated token from server-side
auto authenticatedQueryToServerSide = [&](const TokenContext& context) {
    std::promise p;
    p.set_value("");

    return p.get_future();
};

// Setup AccessTokenProvider
auto provider = std::make_shared(authenticatedQueryToServerSide);

using Virgil.SDK;

// Get generated token from server-side
Func> obtainTokenCallback = async (ctx) =>
{
     var jwtFromServer = await AuthenticatedQueryToServerSide(tokenContext);
     return jwtFromServer;
};

// Setup AccessTokenProvider
var accessTokenProvider = new CallbackJwtProvider(obtainTokenCallback);

package main

import (
    "gopkg.in/virgil.v5/sdk"
)

func main() {
    authenticatedQueryToServerSide := func(context *sdk.TokenContext) (string, error) {
        // Get generated token from server-side
        return "eyJraWQiOiI3MGI0NDdlMzIxZjNhMGZkIiwidHlwIjoiSldUIiwiYWxnIjoiVkVEUzUxMiIsImN0eSI6InZpcmdpbC1qd3Q7dj0xIn0.eyJleHAiOjE1MTg2OTg5MTcsImlzcyI6InZpcmdpbC1iZTAwZTEwZTRlMWY0YmY1OGY5YjRkYzg1ZDc5Yzc3YSIsInN1YiI6ImlkZW50aXR5LUFsaWNlIiwiaWF0IjoxNTE4NjEyNTE3fQ.MFEwDQYJYIZIAWUDBAIDBQAEQP4Yo3yjmt8WWJ5mqs3Yrqc_VzG6nBtrW2KIjP-kxiIJL_7Wv0pqty7PDbDoGhkX8CJa6UOdyn3rBWRvMK7p7Ak", nil
    }

    // Setup AccessTokenProvider
    accessTokenProvider := sdk.NewCachingStringJwtProvider(authenticatedQueryToServerSide)
}

// Get generated token from server-side
final String authenticatedQueryToServerSide =
        "eyJraWQiOiI3MGI0NDdlMzIxZjNhMGZkIiwidHlwIjoiSldUIiwiYWxnIjoiVkVEUzUxMiIsImN0eSI6InZpcmdpbC1qd3Q7dj0xIn0.eyJleHAiOjE1MTg2OTg5MTcsImlzcyI6InZpcmdpbC1iZTAwZTEwZTRlMWY0YmY1OGY5YjRkYzg1ZDc5Yzc3YSIsInN1YiI6ImlkZW50aXR5LUFsaWNlIiwiaWF0IjoxNTE4NjEyNTE3fQ.MFEwDQYJYIZIAWUDBAIDBQAEQP4Yo3yjmt8WWJ5mqs3Yrqc_VzG6nBtrW2KIjP-kxiIJL_7Wv0pqty7PDbDoGhkX8CJa6UOdyn3rBWRvMK7p7Ak";

// Setup AccessTokenProvider
CallbackJwtProvider.GetTokenCallback getTokenCallback = new CallbackJwtProvider.GetTokenCallback() {

        @Override
        public String onGetToken(TokenContext tokenContext) {
                return authenticatedQueryToServerSide;
        }
};
// initialize JWT provider
AccessTokenProvider accessTokenProvider =
        new CallbackJwtProvider(getTokenCallback);

// client.js

import { CachingJwtProvider } from 'virgil-sdk';

const fetchJwt = () => fetch('/virgil-access-token', { credentials: 'same-origin' })
    .then(response => response.text());

const jwtProvider = new CachingJwtProvider(fetchJwt);
// pass jwtProvider as `accessTokenProvider` to the `CardManager` constructor

use Virgil\Sdk\Web\Authorization\CallbackJwtProvider;
use Virgil\Sdk\Web\Authorization\TokenContext;

$authenticatedQueryToServerSide = function (TokenContext $context){
    // Get generated token from server-side
    return "eyJraWQiOiI3MGI0NDdlMzIxZjNhMGZkIiwidHlwIjoiSldUIiwiYWxnIjoiVkVEUzUxMiIsImN0eSI6InZpcmdpbC1qd3Q7dj0xIn0.eyJleHAiOjE1MTg2OTg5MTcsImlzcyI6InZpcmdpbC1iZTAwZTEwZTRlMWY0YmY1OGY5YjRkYzg1ZDc5Yzc3YSIsInN1YiI6ImlkZW50aXR5LUFsaWNlIiwiaWF0IjoxNTE4NjEyNTE3fQ.MFEwDQYJYIZIAWUDBAIDBQAEQP4Yo3yjmt8WWJ5mqs3Yrqc_VzG6nBtrW2KIjP-kxiIJL_7Wv0pqty7PDbDoGhkX8CJa6UOdyn3rBWRvMK7p7Ak";
};

// Setup AccessTokenProvider
$accessTokenProvider = new CallbackJwtProvider($authenticatedQueryToServerSide);

from virgil_sdk.jwt.providers import CallbackJwtProvider

# Get generated token from server-side
def get_token_from_server():
    jwt_from_server = aunthficated_query_to_server(token_context)
    return jwt_from_server

# setup access token
access_token_provider = CallbackJwtProvider(get_token_from_server)

import VirgilSDK

// Get generated token from server-side
let authenticatedQueryToServerSide: ((String) -> Void) -> Void = { completion in
    completion("eyJraWQiOiI3MGI0NDdlMzIxZjNhMGZkIiwidHlwIjoiSldUIiwiYWxnIjoiVkVEUzUxMiIsImN0eSI6InZpcmdpbC1qd3Q7dj0xIn0.eyJleHAiOjE1MTg2OTg5MTcsImlzcyI6InZpcmdpbC1iZTAwZTEwZTRlMWY0YmY1OGY5YjRkYzg1ZDc5Yzc3YSIsInN1YiI6ImlkZW50aXR5LUFsaWNlIiwiaWF0IjoxNTE4NjEyNTE3fQ.MFEwDQYJYIZIAWUDBAIDBQAEQP4Yo3yjmt8WWJ5mqs3Yrqc_VzG6nBtrW2KIjP-kxiIJL_7Wv0pqty7PDbDoGhkX8CJa6UOdyn3rBWRvMK7p7Ak")
}

// Setup AccessTokenProvider
let accessTokenProvider = CallbackJwtProvider { tokenContext, completion in
    authenticatedQueryToServerSide { jwtString in
        completion(jwtString, nil)
    }
}

Set up Server Side and Generate JWT

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

Here is an example of how to generate a JWT:

#include 
#include 

using virgil::sdk::jwt::JwtGenerator;
using virgil::sdk::VirgilBase64;
using virgil::sdk::crypto::Crypto;    

// API_KEY (you got this Key at Virgil Dashboard)
auto apiKeyBase64 = "MIGhMF0GCSqGSIb3DQEFDTBQMC8GCSqGSIb3DQEFDDAiBBC7Sg/DbNzhJ/uakTvafUMoAgIUtzAKBggqhkiG9w0CCjAdBglghkgBZQMEASoEEDunQ1yhWZoKaLaDFgjpxRwEQAFdbC8e6103lJrUhY9ahyUA8+4rTJKZCmdTlCDPvoWH/5N5kxbOvTtbxtxevI421z3gRbjAtoWkfWraSLD6gj0=";
auto privateKeyData = VirgilBase64::decode(apiKeyBase64);

// Crypto library imports a private key into a necessary format
auto crypto = std::shared_ptr();
auto apiKey = crypto->importPrivateKey(privateKeyData);

// use your App Credentials you got at Virgil Dashboard:
auto appId = "be00e10e4e1f4bf58f9b4dc85d79c77a"; // APP_ID
auto apiKeyId = "70b447e321f3a0fd"; // API_KEY_ID
int ttl = 60 * 60 * 24; // 1 hour (JWT's lifetime)

// setup JWT generator with necessary parameters:
auto jwtGenerator = JwtGenerator(apiKey, apiKeyId, crypto, appId, ttl);

// generate JWT for a user
// remember that you must provide each user with his unique JWT
// each JWT contains unique user's identity (in this case - Alice)
// identity can be any value: name, email, some id etc.
auto identity = "Alice";
auto aliceJwt = jwtGenerator.generateToken(identity);

// as result you get users JWT, it looks like this: "eyJraWQiOiI3MGI0NDdlMzIxZjNhMGZkIiwidHlwIjoiSldUIiwiYWxnIjoiVkVEUzUxMiIsImN0eSI6InZpcmdpbC1qd3Q7dj0xIn0.eyJleHAiOjE1MTg2OTg5MTcsImlzcyI6InZpcmdpbC1iZTAwZTEwZTRlMWY0YmY1OGY5YjRkYzg1ZDc5Yzc3YSIsInN1YiI6ImlkZW50aXR5LUFsaWNlIiwiaWF0IjoxNTE4NjEyNTE3fQ.MFEwDQYJYIZIAWUDBAIDBQAEQP4Yo3yjmt8WWJ5mqs3Yrqc_VzG6nBtrW2KIjP-kxiIJL_7Wv0pqty7PDbDoGhkX8CJa6UOdyn3rBWRvMK7p7Ak"
// you can provide users with JWT at registration or authorization steps
// Send a JWT to client-side
auto jwtString = aliceJwt.stringRepresentation();

using Virgil.Crypto;
using Virgil.SDK;

// API_KEY (you got this Key at Virgil Dashboard)
var apiKeyBase64 = "MIGhMF0GCSqGSIb3DQEFDTBQMC8GCSqGSIb3DQEFDDAiBBC7Sg/DbNzhJ/uakTvafUMoAgIUtzAKBggqhkiG9w0CCjAdBglghkgBZQMEASoEEDunQ1yhWZoKaLaDFgjpxRwEQAFdbC8e6103lJrUhY9ahyUA8+4rTJKZCmdTlCDPvoWH/5N5kxbOvTtbxtxevI421z3gRbjAtoWkfWraSLD6gj0=";
var privateKeyData = Bytes.FromString(appKeyBase64, StringEncoding.BASE64);

// Crypto library imports a private key into a necessary format
var crypto = new VirgilCrypto();
var apiKey = crypto.ImportPrivateKey(privateKeyData, appKeyPassword);

//  initialize accessTokenSigner that signs users JWTs
var accessTokenSigner = new VirgilAccessTokenSigner();

// use your App Credentials you got at Virgil Dashboard:
var appId = "be00e10e4e1f4bf58f9b4dc85d79c77a"; // APP_ID
var apiKeyId = "70b447e321f3a0fd"; // API_KEY_ID
var ttl = TimeSpan.FromHours(1); // 1 hour (JWT's lifetime)

// setup JWT generator with necessary parameters:
var jwtGenerator = new JwtGenerator(appId, apiKey, apiKeyId, ttl, accessTokenSigner);

// generate JWT for a user
// remember that you must provide each user with his unique JWT
// each JWT contains unique user's identity (in this case - Alice)
// identity can be any value: name, email, some id etc.
var identity = "Alice";
var aliceJwt = jwtGenerator.GenerateToken(identity);

// as result you get users JWT, it looks like this: "eyJraWQiOiI3MGI0NDdlMzIxZjNhMGZkIiwidHlwIjoiSldUIiwiYWxnIjoiVkVEUzUxMiIsImN0eSI6InZpcmdpbC1qd3Q7dj0xIn0.eyJleHAiOjE1MTg2OTg5MTcsImlzcyI6InZpcmdpbC1iZTAwZTEwZTRlMWY0YmY1OGY5YjRkYzg1ZDc5Yzc3YSIsInN1YiI6ImlkZW50aXR5LUFsaWNlIiwiaWF0IjoxNTE4NjEyNTE3fQ.MFEwDQYJYIZIAWUDBAIDBQAEQP4Yo3yjmt8WWJ5mqs3Yrqc_VzG6nBtrW2KIjP-kxiIJL_7Wv0pqty7PDbDoGhkX8CJa6UOdyn3rBWRvMK7p7Ak"
// you can provide users with JWT at registration or authorization steps
// Send a JWT to client-side
var jwtString = aliceJwt.ToString();

    // API_KEY (you got this Key at Virgil Dashboard)
    privateKeyStr := []byte("MIGhMF0GCSqGSIb3DQEFDTBQMC8GCSqGSIb3DQEFDDAiBBC7Sg/DbNzhJ/uakTva")

    // Crypto library imports a private key into a necessary format
    privateKey, err := crypto.ImportPrivateKey(privateKeyStr, "")
    if err != nil {
        //handle error
    }

    // use your App Credentials you got at Virgil Dashboard:
    appId := "be00e10e4e1f4bf58f9b4dc85d79c77a" // APP_ID
    apiKeyId := "70b447e321f3a0fd"               // API_KEY_ID
    ttl := time.Hour                            // 1 hour (JWT's lifetime)

    // setup JWT generator with necessary parameters:
    jwtGenerator := sdk.NewJwtGenerator(privateKey, apiKeyId, tokenSigner, appId, ttl)

    // generate JWT for a user
    // remember that you must provide each user with his unique JWT
    // each JWT contains unique user's identity (in this case - Alice)
    // identity can be any value: name, email, some id etc.
    identity := "Alice"
    token, err := jwtGenerator.GenerateToken(identity, nil)

    if err != nil {
        //handle error
    }

    // as result you get users JWT, it looks like this: "eyJraWQiOiI3MGI0NDdlMzIxZjNhMGZkIiwidHlwIjoiSldUIiwiYWxnIjoiVkVEUzUxMiIsImN0eSI6InZpcmdpbC1qd3Q7dj0xIn0.eyJleHAiOjE1MTg2OTg5MTcsImlzcyI6InZpcmdpbC1iZTAwZTEwZTRlMWY0YmY1OGY5YjRkYzg1ZDc5Yzc3YSIsInN1YiI6ImlkZW50aXR5LUFsaWNlIiwiaWF0IjoxNTE4NjEyNTE3fQ.MFEwDQYJYIZIAWUDBAIDBQAEQP4Yo3yjmt8WWJ5mqs3Yrqc_VzG6nBtrW2KIjP-kxiIJL_7Wv0pqty7PDbDoGhkX8CJa6UOdyn3rBWRvMK7p7Ak"
    // you can provide users with JWT at registration or authorization steps
    // Send a JWT to client-side
    jwtString := token.String()

// API_KEY (you got this Key at Virgil Dashboard)
String apiKeyBase64 = "MC4CAQAwBQYDK2VwBCIEINlK4BhgsijAbNmUqU6us0ZU9MGi+HxdYCA6TdZeHjR4";
byte[] apiKeyData = ConvertionUtils.base64ToBytes(apiKeyBase64);

// Crypto library imports a private key into a necessary format
VirgilCrypto crypto = new VirgilCrypto();
PrivateKey apiKey = crypto.importPrivateKey(apiKeyData);

// initialize accessTokenSigner that signs users JWTs
AccessTokenSigner accessTokenSigner = new VirgilAccessTokenSigner();

// use your App Credentials you got at Virgil Dashboard:
String appId = "be00e10e4e1f4bf58f9b4dc85d79c77a"; // APP_ID
String apiKeyId = "70b447e321f3a0fd"; // API_KEY_ID
TimeSpan ttl = TimeSpan.fromTime(1, TimeUnit.HOURS); // 1 hour (JWT's lifetime)

// setup JWT generator with necessary parameters:
JwtGenerator jwtGenerator = new JwtGenerator(appId, apiKey, apiKeyId, ttl, accessTokenSigner);

// generate JWT for a user
// remember that you must provide each user with his unique JWT
// each JWT contains unique user's identity (in this case - Alice)
// identity can be any value: name, email, some id etc.
String identity = "Alice";
Jwt aliceJwt = jwtGenerator.generateToken(identity);

// as result you get users JWT, it looks like this: "eyJraWQiOiI3MGI0NDdlMzIxZjNhMGZkIiwidHlwIjoiSldUIiwiYWxnIjoiVkVEUzUxMiIsImN0eSI6InZpcmdpbC1qd3Q7dj0xIn0.eyJleHAiOjE1MTg2OTg5MTcsImlzcyI6InZpcmdpbC1iZTAwZTEwZTRlMWY0YmY1OGY5YjRkYzg1ZDc5Yzc3YSIsInN1YiI6ImlkZW50aXR5LUFsaWNlIiwiaWF0IjoxNTE4NjEyNTE3fQ.MFEwDQYJYIZIAWUDBAIDBQAEQP4Yo3yjmt8WWJ5mqs3Yrqc_VzG6nBtrW2KIjP-kxiIJL_7Wv0pqty7PDbDoGhkX8CJa6UOdyn3rBWRvMK7p7Ak"
// you can provide users with JWT at registration or authorization steps
// Send a JWT to client-side
String jwtString = aliceJwt.stringRepresentation();

// server.js

import express from 'express';
import { VirgilCrypto, VirgilAccessTokenSigner } from 'virgil-crypto';
import { JwtGenerator } from 'virgil-sdk';

const virgilCrypto = new VirgilCrypto();
// initialize accessTokenSigner that signs users JWTs
const accessTokenSigner = new VirgilAccessTokenSigner(virgilCrypto);

// import your API Key that you got in Virgil Dashboard from string.
const apiKey = virgilCrypto.importPrivateKey(process.env.VIRGIL_API_KEY_BASE64);

// initialize JWT generator with your Application Id and API Key Id you got in
// Virgil Dashboard and the `apiKey` object you've just imported.
const jwtGenerator = new JwtGenerator({
  appId: process.env.VIRGIL_APP_ID,
  apiKey: apiKey,
  apiKeyId: process.env.VIRGIL_API_KEY_ID,
  accessTokenSigner: accessTokenSigner,
  millisecondsToLive:  20 * 60 * 1000 // JWT lifetime - 20 minutes (default)
});

app.get('/virgil-access-token', (req, res) => {
  // Get the identity of the user making the request (this assumes the request
  // is authenticated and there is middleware in place that populates the
  // `req.user` property with the user record).
  // Identity can be anything as long as it's unique for each user (e.g. email,
  // name, etc.). You can even obfuscate the identity of your users so that
  // Virgil Security doesn't know your actual user identities.
  const jwt = jwtGenerator.generateToken(req.user.email);
  req.send(jwt.toString());
});

use Virgil\CryptoImpl\VirgilAccessTokenSigner;
use Virgil\CryptoImpl\VirgilCrypto;

use Virgil\Sdk\Web\Authorization\JwtGenerator;

// API_KEY (you got this Key at Virgil Dashboard)
$privateKeyStr = "MIGhMF0GCSqGSIb3DQEFDTBQMC8GCSqGSIb3DQEFDDAiBBC7Sg/DbNzhJ/uakTva";
$apiKeyData = base64_decode($privateKeyStr);

// Crypto library imports a private key into a necessary format
$crypto = new VirgilCrypto();
$privateKey = $crypto->importPrivateKey($apiKeyData);

// initialize accessTokenSigner that signs users JWTs
$accessTokenSigner = new VirgilAccessTokenSigner();

// use your App Credentials you got at Virgil Dashboard:
$appId = "be00e10e4e1f4bf58f9b4dc85d79c77a"; // APP_ID
$apiKeyId = "70b447e321f3a0fd";              // API_KEY_ID
$ttl = 3600; // 1 hour (JWT's lifetime)

// setup JWT generator with necessary parameters:
$jwtGenerator = new JwtGenerator($privateKey, $apiKeyId, $accessTokenSigner, $appId, $ttl);

// generate JWT for a user
// remember that you must provide each user with his unique JWT
// each JWT contains unique user's identity (in this case - Alice)
// identity can be any value: name, email, some id etc.
$identity = "Alice";
$token = $jwtGenerator->generateToken($identity);

// as result you get users JWT, it looks like this: "eyJraWQiOiI3MGI0NDdlMzIxZjNhMGZkIiwidHlwIjoiSldUIiwiYWxnIjoiVkVEUzUxMiIsImN0eSI6InZpcmdpbC1qd3Q7dj0xIn0.eyJleHAiOjE1MTg2OTg5MTcsImlzcyI6InZpcmdpbC1iZTAwZTEwZTRlMWY0YmY1OGY5YjRkYzg1ZDc5Yzc3YSIsInN1YiI6ImlkZW50aXR5LUFsaWNlIiwiaWF0IjoxNTE4NjEyNTE3fQ.MFEwDQYJYIZIAWUDBAIDBQAEQP4Yo3yjmt8WWJ5mqs3Yrqc_VzG6nBtrW2KIjP-kxiIJL_7Wv0pqty7PDbDoGhkX8CJa6UOdyn3rBWRvMK7p7Ak"
// you can provide users with JWT at registration or authorization steps
// Send a JWT to client-side
$token->__toString();

import datetime

from virgil_crypto import VirgilCrypto
from virgil_crypto.access_token_signer import AccessTokenSigner
from virgil_sdk.jwt import JwtGenerator
from virgil_sdk.utils import Utils

# API_KEY (you got this Key at Virgil Dashboard)
api_key_base64 = "MIGhMF0GCSqGSIb3DQEFDTBQMC8GCSqGSIb3DQEFDDAiBBC7Sg/DbNzhJ/uakTvafUMoAgIUtzAKBggqhkiG9w0CCjAdBglghkgBZQMEASoEEDunQ1yhWZoKaLaDFgjpxRwEQAFdbC8e6103lJrUhY9ahyUA8+4rTJKZCmdTlCDPvoWH/5N5kxbOvTtbxtxevI421z3gRbjAtoWkfWraSLD6gj0="
private_key_data = Utils.b64_decode(api_key_base64)

# Crypto library imports a private key into a necessary format
crypto = VirgilCrypto()
api_key = crypto.import_private_key(private_key_data)

#  initialize accessTokenSigner that signs users JWTs
access_token_signer = AccessTokenSigner()

# use your App Credentials you got at Virgil Dashboard:
app_id = "be00e10e4e1f4bf58f9b4dc85d79c77a"
app_key_id = "70b447e321f3a0fd"
ttl = datetime.timedelta(hours=1).seconds

# setup JWT generator with necessary parameters:
jwt_generator = JwtGenerator(app_id, api_key, app_key_id, ttl, access_token_signer)

# generate JWT for a user
# remember that you must provide each user with his unique JWT
# each JWT contains unique user's identity (in this case - Alice)
# identity can be any value: name, email, some id etc.
identity = "Alice"
alice_jwt = jwt_generator.generate_token(identity)

# as result you get users JWT, it looks like this: "eyJraWQiOiI3MGI0NDdlMzIxZjNhMGZkIiwidHlwIjoiSldUIiwiYWxnIjoiVkVEUzUxMiIsImN0eSI6InZpcmdpbC1qd3Q7dj0xIn0.eyJleHAiOjE1MTg2OTg5MTcsImlzcyI6InZpcmdpbC1iZTAwZTEwZTRlMWY0YmY1OGY5YjRkYzg1ZDc5Yzc3YSIsInN1YiI6ImlkZW50aXR5LUFsaWNlIiwiaWF0IjoxNTE4NjEyNTE3fQ.MFEwDQYJYIZIAWUDBAIDBQAEQP4Yo3yjmt8WWJ5mqs3Yrqc_VzG6nBtrW2KIjP-kxiIJL_7Wv0pqty7PDbDoGhkX8CJa6UOdyn3rBWRvMK7p7Ak"
# you can provide users with JWT at registration or authorization steps
# Send a JWT to client-side
jwt_string = alice_jwt.to_string()

import VirgilSDK
import VirgilCrypto

// API_KEY (you got this Key at Virgil Dashboard)
let apiKeyBase64 = "MIGhMF0GCSqGSIb3DQEFDTBQMC8GCSqGSIb3DQEFDDAiBBC7Sg/DbNzhJ/uakTvafUMoAgIUtzAKBggqhkiG9w0CCjAdBglghkgBZQMEASoEEDunQ1yhWZoKaLaDFgjpxRwEQAFdbC8e6103lJrUhY9ahyUA8+4rTJKZCmdTlCDPvoWH/5N5kxbOvTtbxtxevI421z3gRbjAtoWkfWraSLD6gj0="
let privateKeyData = Data(base64Encoded: apiKeyBase64)!

// Crypto library imports a private key into a necessary format
let crypto = VirgilCrypto()
let apiKey = try! crypto.importPrivateKey(from: privateKeyData)

// initialize accessTokenSigner that signs users JWTs
let accessTokenSigner = VirgilAccessTokenSigner()

// use your App Credentials you got at Virgil Dashboard:
let appId = "be00e10e4e1f4bf58f9b4dc85d79c77a" // APP_ID
let apiKeyId = "70b447e321f3a0fd" // API_KEY_ID
let ttl: TimeInterval = 60 * 60 * 24 // 1 hour (JWT's lifetime)

// setup JWT generator with necessary parameters:
let jwtGenerator = JwtGenerator(apiKey: apiKey, apiPublicKeyIdentifier: apiKeyId,
                                accessTokenSigner: accessTokenSigner, appId: appId, ttl: ttl)

// generate JWT for a user
// remember that you must provide each user with his unique JWT
// each JWT contains unique user's identity (in this case - Alice)
// identity can be any value: name, email, some id etc.
let identity = "Alice"
let aliceJwt = try! jwtGenerator.generateToken(identity: identity)

// as result you get users JWT, it looks like this: "eyJraWQiOiI3MGI0NDdlMzIxZjNhMGZkIiwidHlwIjoiSldUIiwiYWxnIjoiVkVEUzUxMiIsImN0eSI6InZpcmdpbC1qd3Q7dj0xIn0.eyJleHAiOjE1MTg2OTg5MTcsImlzcyI6InZpcmdpbC1iZTAwZTEwZTRlMWY0YmY1OGY5YjRkYzg1ZDc5Yzc3YSIsInN1YiI6ImlkZW50aXR5LUFsaWNlIiwiaWF0IjoxNTE4NjEyNTE3fQ.MFEwDQYJYIZIAWUDBAIDBQAEQP4Yo3yjmt8WWJ5mqs3Yrqc_VzG6nBtrW2KIjP-kxiIJL_7Wv0pqty7PDbDoGhkX8CJa6UOdyn3rBWRvMK7p7Ak"
// you can provide users with JWT at registration or authorization steps
// Send a JWT to client-side
let jwtString = aliceJwt.stringRepresentation()

For this tutorial we've created a sample backend that demonstrates how you can set up your backend to generate the JWTs. To set up and run the sample backend locally, head over to your GitHub repo of choice:

Node.js | Golang | PHP | Java | Python and follow the instructions in README.

Manage a JWT

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

// JWT Token structure
header.payload.signature

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.

{
  // Issuer. Equals to virgil-
  "iss": "virgil-be00e10e4e1f4bf58f9b4dc85d79c77a",
  // Subject. Equals to identity-
  "sub": "identity-Alice",
  // Issued at. Utc timestamp that indicates when token was issued.
  "iat": 1518612517
  // Expires at. Utc timestamp that shows when token will expire. Tokens have a maximum age of 24 hours
  "exp": 1518698917,
}

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.

The signature is computed using the following pseudo code:

// Signature
signature = base64urlEncode(EdDSA+SHA512(SHA512(base64urlEncode(header) + "." + base64urlEncode(payload))))

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.

Here is an example of JWT:

// JWT Token
eyJraWQiOiI3MGI0NDdlMzIxZjNhMGZkIiwidHlwIjoiSldUIiwiYWxnIjoiVkVEUzUxMiIsImN0eSI6InZpcmdpbC1qd3Q7dj0xIn0.eyJleHAiOjE1MTg2OTg5MTcsImlzcyI6InZpcmdpbC1iZTAwZTEwZTRlMWY0YmY1OGY5YjRkYzg1ZDc5Yzc3YSIsInN1YiI6ImlkZW50aXR5LUFsaWNlIiwiaWF0IjoxNTE4NjEyNTE3fQ.MFEwDQYJYIZIAWUDBAIDBQAEQP4Yo3yjmt8WWJ5mqs3Yrqc_VzG6nBtrW2KIjP-kxiIJL_7Wv0pqty7PDbDoGhkX8CJa6UOdyn3rBWRvMK7p7Ak

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.

You can try creating your own JWT through your browser at jwt.io.