Tutorial — Integration for EMMs

This tutorial guides third party portal providers through integrating with Samsung Account and Knox Cloud Services in order to:

• Add Samsung Account end customer authentication to a web portal
• Make calls from the web portal to Knox Cloud Services APIs on behalf of end customers

After you implement this authentication flow, your customers will be able to create a Samsung Account, sign up for Knox Cloud Services, and then establish a trust relationship with your service to start managing Knox data from your portal (shown in the following end customer registration diagram).

Authentication sequence diagram

The following diagram shows the 10-step authentication process and data flow:

Terms to know

• Knox cloud services — cloud services and REST APIs for products like Knox Mobile Enrollment and Knox Configure.
• end customer — a customer enrolled in one or more Knox Cloud Services who has also registered for Samsung Account.
• third party provider — a company providing a Knox-integrated service, allowing end customers to manage data without logging into a Knox admin portal.
• third party portal — a web portal hosted by a third party provider.
• Samsung Account (SA) — Samsung’s identity provider for Knox Cloud Services.
• Samsung Account access token — an OAuth2 token obtained from Samsung Account when the end customer signs into a third party portal through Samsung Account.
• KCS access token — a token used to make requests to Knox Cloud Services APIs, obtained from Knox Cloud Services with a valid Samsung Account access token.
• Refresh token — The access token can be easily re-issued using refresh token instead of doing the authentication all over again.

Before you start

Before you start, ensure that you’ve registered your portal for Samsung Account and for Knox cloud services (illustrated in the diagram below), and that you’ve prepared the following items:

Samsung Account client ID and secret

Locate your Samsung Account client ID and secret. If you need help with either, contact Knox Support with the following information:

• Redirect URL — The URL where the user will be redirected to once the Samsung Account authentication is completed.

• Alias ID — An identifier which maps the Samsung Account with a client ID. This needs to be passed by a third-party authenticator when calling the Samsung Account OAuth2 API (for example, https://account.samsung.com/accounts/v1/<thirdPartyAliasID>/signInGate).

Knox API token library

Download the Knox utility JAR (which supports Java version 1.6 and above) or the Knox token utility NuGet package. You’ll need this utility to sign your Samsung Account access and Knox Cloud Services access tokens.

Knox public/private key pair

Get your public/private key pair from the Knox API portal.

1. Launch the Knox API Portal from the Knox Partner Portal Dashboard. The Knox API portal works best with Chrome, Firefox, Safari, or Microsoft Edge.
2. From the portal, generate a public/private key pair called keys.json by clicking Download.

keys.json contains the following information:

• Public key — Sent in the body of the accessTokenOAuth2 APIs and stored by Samsung Knox to validate signed requests.
• Private key — Stored for your use and never revealed. This key is used for signing your Knox Cloud Services Client Identifier, Samsung Account access token, and Knox Cloud Services access token. This key is not stored by Samsung Knox and we will never request it from you.

Knox Client Identifier

Obtain your Client Identifier from the Knox API Portal. This unique identifier only needs to be generated once unless:

• Privileges need to be changed
• The Client Identifier is lost or stolen

In both cases, regenerating the Client Identifier invalidates the previous one. The image below shows the page you see when generating the Client Identifier from the portal.

Help end customers authorize your portal

End customers must enter your Knox partner ID into their Knox admin portal to authorize your service. This creates a full trust relationship, giving your portal permission to make calls to Knox Cloud Services on the end customer’s behalf.

For example, an end customer using Knox Mobile Enrollment (KME) should log into their KME admin portal and enter your Knox partner ID.

Your Knox partner ID is the unique ID issued by Knox Cloud Services when your service applies for access to a Knox Cloud Services API.

How you share your Knox partner ID is entirely up to you. Knox Cloud Services is not involved with sharing your Knox partner ID with end customers.

Steps

1. Authorize a user with Samsung Account

2. Generate a Knox Cloud Services signed access token

See also:

• Knox Cloud Services Third Party Integration (Authentication) REST API reference