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 paramaters, 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. If you’re on the Dashboard of an account, go to “Users > Authentication”. If you’re on the Admin page for the account, org, or customer level, go to “Security > Authentication.”
  2. Enable the API toggle and save - a new API tab will appear.
../../_images/add_api_0.png
  1. Click the API tab, then click “Add API”.
../../_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; it must be 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. You’ll see the new API show up in the 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. If you’re on the Dashboard of an account, go to Users -> Authentication. If you’re on the admin page for the account, org, or customer level, go to Security -> Authentication.
  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 click “Add Provider”.
../../_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:
Anonymous Provider Properties
Description A short description of what you plan to use the Anonymous Token provider for (e.g. public trials)
Token Duration how long until the token expires and is no longer valid.
Roles and Scope The role will typically be a launchpad user, and the scope is which account/Launchpad you’d like to provide access to via these tokens.

  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 options menu 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
Optional Anonymous Token Parameters
Name Type Description
first_name string “John” for example.
last_name string “Smith” for example.
email string Example: john.smith@acme.com
email_domain string Example: acme.com. This will return xxxxxxx@acme.com.