Menu

Generate a Knox Cloud Services signed access token

Retrieving and signing a Knox Cloud Services (KCS) access token forms the second stage of third party integration with KCS. Ensure you have a valid Samsung Account access token before proceeding. For more information on retrieving a Samsung Account access token, see Authorize a user with Samsung Account.

1. Sign your Client Identifier with your Samsung Account access token

Sign your Knox Client Identifier with the Knox token utility using your Samsung Account access token. For more information on downloading and using the Knox token utility, see Knox API token library.

You can get your public key using KnoxTokenUtility.generateBase64EncodedStringPublicKey( ) as shown:

   // Downloaded from the Knox Portal 
    String clientIdentifier = <Your Client Identifier>; 
    String downloadedKeys = <insert path to keys.json>; 
 
    // Retrieved using the Samsung Account token API  
    String saAccessToken = < Your Samsung Account access token >; 


    String publicKey = KnoxTokenUtility.generateBase64EncodedStringPublicKey(
                                    new FileInputStream(new File(downloadedKeys))); 
    String signedClientIDJWT = KnoxTokenUtility.generateSignedClientIdentifierJWTWithIdpAccessToken(
                                    new FileInputStream(new File(downloadedKeys)),
                                    clientIdentifier, 
                                    saAccessToken);

2. Get and sign a KCS session token

You must first establish a KCS session on behalf of the logged-in customer by requesting a token from the sessiontoken endpoint. You’ll use this session token to request a KCS access token.

A session’s validity can either be tied to the identity provider's session (default) or be explicitly set by including a value for validityForSessionTokenInHours in the request body.

Example sessiontoken request body:

    { 
        "clientIdentifierJWT": < signedClientIDJWT >, 
        "base64EncodedStringPublicKey": < publicKey >, 
        "validityForSessionTokenInHours": 24 
    }

Now sign your session token with the Knox token utility:

    String signedSessionTokenJWT = KnoxTokenUtility.generateSignedSessionTokenJWT(	
					new FileInputStream(new File(downloadedKeys)), 
					< Your unsigned KCS session token >);

4. Get a KCS access token

Generate your access token by passing your signed session token and public key to the accesstoken endpoint. Optionally set the token’s validity by including a value for validityForAccessTokenInMinutes in the request body.

Example accesstoken request body:

    { 
        "sessionTokenJWT": < signedSessionTokenJWT >, 
        "base64EncodedStringPublicKey": < publicKey >, 
        "validityForAccessTokenInMinutes": 30 
    }

NOTE - When your KCS access token expires, you can use the sessiontoken endpoint to repeatedly request a new access token until the session token is invalidated or expires. You must sign the session token before each of these requests to avoid replay attacks.

Example response:

    { 
        "accessToken": "<Your unsigned KCS access token >" 
    }

5. Sign your KCS access token

Sign your access token with your private key using the Knox token utility. The access token will be valid for 30 minutes once signed. 

    String signedAccessToken = KnoxTokenUtility.generateSignedAccessTokenJWT(
                                   new FileInputStream(new File(downloadedKeys)), 
                                   < Your unsigned KCS access token >);

6. Start making KCS API calls

This completes the third party integration tutorial. You can now start making calls to KCS APIs to access end customer data with your signed KCS access token.

Include your signed KCS access token as a header parameter when requesting resources on behalf of your customer. Check out step 5 of the KME tutorial to see an example of using the KME API to assign device profiles.

You can also browse the detailed KME API reference, which includes example calls.

NOTE - If this step fails, ensure that your end customers have established a full trust relationship with your portal.

See also: