Enrollment Overview

This document discusses the methods for enrolling a new user and device combination into a customer’s Ionic tenant.

Terminology

Enrollment Ionic uses the term “enrollment” to refer to the process by which a device can both identify itself to the Ionic.com and establish a secure communications tunnel.
Note that historically this was sometimes referred to as “registering”.

In order to interact with Ionic.com, a device must first “enroll” with the platform. Enrolling a device uniquely associates the host (either physical hardware or some virtual machine) and the particular user logged in on that host. It also establishes a secure communication tunnel with Ionic.com as well as a second tunnel directly to the Enterprise Key Service.

Enrollment Profiles Enrollment will produce an artifact known as an “Enrollment Profile”. The enrollment profile is stored locally on disk by the enrolled device. Possession of a valid enrollment profile is required for any communication with Ionic.com. Each enrollment profile is unique to a particular Ionic tenant, host, and user.

Device Sometimes when “device” is mentioned it refers to a host (e.g. computer such as the physical hardware or a virtual machine). However, often (such as in the Ionic.com Dashboard views and APIs) a “device” refers to an Enrollment Profile (which is the intersection of a tenant, host, and user).

If you have signed up for an account in the Community Developer Tenant, use the below URL as the Enrollment URL for your enrollment methods:

Methods of Enrollment

Ionic’s Enrollment Service provides multiple capabilities for enrollment to account for different customer needs. Selecting the correct one for a specific use-case is important as it will greatly ease the enrollment of users or services into the Ionic ecosystem for the first time, enabling them to leverage the Ionic Platform.

Although you can develop against the Enrollment Server APIs and use the SDK to perform this process, Ionic also offers a few tools to help. The below table shows the types of enrollments supported by different tools. Note that the enrollment type is independent of the choice of persistor type used to store the resulting Secure Enrollment Profile. (SEP), which are shown here.

Enrollment Method Ionic Manager Server Enrollment Tool IonicRegister Sample Code
SAML IdP Y (GUI) N N
Email Token Y (GUI) N N
Oauth2 Y (GUI) N N
Generated SAML Assertion Y (CLI) Y Y

NOTE: The technical cryptography aspects of these processes, and subsequent key creates and fetches, are out-of-scope for this document. Contact your Ionic POC if detailed mathematical documentation is needed.

SAML

In this method, the user is sent from the customer’s enrollment portal to a configured corporate identity provider (IdP). The user then authenticates to the corporate identity provider and receives a SAML assertion. The assertion is then presented back to the customer’s enrollment portal which transforms it into an Ionic assertion, which is the same regardless of the enrollment method used. The user then completes enrollment to the customer’s key service via Ionic.com using the Ionic assertion.

These steps are illustrated in the below diagram:

NOTE: This method is sometimes used in development or demonstration tenants linked to an Ionic SAML IdP instead of a third-party corporate identity provider. This is not for production usage.

Prerequisites

You will need the following before beginning the enrollment process.

  1. A user account in the configured SAML IdP.

    • You will be prompted for an identifier, such as the email address, of an existing user in the IdP.
    • If your Ionic tenant is configured to use SAML-based user authentication, you will also need the Single Sign On (SSO) account credentials.
    • If you do not have an Identity Provider (IDP) with support for SAML authentication available, ask your Ionic representative about configuring Ionic.com to act as your IdP.
    • If you do not have “just-in-time” enrollment configured on your Ionic.com tenant, the user you authenticate with must already exist in Ionic.com. In this case, the users are typically pre-loaded using the SCIM API.
  2. The address of the enrollment server for your tenant. The case-sensitive enrollment server address should be provided by your Ionic POC or your internal deployment team.

OAuth

The documentation for this method will be available in an upcoming release. Contact your Ionic representative if you need documentation now.

Email Token

The documentation for this method will be available in an upcoming release. Contact your Ionic representative if you need documentation now.

Registration Options by Operating System

Registering a Windows Device

For graphical end-user enrollment, we currently support multiple options:

  • Download Ionic Manager, and then enroll (see Ionic Manager Registration instructions).
  • Download the Firefox or IE plugin, and then enroll. (Deprecated)

Registering an OSX Device

For graphical end-user enrollment, we currently support this options:

Registering on a Headless Server

There are some instances in which a service is operating on a server and needs to enroll, and thus a graphical end-user enrollment is not appropriate. In these cases, the developer may leverage the Server Enrollment Tool option.

Registration for Developers

This sections contains further technical information on device enrollment that may be of interest to Ionic SDK Developers.

Secure Enrollment Profiles

The enrollment process will produce an artifact known as an “Enrollment Profile”. The enrollment profile is stored locally by the registered device. Each enrollment profile is unique to a particular Ionic tenant, device, and user.

The method of storing these varies by “persistor” type and by the operating system. For example, on Windows, SEPs are secured using the Windows Data Protect API. On OSX, SEPs are secured using the OSX keychain.

Enrollment Profiles can be accessed programmatically through the Agent class in the Ionic SDK. If a device is already registered, and the SDK supports a default persistor, the profile will be loaded automatically by invoking Agent::Initialize().