Pin-Based Authentication

In this tutorial, we will build a simple application using the
wrapper library to perform pin-based authentication. The user
will be redirected to SmartVault to authenticate and will be prompted
to allow our application access to the service.
The user will then be redirected back to your application to input
the pin. This is a common workflow for rich applications. We will
use the generic integration model, which effectively makes
SmartVault a basic file storage system similar to a hard drive.

Here’s What You’ll Need

If you have not yet created a developer account or client ID, visit Creating a Developer Account.(For OAuth Support, select User PIN since this is how we will be authenticating.)

Installing the Library

We could form individual REST API calls and communicate with SmartVault that way, but why reinvent the wheel right? Our Java API wrapper library allows you to perform actions with SmartVault without writing individual REST API requests.
You can download the wrapper library down below.
There is one important dependency you will need in order to use our library: protobuf-java 2.4.1
For this tutorial, we will also make use of two other libraries: commons-io and bcprov-jdk16
All of these extra libraries can be obtained using Maven. How you set them up will depend on the environment you are using. If you are using an IDE, check its documentation if you are unsure about how to do this.

Setting Up

Let’s create a new class called SmartVault to handle communication with the SmartVault API. We will need to include the SmartVault library:

import com.smartvault.proto.*;
import com.smartvault.rest.*;
public class SmartVault
{
	. . .
}

Opening the Connection

Let’s add two instance variables to our class to handle communication with SmartVault:

private PublicClientProtocol _protocol;
private DelegatedProtocol _delegation;

The protocol object created here will handle tasks on behalf of the client. In our case, this will be mainly for authentication. The delegation object will allow us to perform actions on behalf of the user. We can use this to do a variety of tasks including browsing and managing files, as well as performing uploads and downloads.
Let’s create a constructor to set up an initial connection with SmartVault. This will initialize the protocol object:

public SmartVault() throws Exception
{
	String clientId = "JavaTutorial"; // Change this to your client ID

	PublicClientCfg cfg = new PublicClientCfg(new Uri("https://rest.smartvault.com"), clientId);
	_protocol = new PublicClientProtocol(cfg);
}

NOTE: You will need to change the Client ID to the one you registered earlier using the SmartVault Portal.

Authentication

For this tutorial, we’re going to be using pin-based authentication with manual pin entry. The way that this works is that the user will need to be directed to the SmartVault Portal to authorize our application. Once the user does this, he or she will be given a pin, which will need to be typed into your application to authenticate.

Requesting a Pin

The SmartVault API has a call to get a URL from the server for the user to visit in order to authorize an application. We will need the user’s email address in order to do this.
Let’s start by creating a method called requestPin which will take in the user’s email address and output the URL as a string. There’s just one simple library call that we’ll need to do in order to get the URL. Here’s the implementation for requestPin:
public String requestPin(String userEmail) throws Exception
{
return _protocol.getPinRequestEndpoint(userEmail);
}

Authenticating with SmartVault

Once the user has their pin, we can use it along with their email address to actually authenticate. Let’s create a method called authenticate to take care of this. This is where the delegation object gets initialized.

public void authenticate(String userEmail, String userPin) throws Exception
{
	_delegation = _protocol.createDelegatedProtocol(userEmail, userPin);
}

Trying It Out

Setting It Up

Now that we’ve got a nice wrapper class to handle some basic operations, let’s try it out! We’re going to make a simple console program that performs authentication.
Let’s start with a simple main method.

public class Program
{
	public static void main(String[] args)
	{
		...
	}
}

Opening the Connection

All we need to do is create an instance of our SmartVault class to open a connection.

public static void main(String[] args)
{
	try
	{
		SmartVault smartVault = new SmartVault();

		...
	}
	catch (Exception e)
	{
		e.printStackTrace();
	}
}

Authenticating

Let’s call a new method to handle authenticating with SmartVault. This method, called authenticate, will need to take in the SmartVault object.

public static void main(String[] args)
{
	try
	{
		SmartVault smartVault = new SmartVault();
		authenticate(smartVault);
	}
	catch (Exception e)
	{
		e.printStackTrace();
	}
}

Now let’s start implementing the authenticate method. We’ll need the user’s email address and pin in order to authenticate. Let’s have them enter their email address from the console.

