Privakey Cloud - Quick Start

The easiest and quickest way to gain a functional understanding how Privakey works is to leverage Privakey Cloud, the Privakey AuthWallet mobile apps 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 authentication challenges via Privakey ID.

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 or iOS phone to run our Universal Application.

Overview

This tutorial will walk through the following steps:

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.

The Privakey AuthWallet application is our universal authentication and authorization application. 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.

Sign Up for Privakey Cloud

Go here to create a new account.

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:

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

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:

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

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.

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:

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:

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:

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:

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:

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:

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:

To see complete API documentation go to our documentation site.

Conclusion

You have now completed this Quick Start Guide.