Privakey Cloud - Quick Start

Author: Brian Ross & Nick Vaccaro
Date: June 4, 2021
Version: 1.1

The easiest and quickest way to gain a functional understanding how Privakey works is to leverage Privakey Cloud (Server), the Privakey AuthWallet (Authenticator Application) applications and a simple API explorer as a proxy for a connected service.

This Quick Start guide will do just that to demonstrate the core architecture and principals of Privakey while allowing you to experience just how easy it is to process challenges via Privakey's Transaction Intent Verification infrastructure.

In this guide, which should take no more than 30 minutes to an hour to complete, we'll walk you through signing up for Privakey, configuring an App Space and a Relying Party in the Privakey Cloud, installing a universal application, and interacting with this set-up via Postman.

At the end of this guide you should understand the core constructs of Privakey and hopefully be able to develop a vision for how Privakey can help you reduce threat vectors and provide unparalleled, secure interactions with your customers.

Prerequisites Not much is needed to tackle this Quick Start. It is helpful, but not necessary to have prior experience with Postman. To get the most out of the tutorial one should probably have prior experience with distributed systems and APIs.

At this point, this guide also requires an Android phone to run our Universal Application. (An iOS version of the universal application is forthcoming.)

Overview

This tutorial will walk through the following steps:

StepDescription
1. Download Privakey AppWallet ApplicationGet the Privakey AuthWallet Application
2. Sign up for the Privakey Cloud ServiceSet up your Privakey Cloud account
3. Create your first App SpaceDefine an app context and a specific service that will connect to it
4. Create your First Request OriginCreate a Request Origin from which requests will be sent to the Privakey API
5. Bind your Mobile ApplicationConnect your AuthWallet application to the App Space you just created.
6. Interact with your UserSend challenges to your user

Download the Privakey AuthWallet Application

The Privakey AuthWallet application is one of the key elements of the Privakey infrastructure. It is a client application used by end-users to receive, view and act on transaction intent verification challenges.

mobileApp

The Privakey AuthWallet application is our universal authentication and authorization application. It is required to access the Privakey Cloud Administration portal. It can also be used by end-users of services which have configured use of the AuthWallet application in the Privakey Admin Portal. Alternatively, implementers can opt to use libraries provided by Privakey to enhance their own application with transaction intent verification capabilities. Library implementation is out of the scope of this quick start guide.

The Privakey AuthWallet Application is available on Google Play and the App Store. After you've downloaded it onto your device, continue on to the next step.

Sign Up for Privakey Cloud

Go here to create a new account.

img1

Based on the information you provide, we'll create your company account and initialize your login account. You will be redirected to a screen with important information. It will look like this:

sign up 3

Make note of all the information on the page and please be sure to copy and save the Login Link. It is your unique login link.

You'll receive an email after completing the sing-in information with instructions to complete Authwallet binding.

email

Get your AuthWallet App ready. During this process we will bind your AuthWallet application to your Privakey Cloud account to enable logging-in to the portal.

CORE CONCEPT: Binding

