Tutorial — Knox Deployment Program (Knox Deployment Program) Integration

The aim of this integration is to be able to upload customer devices that are sold through [CARRIER COMPANY] with their customer-side Samsung Knox services, such as Knox Mobile Enrollment and Knox Configure.

Prerequisites and Documentation (General Steps)

1. Creating a Knox Deployment Program (Knox Deployment Program) account
2. Applying for Knox Deployment Program API access and getting your Access Key Pair
3. Ensuring you can generate session tokens (requires coding)
4. Create your access token
5. Integrating with the Knox Deployment Program APIs (requires coding)
6. Testing your Knox Deployment Program API Integration
7. Integrating your Knox Deployment Program integration with your internal systems
8. Go Live with your Knox Deployment Program API Integration

Step 1: Sign up for the Knox Deployment Program

1. Get access to the Reseller Portal.

2. Login to your account through the Knox Deployment Program Portal within the Samsung Knox dashboard.

3. Select LAUNCH CONSOLE to open the Knox Deployment Program Portal console.

4. Find your resellerId in the main dashboard of the console.

5. As soon as you apply, please email the [SALES ENGINEER] to let them know that the application has taken place.

   • Please provide the Samsung account (email address) that you have used to apply.
   • This will fast-track your application.

Step 2: Apply for Knox Deployment Program API access and getting your Access Key Pair

As soon as you get your Knox Deployment Program account, log into the Samsung Knox Resellers page.

• Click on Apply for Knox Deployment Program API access.

• Please email the [SALES ENGINEER] to let them know.

  • Alternatively, you can apply for Knox Cloud API access to the cloud REST service by contacting your local Samsung representative or raise a support ticket.

• Once you receive your API access approval, log into the Samsung Knox Resellers page.

• Download your Key pair and generate your clientIdentifier from the Knox Cloud APIs by following Steps 1, 2, and 3 of the Knox Cloud Authentication Developer Guide.

  • The clientIdentifier can be re-generated through the console, but must be bound to the downloaded certificate, as described in the Knox Web Services overview.

For more information, see the Knox Web Services overview.

Step 3: Ensure you can generate session tokens

Creating the session token is a security-heavy process and is required for any Cloud API call.

• Follow Steps 4 to 8 of the Knox Cloud Authentication Developer Guide.

• As a practical guide, use the attached sample JavaScript token signing and session token generating code.

  • There are JavaScript and Native Java libraries to integrate.

  • We created a sample script on JavaScript, based on the APIs for the Knox Cloud APIs Integration.

    1. The name of the file is SampleSessionID-GeneratingCode.gz.

    2. The .gz file can be opened with Winzip. It needs to be renamed as.js and is meant to be run with node (The file name is modified so your antivirus does not catch it).

    3. You need to install node.js and the Samsung JavaScript libraries as per the guide.

Step 4: Create your access token

Call the access token REST API to generate your access token x-knox-apitoken.

Step 5: Integrate with the Knox Deployment Program APIs

At a minimum, these are the APIs that you need to integrate with:

• Upload Devices

    PUT /kcs/v1/rp/devices/upload HTTP/1.1
    host: https://us-kcs-api.samsungknox.com
    content-type: application/json
    x-knox-apitoken: "<insert-token-step-4>"

• List Device Transaction Status

    GET /kcs/v1/rp/devices/status?resellerId="<your-reseller-id>"&customerId="<your-customer-id>"; HTTP/1.1
    host: https://us-kcs-api.samsungknox.com
    content-type:application/json
    x-knox-apitoken: "<insert-token-step-4>"

• Delete Devices

    PUT /kcs/v1/rp/devices/delete HTTP/1.1
    host: https://us-kcs-api.samsungknox.com
    content-type:application/json
    x-knox-apitoken: "<insert-token-step-4>"

• Optionally, you can use the List Devices API to view all successfully loaded devices for a customer.

    GET /kcs/v1/rp/devices?resellerId="<your-reseller-id>"&pageSize=100&pageNum=0
    host: https://us-kcs-api.samsungknox.com
    content-type:application/json
    x-knox-apitoken: "<insert-token-step-4>"

• You can also access the list of customers in your portal by using the List Reseller’s Customers API (optional as well).

    GET /kcs/v1/rp/customers/list?resellerId="%lt;your-reseller-id>" HTTP/1.1
    content-type:application/json
    x-knox-apitoken: "<insert-token-step-4>"
    host: https://us-kcs-api.samsungknox.com

Evaluate any additional APIs and specific methods with which you might wish to integrate.

As a participating Knox Deployment Program reseller, you are responsible for uploading devices purchased by your customers for access to Knox Mobile Enrollment, Knox Configure, and other Knox cloud services. The association between the reseller and the customer is automatically created during a device’s first upload based on their customerId.

Step 6: Test your Knox Deployment Program API Integration

Since you are testing as a Samsung Device Vendor you will need a Samsung Knox Customer-Side Knox Mobile Enrollment account for testing the end-to-end flow.

Create a different Knox Portal account than the account used on Step 1 above.

• Head to the Samsung Knox Customers page.
• Click Enroll (top, right-hand side).
• This application button will have you create a Samsung Account.
• This means that you will temporarily be taken to account.samsung.com where you can create a Samsung account with a test email address.
  1. You can use any email address that is not from a free email provider (that is, use a business email address).
  2. The Samsung Account will serve as the Single Sign On for the Knox Portal.
• Once you create the Samsung Account, you will be re-routed back to the main Knox Portal and will have access.

Get Knox Mobile Enrollment access for your newly-created test account.

• Once you are inside the Knox Portal, go to Knox Suite > Knox Mobile Enrollment and request access.

Ensure that you can upload and delete devices against a (test) customer-side Samsung Knox Customer account.

Step 7: Integrate your Knox Deployment Program integration with your internal systems

The effort and duration of this project stage is dependent on your integration resources, technical availability and internal system complexity.

Step 8: Go Live with your Knox Deployment Program API Integration

Once all your internal and Knox Deployment Program API integration testing is complete, you are ready to go live with your Knox Deployment Program integration and to upload devices to customer’s environments.

Coordinate with your Samsung representative on go-live steps.