API Onboarding Playbook

Introduction

While YubiEnterprise Delivery can be driven entirely through the pre-built console, it also comes with an API that provides the ability to extend the functionality to custom applications. This API will enable your organization’s developers to integrate the API into custom solutions that precisely meet the requirements of your business.

The following points are important to master before working with the API:

Data model complexity:
Shipment flow:	Make sure you understand the shipment request happy path flow and how to handle the error cases.
Testing:	Use an isolated sandbox environment to reduce testing time.
	The API exposes the YubiEnterprise Services data model. It is crucial to understand the difference between product identifiers and form factor identifiers.
Low inventory:	Prepare for initial stock running out by setting up pulling from the buffer or replacement stocks. Set up notification to admins of low inventory and automatically roll shipment requests to buffer and replacement stocks.

:App maintenance. The YubiEnterprise Services API occasionally makes breaking changes. Therefore, monitor all release notes and spin up a project to prepare for migration before the change goes live.

YubiEnterprise Delivery Self-Service Web Portal

This example in YubicoLabs GitHub repository will demonstrate an end-to-end solution with the ability to integrate the YubiEnterprise Delivery API into a web application that users in your enterprise (or beyond) could use to create YubiKey shipment requests drawing on your organization’s inventory.

In this project you will:

Stand up an environment in Amazon Web Services (AWS) to handle the server-side operations for the YubiEnterprise Delivery API and for handling user authentication/authorization
Use the YubiEnterprise Delivery API to create, delete, edit, and retrieve shipment requests as well as verify a shipment address
Create a front-end application for your end users to request shipment of a YubiKey that has been defaulted by your organization.

Guide

GitHub Repository: This repository contains the code and steps required to stand up an application in AWS capable of sending requests to your organization’s instance of YubiEnterprise Delivery.

Considerations

The aim of this guide is to demonstrate a barebones application that utilizes the YubiEnterprise Delivery API. The application should not be considered “production ready”. Below are a few of the considerations to keep in mind to ensure the success of your integration.

Policies to prevent abuse:
	This demo will allow a user to request shipment of as many keys as they desire. Additional logic will need to be built in to limit the number of shipment requests based on your requirements.
Selectable security Key:
	This demo is configured to order the YubiKey 5 NFC, and can be extended a variety of ways to allow different keys.
Error handling:	There is one section in this guide that describes handling methods if an error is sent during the initial order. For a production deployment, there are a variety of different error cases that should be considered such as low inventory, shipment failure, undeliverable address, etc.
Auto-filling address:
	Currently this guide assumes that the user will be shipping their key to the address listed in ServiceNow. The catalog item may need to be extended to allow the user to input their personal address (for example, if they are not located at one of your main offices). You may want to consider leveraging the YubiEnterprise Delivery Verify Address API to allow your users to correct any address errors prior to submitting a shipment request.

Configuration based on your security requirements:
	This includes swapping the system out to use your identity provider, secrets management in AWS Lambda, and other controls used by your organization.
People and process impacts to customer service:
	If your application is intended for external end users then your internal CX team needs to be prepared to handle inquiries relating to YubiEnterprise Delivery/YubiKey. Either an internal team should be established and trained to handle these items OR you can engage Yubico Professional Services.
Multi-region PO support:
	The current demo is configured for a purchase order covering a single region. You will need to use the proper API token for the user’s region, e.g. North America / Canada is one region, EMEA is a different region and each have their own associated API token.

More information can be found here.

ServiceNow Integration

For an organization that has fully integrated YubiEnterprise Delivery into its own internal systems via the APIs, the fulfillment experience is streamlined: the end-user receives an email notifying them that they are eligible for a YubiKey and/or that they are required to use the key for specific system access. The email directs the end-user to the corporate fulfillment system (e.g., ServiceNow). For more information, see ServiceNow Integrations.

Setting up API Caller and Generating Token

With regard to the API token,

Protect access to the API token, because whoever is in possession of the token is authorized to perform API operations for your organization.
Accounts that use machine tokens should have the Admin role, not the Owner role. This reduces the risk if the token is compromised, since the token has only the permissions associated with its role.
The fact that API tokens can easily be issued and revoked helps to assure the security of accounts that use machine tokens.
To handle machine token expiry, we recommend using the API (/auth/machine-token) to renew the API token. Ideally, logic should be put in to renew by calling the API to get a new token before the existing one expires.
If a user is removed from an organization and has a token in that organization, the token is revoked. If a user is suspended, all tokens are revoked. The tokens are left untouched if the user is reset or the password is reset.
Before an API token expires, the system generates and sends a notification to the associated email address. The email notifies that the token will expire in 7 days/1day and will not be accepted by our system after that.

Step 1:	Set up a sub-account for the application that will be calling the YubiEnterprise Delivery API. Detailed instructions for b and c below are given in Adding or Deleting an Org Member. Set up an email account for the application that will be calling the API. Ensure that you have access to it. The system automatically sends an email with login instructions to the new user. Use the YubiEnterprise Delivery Console (GUI) to create an account used solely by the API caller, for example, jan+api@example.com. Assign to the API caller’s account the YubiDelivery Admin role.
Step 2:	Activate the new API-calling account by clicking the login link in the email and following the on-screen prompts.
Step 3:	Associate a YubiKey for the API caller account with the YubiEnterprise login credentials: On the upper right of any YubiEnterprise Console page, go to the profile page of the API caller by clicking the initial for that account. Click Manage login credentials and enroll a YubiKey as a roaming credential. Note Consider registering a second YubiKey in case the first YubiKey becomes unavailable due to loss or theft.
Step 4:	Generate the API token: On the YubiEnterprise Console Profile page, click Generate new API token. Make a copy of the token and store it in a secure location. The token is displayed on the Console only at this time. Once you navigate away from the page you will no longer be able to view it. Note The API token is tied to an account AND an organization.

Authenticating with HTTP

The YubiEnterprise Delivery API supports the HTTP Bearer Authentication scheme. In order to authenticate with HTTP, you must provide your API token in the header of the request.

Copy your API token from its secure location and paste it into into a curl command in a bash script as shown below (the full token is not shown here).

curl "https://api.console.yubico.com/v1/inventory" \
--header "Authorization: Bearer eyJhb..."

Once you are logged into YubiEnterprise Delivery, you can view the YubiEnterprise Delivery public API at https://console.yubico.com/apidocs.

Dates and Times

All dates and times in requests from the API are UTC in the RFC-3339 format.

Users, Roles, and Organizations

Since API tokens are scoped to organizations, if an organization is shipping YubiKeys to both United States/Canada and to Europe, two API tokens are required: one for the US/CAN organization and one for the European organization.

An individual user can have one role in one organization and the same or a different role in another organization; for example, user Jan could be an owner in a company’s US/CAN organization and an Admin in the same company’s EU organization. However, because these are separate organizations, if Jan is logged in to the US/CAN YubiEnterprise, Jan cannot use that login to perform operations in the company’s EU YubiEnterprise.

Because it is possible to change the role of a user already in an organization, it is worth noting that deleting a user both:

Deletes that user’s association with the organization, and
Removes from that user the permissions associated with their role.

It is therefore possible in theory (though undesirable) for a user to be a member of an organization without having a role.

To file a support ticket for YubiEnterprise Delivery, click Support.