Step 1 — Get authorization code

The authorization code grant type lets your registered app interact with the end user’s agent, and receive incoming requests from the Knox authorization server through redirection.

When the end user provides consent for use of requested Knox cloud services APIs, the Knox authorization server issues an authorization code that is exchanged for access and refresh tokens. These tokens are used to authenticate Knox cloud services API requests, which your app makes on behalf of your end user.

Prerequisites

Before you begin, ensure you have:

• Registered a new cloud app and obtained your Client ID
• Configured your Redirect URI in the Knox Developer Portal
• Added the necessary scopes that your app requires

Requesting the authorization code

Direct the user‑agent (usually a web browser) to the GET /oauth2/authorize endpoint.

For example:

https://api.samsungknox.com/ams/v1/oauth2/authorize?response_type=code
    &client_id=example-client&scope=kai
    &redirect_uri=https://example-app.com/redirect
    &code_challenge=1234abcd123abCd1a2BCdaBCdab3cDABcdaBcDABcD
    &code_challenge_method=S256&state=abcde

Required query parameters

Implementing PKCE

PKCE (Proof Key for Code Exchange) is a security enhancement for the OAuth 2.0 authorization framework. It prevents authorization code interception attacks by requiring the client to prove it originally requested the authorization code.

PKCE security best practices

To securely store the PKCE code verifier in your app:

• Use a secure database with robust credentials
• Transmit the code verifier over a secure, encrypted channel (HTTPS)
• Promptly delete or replace the code verifier after one-time use
• Never log or expose the code verifier in error messages

Generating the code verifier and code challenge

Follow these steps to implement PKCE:

1. Generate a code verifier — Create a high-entropy cryptographic random string with a length between 43 and 128 characters. It can contain letters, digits, underscores, periods, hyphens, or tildes. Include this in your request for an access token.

2. Hash the code verifier — Use the SHA-256 algorithm to create a hash of the code verifier.

3. Create the code challenge — Base64 URL-encode the hash without padding. Include this in your request for an authorization code.

The following examples demonstrate how to generate the code verifier and code challenge:

• Bash example
• Java example

#!/bin/bash
# Generate random code verifier
code_verifier=$(openssl rand -hex 32)

# Hash and base64 url encode code verifier
code_challenge=$(echo -n "$code_verifier" | openssl dgst -sha256 -binary | base64 | tr '/+' '_-' | tr -d '=')

echo "Code Verifier: $code_verifier"
echo "Code Challenge: $code_challenge"

import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.security.SecureRandom;
import java.util.Base64;

public class PKCEGenerator {
    public static void main(String[] args) throws NoSuchAlgorithmException {
        // Generate a secure random code verifier
        SecureRandom sr = new SecureRandom();
        byte[] code = new byte[32];
        sr.nextBytes(code);
        String codeVerifier = Base64.getUrlEncoder().withoutPadding().encodeToString(code);

        // Generate a code challenge from the code verifier
        MessageDigest md = MessageDigest.getInstance("SHA-256");
        byte[] digest = md.digest(codeVerifier.getBytes());
        String codeChallenge = Base64.getUrlEncoder().withoutPadding().encodeToString(digest);

        System.out.println("Code Verifier: " + codeVerifier);
        System.out.println("Code Challenge: " + codeChallenge);
    }
}

End user authentication

The Knox authorization server authenticates your end user using Samsung Account or another identity provider, and obtains their consent for you to manage their Knox cloud services resources.

Authentication flow

1. The end user is redirected to the Knox authorization server’s login page.

2. The user authenticates using their Samsung Account credentials.

3. The authorization server displays a consent screen showing the permissions your app is requesting (based on the scopes).

4. The user reviews and grants consent.

Receiving the authorization code

When the end user provides consent, they’re redirected to your app’s redirect URI with the authorization code and the state parameter.

Here’s an example of a redirect URI:

https://example-app.com/redirect?code=abcdefghijKL&state=abcde

Next steps

After receiving the authorization code, proceed to Step 2 — Get access and refresh tokens.