private static void authenticate(SmartVault smartVault) throws Exception
{
	// Pin-based authentication with manual pin entry
	System.out.println("Enter your email address:");
	String email = keyboard.nextLine();

	. . .
}

We will also need the user’s pin, but we can’t assume that they already have one! For this tutorial, let’s ask the user if they have a pin, and if they don’t, we can provide them with the URL where they can view the pin.

public static void authenticate(SmartVault smartVault) throws Exception
{
	// Pin-based authentication with manual pin entry
	System.out.println("Enter your email address:");
	String email = keyboard.nextLine();

	System.out.println("Do you have a pin? [y/n]:");
	String response = keyboard.nextLine();

	if (!response.toLowerCase().startsWith("y"))
	{
		String url = smartVault.requestPin(email);
		System.out.println("Go to the following URL to view your pin and press the 'Enter' key when you've got the pin.");
		System.out.println(url);
		keyboard.nextLine();
	}

	. . .
}

Now that we know the user definitely has a pin, let’s ask them to enter it from the console.

public static void authenticate(SmartVault smartVault) throws Exception
{
	// Pin-based authentication with manual pin entry
	System.out.println("Enter your email address:");
	String email = keyboard.nextLine();

	System.out.println("Do you have a pin? [y/n]:");
	String response = keyboard.nextLine();

	if (!response.toLowerCase().startsWith("y"))
	{
		String url = smartVault.requestPin(email);
		System.out.println("Go to the following URL to view your pin and press the 'Enter' key when you've got the pin.");
		System.out.println(url);
		keyboard.nextLine();
	}

	System.out.println("Enter your pin:");
	String pin = keyboard.nextLine();

	. . .
}

Finally, since we have the user’s email address and pin, we have all we need to authenticate using the authenticate method in the SmartVault class that we created earlier.

public static void authenticate(SmartVault smartVault) throws Exception
{
	// Pin-based authentication with manual pin entry
	System.out.println("Enter your email address:");
	String email = keyboard.nextLine();

	System.out.println("Do you have a pin? [y/n]:");
	String response = keyboard.nextLine();

	if (!response.toLowerCase().startsWith("y"))
	{
		String url = smartVault.requestPin(email);
		System.out.println("Go to the following URL to view your pin and press the 'Enter' key when you've got the pin.");
		System.out.println(url);
		keyboard.nextLine();
	}

	System.out.println("Enter your pin:");
	String pin = keyboard.nextLine();

	smartVault.authenticate(email, pin);
}

Finishing It Up

Since console applications generally quit after they finish, let’s prevent that by adding a quick prompt to have the user press a key to exit. This allows us to see the end of the program’s output easily if it is not launched from a command line window. It is not necessary to do this if you do not want it.

public static void main(String[] args)
{
	try
	{
		SmartVault smartVault = new SmartVault();
		authenticate(smartVault);
	}
	catch (Exception e)
	{
		e.printStackTrace();
	}

	System.out.println("\nPress 'Enter' key to exit");
	keyboard.nextLine();
}

Putting it together

SmartVault.java

import com.smartvault.rest.*;
import com.sun.jndi.toolkit.url.Uri;


public class SmartVault
{
    private PublicClientProtocol _protocol;
    private DelegatedProtocol _delegation;

    public SmartVault() throws Exception
    {
        String clientId = "JavaTutorial"; // Change this to your client ID

        PublicClientCfg cfg = new PublicClientCfg(new Uri("https://rest.smartvault.com"), clientId);

        _protocol = new PublicClientProtocol(cfg);
    }

    public String requestPin(String userEmail) throws Exception
    {
        return _protocol.getPinRequestEndpoint(userEmail);
    }

    public void authenticate(String userEmail, String userPin) throws Exception
    {
        _delegation = _protocol.createDelegatedProtocol(userEmail, userPin);
    }
}

Program.java

import java.util.Scanner;

public class Program
{

    private static Scanner keyboard = new Scanner(System.in);

    public static void main(String[] args)
    {
        try
        {
            SmartVault smartVault = new SmartVault();
            authenticate(smartVault);
        }
        catch (Exception e)
        {
            e.printStackTrace();
        }

        System.out.println("\nPress 'Enter' key to exit");
        keyboard.nextLine();
    }

