Menu

Tutorial: Third party integration

NOTE - While this authentication flow incorporates parts of the general Samsung Account and KCS authentication protocols, it is not the same and should only be used for third party portal integration. This flow uses a set of specially designed APIs for third party integration maintained separately from the standard Samsung Account and KCS authentication APIs.

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

  • Add Samsung Account end customer authentication to a web portal
  • Make calls from the web portal to KCS 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 KCS, 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).

end customer registration flow

Authentication sequence diagram

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

Terms to know

  • Knox Cloud Services (KCS) - 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 KCS.
  • 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 session token – a token that establishes a login session for an end customer, obtained from KCS with a valid Samsung Account access token.
  • KCS access token – a token used to make requests to KCS APIs, obtained from KCS with a valid KCS session token.

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.

third party portal registration flow

Samsung Account client ID and secret

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

When you have your client ID, contact the Knox Support team to add further permissions to your client ID.

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 KCS session and 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 Samsung Knox Dashboard. The Knox API portal works best with Chrome, Firefox, Safari, and Internet Explorer 10 or 11.
  2. From the portal, generate a public/private key pair called keys.json by clicking Download.

WARNING - keys.json can only be generated once and cannot be restored if lost.

keys.json contains the following information:

  • Public key - Sent in the body of the sessiontoken and accesstoken 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 KCS Client Identifier, session token, and 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.

Generating your Client Identifier in the Knox Portal

Help end customers authorize your portal

End customers must enter your Knox customer ID into their Knox admin portal to authorize your service. This creates a full trust relationship, giving your portal permission to make calls to KCS 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 KME customer ID.

Your customer ID is the unique ID issued by KCS when your service applies for access to a KCS API.

How you share your customer ID is entirely up to you. KCS is not involved with sharing your customer ID with end customers.

Steps

1. Authorize a user with Samsung Account

2. Generate a Knox Cloud Services signed access token

See also: