Set up authentication to make API calls to Virgil Services

This guide shows how to set up authentication using Access Token.

In order to make call to Virgil Services (for example, to publish user's Card on Virgil Cards Service), you need to have a Access Token. You have to generate for each Application an Access Token on Virgil Dashboard.

Prerequisites for work

Install SDK and Setup Virgil Crypto

The Virgil is provided as a package. The package is distributed via Carthage and CocoaPods.

The package is available for:

iOS 7.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:

To integrate VirgilSDK into your Xcode project using Carthage, perform following steps:

Create an empty file with name Cartfile in your project's root folder, that lists the frameworks you’d like to use in your project.

Add the following line to your Cartfile

github "VirgilSecurity/virgil-sdk-x" ~> 4.6.0

Run carthage update. This will fetch dependencies into a Carthage/Checkouts folder inside your project's folder, then build each one or download a pre-compiled framework.

On your application targets’ “General” settings tab, in the “Linked Frameworks and Libraries” section, add each framework you want to use from the Carthage/Build folder inside your project's folder.

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

Swift note

Although VirgilSDK pod is using Objective-C as its primary language it might be quite easily used in a Swift application.
All public API is available from Swift and is bridged using NS_SWIFT_NAME where needed.

If you want to use VirgilSDK from swift it is necessary to perform the following:

Collect your Virgil developer credentials

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

APP_KEY_PASSWORD

A password to your APP KEY

ACCESS_TOKEN

An unique string that is used to authorize requests on Virgil Services.

You generate an Access Token on developer dashboard and then provide the Token to a user. With the Token, the user can then safely communicate with the Virgil Services.

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

Each Access Token is granted access to specific Application and has permissions that are configured by you.

Let's see how we can set up authentication:

first, we'll set up a client side

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

Set up Client side

When users want to start sending and receiving messages in a browser or mobile device, Virgil can't trust them right away. Clients have to be provided with a unique identity, thus, you'll need to give your users the Access Token that tells Virgil who they are and what they can do.

Each your client must send to you the Access Token request with their registration request. Then, your service that will be responsible for handling access requests must handle them in case of users successful registration on your Application server.

here an example of an Access Token

// an example of an Access Token representation
AT.7652ee415726a1f43c7206e4b4bc67ac935b53781f5b43a92540e8aae5381b14

Use an Access Token

With the Access Token we can initialize the Virgil SDK on the client-side to start doing fun stuff like sending and receiving messages.

To initialize the Virgil SDK on a client-side you need to use the following code:

let virgil = VSSVirgilApi(token: "[YOUR_ACCESS_TOKEN_HERE]")

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

Set up Server Side

Next, you'll set up server-side SDK to sign and approve user's Card.

Here is an example of how to setup server side with an Access Token:

// this language is not supported yet.

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