    private static void authenticate(SmartVault smartVault) throws Exception
    {
        System.out.println("Enter your email address:");
        String email = keyboard.nextLine();

        System.out.println("Do you have a pin? [y/n]:");
        String response = keyboard.nextLine();

        if (!response.toLowerCase().startsWith("y"))
        {
            String url = smartVault.requestPin(email);
            System.out.println("Go to the following URL to view your pin and press the 'Enter' key when you've got the pin.");
            System.out.println(url);
            keyboard.nextLine();
        }

        System.out.println("Enter your pin:");
        String pin = keyboard.nextLine();
        smartVault.authenticate(email, pin);
    }
}

Download HelloWorldSVRest-PinBasedAuth.zip

Here’s What You’ll Need

If you have not yet created a developer account or client ID, visit Creating a Developer Account.(For OAuth Support, select User PIN since this is how we will be authenticating.)

Installing the Library

We could form individual REST API calls and communicate with SmartVault that way, but why do this when this work has already been done for you? Our C# API wrapper library allows you to perform actions with SmartVault without writing individual REST API requests. This is available as a NuGet package called SmartVault.Rest and can be obtained from the standard nuget.org repository:

Now that we have the library installed, we can start writing some code.

Setting Up

Let’s create a new class called SmartVault to handle communication with the SmartVault API. We will need to include the SmartVault library:

using SmartVault.Core;
using SmartVault.Proto;
using SmartVault.Rest;

class SmartVault
{
    ...
}

Opening the Connection

Let’s add two instance variables to our class to handle communication with SmartVault:

private PublicClientProtocol _protocol;
private DelegatedProtocol _delegation;

The protocol object created here will handle tasks on behalf of the client. In our case, this will be mainly for authentication. The delegation object will allow us to perform actions on behalf of the user. We can use to do a variety of tasks such as browsing and managing files, as well as performing uploads and downloads.

Now let’s create a constructor to set up an initial connection with SmartVault. This will initialize the protocol object:

public SmartVault()
{
    string clientId = "CSharpTutorial"; // Change this to your client ID
    PublicClientCfg cfg =
        new PublicClientCfg(new Uri("https://rest.smartvault.com"), clientId);
    _protocol = new PublicClientProtocol(cfg);
}

NOTE: You should change the contents of clientId to match the ID you registered earlier using the SmartVault Portal.

Authentication

Requesting a Pin

The SmartVault API has a call to get a URL from the server for the user to visit in order to authorize an application. We will need the user’s email address in order to do this.
Let’s start by creating a method called RequestPin which will take in the user’s email address and output the URL as a string. There’s just one simple library call that we’ll need to do in order to get the URL. Here’s the implementation for RequestPin:

public string RequestPin(string email)
{
    return _protocol.GetPinRequestEndpoint(email);
}

Authenticating with SmartVault

Once the user has their pin, we can use it along with their email address to actually authenticate. Let’s create a method called Authenticate to take care of this. This is where the delegation object gets initialized.

public void Authenticate(string email, string pin)
{
	_delegation = _protocol.CreateDelegatedProtocol(email, pin);
}

Trying It Out

Setting It Up

class Program
{
	static void Main(string[] args)
	{
		...
	}
}

Opening the Connection

All we need to do is create an instance of our SmartVault class to open a connection.

static void Main(string[] args)
{
    try
    {
        SmartVault smartVault = new SmartVault();

        ...
    }
    catch (Exception e)
    {
        Console.WriteLine(e.Message);
    }
}

Authenticating

Now let’s start implementing the Authenticate method. We’ll need the user’s email address and pin in order to authenticate. Let’s have them enter their email address from the console.

private static void Authenticate(SmartVault smartVault)
{
    // Pin-based authentication with manual pin entry
    Console.Write("Enter your email address: ");
    string email = Console.ReadLine();

    ...
}

We will also need the user’s pin, but we can’t assume that they already have one! For this tutorial, let’s ask the user if they have a pin, and if they don’t, we can open the URL to generate one in their default browser.

private static void Authenticate(SmartVault smartVault)
{
    // Pin-based authentication with manual pin entry
    Console.Write("Enter your email address: ");
    string email = Console.ReadLine();

    Console.Write("Do you have a pin? [y/n]: ");
    string response = Console.ReadLine();

    if (!response.ToLower().StartsWith("y"))
    {
        string url = smartVault.RequestPin(email);
        Process.Start(url);
    }

    ...
}