Binding is the process whereby a user links their service account to an App Space and instance of the AuthWallet within Privakey. During Binding, Privakey will tokenize the user's account. During tokenization, Privakey does a number of things, including creating device keys and account keys on the user's device, prompting the user to create a PIN (if they haven't), storing the privakey keys in restricted, hardware protected spaces within the user's device, and storing account information, including corresponding public keys in the Privakey CX server's database.

Back to the email - click on the link following "Please complete your registration..." to complete your registration.

You should see a screen that looks just like this:

registration

Fill in this form and click 'Save' and you'll be presented with a bind screen:

bind

At this step we will be binding the AuthWallet application installed on your device to your Privakey Cloud account. After this initial binding you will use the Auth Wallet application to log into your Privakey Cloud account.

Launch AuthWallet on your device, click Add Service and complete the prompts to set up your account. You'll go through a multi-step process to tokenize your device and configure it to authenticate and authorize events from the Privakey Portal.

bind2

There's an important bit of information here - your company GUID - embedded in the URL presented. This GUID (or the URL) is required to authenticate to the Portal. Make sure you bookmark the link or save the GUID.

At the bottom of the page there's a link 'click here.' Click it, bookmark it and log in to the portal. Our next step happens in the portal.

Create your First App Space

CORE CONCEPT: App Space

In Privakey, an App Space is defined by the intersection of two constructs - a user population and a Privakey application deployment. A user population means a group or groups of service users who have unique ID's. A Privakey application deployment is a singular mobile application (in this Quick Start Guide, the Privakey Auth Wallet) the user population will interact with to perform Transaction Intent Verifications. An App Space is a somewhat abstract construct. App Spaces do not have have API credentials - Request Origins (see below), of which there can be many for each App Space, are concrete services that connect to the Privakey API.

Once logged into the Portal you will resolve to your Company landing page. An example is depicted below:

company

When you requested access to Privakey Cloud above we set your company up and made you a Company Administrator. Click around the portal to familiarize yourself with the functionality. Things you can do include adding additional Company Admins and creating App Spaces.

When you're ready to continue with this guide click 'Create New App Space' to get started creating an App Space. You should see the following screen:

appSpace

The App Space name should equate to the name of the service. This will display on challenges and within the AuthWallet application list views.

Set "Identity Provider Type" to Simple. This functionality will not be leveraged when using the AuthWallet, universal application.

In the section, Firebase Configuration, you should toggle the Use Privakey Cloud App toggle. This designates that you will be using the Universal, AuthWallet application for this App Space.

Lastly, we'll need to configure your brand within the AuthWallet Application. This is comprised of two key elements - a logo and a Brand Color.

Create your First Request Origin

Next, you will need to create a Request Origin - that is, a service that connects to Privakey to send challenges and receive responses to and from Privakey Cloud.

CORE CONCEPT: Request Origin

Request Origins are services, configured within the App Space construct, that have credentials to connect to and interact with the Privakey Cloud server. An App Space can have many Request Origins. A client facing application may be comprised of many services, all of which can send challenges to a user within the context of an App Space.

To create your first Request Origin click into the App Space you just created.

You will see the following screen:

appSpace2

First you will need to make yourself an App Space Administrator. Click on View/Manage Admins and add yourself as an Admin. The page will refresh and return you to the Company dashboard. If you are not following this Quick Start to the letter, you may be returned to the App Space dashboard. Find your way to the App Space dashboard for the App Space you created above and then click, View/Manage All Request Origins.

Click on "Create New Request Origin"

Give the request origin a name and choose Basic Authentication (for this tutorial we'll use Basic Authentication).

After submitting the form you will be presented with the Request Origin dashboard. It will look like this:

request origin

IMPORTANT:

Make note of the GUID and Password. Copy them to a secure location. These will be used in the next sections to Bind a user to this service and to send them challenges.

Congratulations - you have successfully configured an App Space and Request Origin. Now you are ready to bind a user and send them challenges.

Bind your Mobile Application to the App Space

This Bind is going to be similar to the process you went through when gaining access to the Privakey Cloud Server. During that Bind we linked your Admin Account within Privakey CX to your mobile AuthWallet application. In this exercise, we will link the App Space you just created to the Mobile AuthWallet application.

We have created a public Postman documentation site to facilitate this tutorial. It can be found here. A real-life binding would happen a bit differently. Of course, Postman would not be used. Instead, an end-user would, once authenticated to a service, be presented with an option to set-up AuthWallet Authorizations at which point they'd be presented a QR Code / Link to bind. To reduce the amount of effort in this tutorial we're using Postman.

To use it, we recommend and assume you have downloaded Postman. Once you have downloaded and installed Postman, return to the Postman documentation and click Run in Postman in the top right of the screen. This will allow you to assert your own Variables for Username and Password and to interact with the Privakey Cloud API.

In Postman, click 'Collections' and then expand the Privakey CX Tutorial collection. You should see 2 requests (Bind Account and Add Request). Click on Bind Account and you should see the following:

pmbind

In the top right of the screen you should see a drop down depicting 'No Environment'. On that dropdown click Privakey CX Tutorial. Then click the eye icon to the right of the drop-down to configure your variables. The variables presented are:

VariableDefinitionValue
UsernameThe username for Basic Header AuthenticationThe Request Origin GUID captured from the Create Request Origin Section
PasswordThe password for Basic Header AuthenticationThe password captured from the Create Request Origin Section
account_idThe user's unique account ID.For this quick-start it really can be anything
base_urlThe API endpoint for the Privakey ServerDo not change this\

Update the Username, Password and account_id in the environment variables.

Then, in the body of the Postman page, with Bind selected in the left navigation, click Send. This will send a Bind call to the Privakey Cloud service. This Server to Server call is used to initiate the bind process. It is server-to-server and authenticated to ensure the integrity of all Bind calls. The Privakey server will return a sessionToken, appSpaceGuid, and appSpaceName.

Enter these values in the form below to generate a QR code. This QR code will be scanned in the AuthWallet application to bind your account.

With the QR code on the screen, open the AuthWallet application on your mobile phone. Click on the hamburger menu in the top left and then click on Add Service and then Scan QR Code. Scan the code and the App Space you created will be added to your AuthWallet.

Congratulations - you now have your first 'user' bound to your App Space.

Interact with your User

Now you can send challenges to the user you just bound via the Privakey API. Back in Postman, click Add Request. The POST to addRequest has been pre-configured.

Simply hit send to send your request. You will receive a challenge on your device. Open the challenge on the AuthWallet application to review the content.

The body of the POST message you just sent looked like:

{
"notificationTitle": "Sample Request",
"accountId": "{{accountId}}",
"additionalInfo": "{\"template\":true}",
"content": "{\"title\":\"This is a Sample Request\",\"keys\":[{\"key\":\"Heading 1\",\"value\":\"Content of heading one. One can add many headings and content sections.\"},{\"key\":\"Heading 2\",\"value\":\"More content. Headings and sections help organize the content.\"}]}",
"buttons": [
{
"title": "Approve",
"strongAuth": true,
"style": "{\"color\":\"green\"}"
},
{
"title": "No thanks.",
"strongAuth": false,
"style": "{\"color\":\"#FF0000\"}"
}
],
"duration": "24h"
}
`

The JSON document includes the following key elements:

Element (key)Description
notificationTitleThe text sent as the notification title to users
accountIdThe account ID of the user to whom the challenge is sent. In Postman, this is pulled from the Environment variables
additionalInfoCurrently, for AuthWallent Privakey implementations this value, "{\"template\":true}" must be part of the AdditionalInfo object. Implementers can also put any other information they want in this value.
contentThis is the main body of the message as displayed within the AuthWallet application. Because the Privakey API can also support custom applications, this is defined as a String. But, when employed with the AuthWallet application the String must be stringified JSON, as this example shows.
buttonsThe name and color of the buttons displayed. The AuthWallet application can only show 2 buttons.
durationThe time-to-live of the challenge.

To see complete API documentation go to our documentation site.

Conclusion

You have now completed this Quick Start Guide.