Step 1 — Get authorization code

The authorization code grant type lets your registered app interact with the end user’s agent, typically a web browser, 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 the access and refresh tokens. These tokens are used to authenticate the Knox cloud services API requests, which your app makes on the behalf of your end user.

1. First, your app directs the user-agent to the GET /oauth2/authorize operation with the request body parameters as shown in the following sample:

   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
   

   The authorization code request sample must:

   • Include your app’s client_id.

   • Include the scope to define the scope of the access request. See scopes for Knox cloud services APIs for the list of available scopes.

   • Include the redirect URL (redirect_uri) that you specified when creating your app.

   • Include a code_challenge as per the PKCE protocol. It’s required to use this, to prevent you from engaging in insecure end-user flows.

     1. First, generate a code verifier, according to the Proof Key for Code Exchange (PKCE) protocol, it is a high-entropy cryptographic random string with a length between 43 and 128 characters. It can contain letters, digits, underscores, periods, hyphens, or tildes.

     2. Hash the generated code verifier using SHA-256 code challenge method.

     The PKCE is a security enhancement for the OAuth 2.0 authorization framework. Ensure that your app stores the code verifier in the backend only, and never sends or exposes it through the frontend or web browser. The best practices to securely store the PKCE code verifier in your app are as follows:

     • Secure database: Use a secure database with robust credentials.

     • Secure transmission: Transmit the code verifier over a secure, encrypted channel.

     • Rotation or deletion: Promptly delete or replace the code verifier after using it one-time only.

   The following are some examples of 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);
       }
   }
   

   • Specify code_challenge_method. Knox authorization server supports only SHA-256: code_challenge_method=S256.

   • The state parameter, specifies an opaque value, and is a random string used by the client to maintain the state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. It’s mandatory to use this parameter, it provides protection against certain attacks, such as Cross-Site Request Forgery (CSRF).

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

   When the end user provides consent, they’re redirected to your app’s redirect URL with the authorization code and the state parameter. Ensure that the value of state parameter is what you initially specified in the authorization code request.

   Redirect URL example:

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

For more information, see Knox OAuth 2.0 Authentication API.