Secure Anonymous Tokens

Secure Anonymous Tokens (SATs) can allow users to authenticate using Xi Frame’s Session API. These tokens, generated by a secure API call, allow admins to provide their users with access to Xi Frame resources on-demand without prompting for another set of credentials. There are many use-cases where this type of authentication could be useful, such as software trials, demos, or kiosk-like experiences for example.

Additionally, the SAT API can be customized with additional parameters, some of which can be populated via environment variables in the remote system.

Overview

Using the SAT API, a web server can request a token on-demand (when a page or endpoint is requested, for example) and provide it to the Xi Frame Session API for sessions.

../../_images/session_api_sat_workflow_diagram.png

Getting Started

Requirements

  • Xi Frame Administrative access (Customer, Org, or Account level).
  • Administrative RESTful API access enabled.
  • Secure Anonymous Token provider enabled with Launchpad users.
  • Web server to host Secure Anonymous Token API integration.

RESTful API Credentials

The Secure Anonymous Token API can be consumed over RESTful endpoints to retrieve tokens.This requires an API integration with the proper roles/permissions.

Creating a new API integration

To get started, be sure to login as an administrator to gain access to API settings.

  1. There are two ways to start this process:

    1. From the Dashboard of the account, navigate to the “Users” page.
    2. If you are starting from the Admin view, navigate to the entity (Customer, Organization or Account) you wish to update and click on the ellipsis listed next to it to select “Users.”
    ../../_images/add_api_00.png
  2. Enable the “API” toggle and save – a new tab entitled “API” will appear.

../../_images/add_api_0.png
  1. Click on the API tab and then click the “Add API” link.
../../_images/add_api_1.png
  1. Give this new API integration a name; for this example, we’ll use “API to create anonymous tokens”. Then, select a role and scope; select at least an administrator for the account/org/customer you’re configuring access for. The “Launchpad User” role does not have permissions generate tokens.
../../_images/add_api_2.png
  1. Click “Add.” The new API will show up in the API list. Click the options menu for the new API and select “Manage Credentials”.
../../_images/add_api_3.png
  1. You’ll be prompted to create a new API key – start by giving it a name, then click the PLUS button on the right.
../../_images/add_api_4.png
  1. You’ll now see your Client ID and Client Secret. Copy these values, as you won’t be able to see the secret again after leaving this screen.
../../_images/add_api_5.png
  1. That’s it! Now you’re ready to add a Secure Anonymous provider using the steps below.

Note

The API credentials need Administrator permissions for the account, org, or customer that the integration is configured for. Launchpad users cannot generate tokens.

Creating a Secure Anonymous Token provider

  1. There are two ways to start this process:

    1. From the Dashboard of the account, navigate to the “Users” page where you will land on the “Authentication” tab.
    2. If you are starting from the Admin view, navigate to the entity (Customer, Organization, or Account) and click on the ellipsis listed next to it to select “Users.”
    ../../_images/add_api_00.png
  2. Enable the Secure Anonymous option under Authentication and save; a new Secure Anonymous tab will show up.

../../_images/secure_anon_setup_1.png
  1. Click the Secure Anonymous tab, then click the “Add Provider” link.
../../_images/secure_anon_setup_2.png
  1. You’ll be prompted to describe and configure your new Secure Anonymous provider. You can specify the following:

  1. Give it a description that makes sense for your use case, e.g. “Token provider for product trials”. Then, set the token duration you’d like. Finally, select a Role and scope – we recommend only configuring the role for Launchpad Users for security reasons.
../../_images/secure_anon_setup_3.png
  1. Your new Anonymous Access Provider will appear. Click the ellipsis next to the provider and select “Playground.” Test generating tokens using the new provider, as well as various syntax examples demonstrating how to make a request for tokens.
../../_images/secure_anon_setup_4.png

Programmatically generating Secure Anonymous Tokens

Now that we have an API Client ID and Client Secret from the API setup steps above, we can use the dynamic code snippet examples provided in the Secure Anonymous Playground. You should be able to copy the code in your preferred language, then paste in your Client ID and Client Secret and be good to go.

Here’s an example that prints the output of a token request in Python:

#!/bin/env python

import hashlib
import hmac
import time
import requests
import base64

# Client credentials
client_id = "<Your API Client ID goes here>"
client_secret = "<Your API Client Secret goes here>"

# Create signature
timestamp = int(time.time())
to_sign = "%s%s" % (timestamp, client_id)
signature = hmac.new(client_secret, to_sign, hashlib.sha256).hexdigest()

# Prepare http request headers
headers = { "X-Frame-ClientId": client_id, "X-Frame-Timestamp": str(timestamp), "X-Frame-Signature": signature }

# Include optional params such as first_name, last_name, email_domain, email or metadata.
body = {}

# Make request
r = requests.post("https://api.frame.nutanix.com/v1/accounts/<Account ID goes here>>/secure-anonymous/<Secure anonymous provider ID goes here>/tokens", headers=headers, data=body)

# Print the response (a JWT)
print r.json()

Optional Anonymous Token Parameters

You can provide a few optional parameters when generating anonymous tokens. These parameters let you customize the information provided in the JWT, allowing you to set properties such as:

  • First Name
  • Last Name
  • Email Address
  • Email Domain