Now that we know the user definitely has a pin, let’s ask them to enter it from the console.

private static void Authenticate(SmartVault smartVault)
{
    // Pin-based authentication with manual pin entry
    Console.Write("Enter your email address: ");
    string email = Console.ReadLine();

    Console.Write("Do you have a pin? [y/n]: ");
    string response = Console.ReadLine();

    if (!response.ToLower().StartsWith("y"))
    {
        string url = smartVault.RequestPin(email);
        Process.Start(url);
    }

    Console.Write("Enter your pin: ");
    string pin = Console.ReadLine();

    ...
}

Finally, since we have the user’s email address and pin, we have all we need to authenticate using the Authenticate method in the SmartVault class that we created earlier.

private static void Authenticate(SmartVault smartVault)
{
    // Pin-based authentication with manual pin entry
    Console.Write("Enter your email address: ");
    string email = Console.ReadLine();

    Console.Write("Do you have a pin? [y/n]: ");
    string response = Console.ReadLine();

    if (!response.ToLower().StartsWith("y"))
    {
        string url = smartVault.RequestPin(email);
        Process.Start(url);
    }

    Console.Write("Enter your pin: ");
    string pin = Console.ReadLine();

    smartVault.Authenticate(email, pin);
}

Now we can call our new method to handle authentication with SmartVault. This method, called Authenticate, will need to take in the SmartVault object.

static void Main(string[] args)
{
    try
    {
        SmartVault smartVault = new SmartVault();
        Authenticate(smartVault);
    }
    catch (Exception e)
    {
        Console.WriteLine(e.Message);
    }
}

Finishing It Up

static void Main(string[] args)
{
    try
    {
        SmartVault smartVault = new SmartVault();
        Authenticate(smartVault);
    }
    catch (Exception e)
    {
        Console.WriteLine(e.Message);
    }

    Console.WriteLine("\nPress any key to exit");
    Console.ReadKey();
}

Putting It Together

SmartVault.cs

using System;
using SmartVault.Core;
using SmartVault.Proto;
using SmartVault.Rest;
using System.IO;

namespace HelloWorldSVRest
{
    class SmartVault
    {
        private PublicClientProtocol _protocol;
        private DelegatedProtocol _delegation;

        public SmartVault()
        {
            string clientId = "CSharpTutorial"; // Change this to your client ID
            PublicClientCfg cfg =
                new PublicClientCfg(new Uri("https://rest.smartvault.com"), clientId);
            _protocol = new PublicClientProtocol(cfg);
        }

        public string RequestPin(string email)
        {
            return _protocol.GetPinRequestEndpoint(email);
        }

        public void Authenticate(string email, string pin)
        {
            _delegation = _protocol.CreateDelegatedProtocol(email, pin);
        }
    }
}

Program.cs

using System;
using System.Diagnostics;
using System.IO;

namespace HelloWorldSVRest
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                SmartVault smartVault = new SmartVault();
                Authenticate(smartVault);
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }

            Console.WriteLine("\nPress any key to exit");
            Console.ReadKey();
        }

        private static void Authenticate(SmartVault smartVault)
        {
            // Pin-based authentication with manual pin entry
            Console.Write("Enter your email address: ");
            string email = Console.ReadLine();

            Console.Write("Do you have a pin? [y/n]: ");
            string response = Console.ReadLine();

            if (!response.ToLower().StartsWith("y"))
            {
                string url = smartVault.RequestPin(email);
                Process.Start(url);
            }

            Console.Write("Enter your pin: ");
            string pin = Console.ReadLine();

            smartVault.Authenticate(email, pin);
        }
    }
}

Download PinAuth-C#.zip

Here’s What You’ll Need

Installing the Library

Setting Up

Opening the Connection

Authentication

Requesting a Pin

Authenticating with SmartVault

Trying It Out

Setting It Up

Opening the Connection

Authenticating

Finishing It Up

Putting it together

Here’s What You’ll Need

Installing the Library

Setting Up

Opening the Connection

Authentication

Requesting a Pin

Authenticating with SmartVault

Trying It Out

Setting It Up

Opening the Connection

Authenticating

Finishing It Up

Putting It Together

Leave A Comment? × Cancel Reply