Step 1 — Get authorization code

Since the authorization code grant type flow is a redirection-based flow, the OAuth2 client you have created is capable of interacting with the Knox end-customer’s user-agent (typically a web browser) and capable of receiving incoming requests (through redirection) from the Knox authorization server.

If Knox end-customer provides their consent to use requested Knox Cloud APIs, the authorization server issues an “authorization code” that can be exchanged for the access and refresh tokens to authenticate Knox Cloud API requests made by your OAuth2 client on behalf of the customer.

1. First, your organization portal needs to direct user-agent to Knox authorization endpoint with the request body parameters shown in the example below (for more details, please refer to Knox OAuth2 Authorization Server API).

   Authorization Code request example:

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

   1. Include Knox OAuth2 application client_id.

   2. Include the scope your customer is requesting access to (for example, use “ke” for Knox E-FOTA).

   3. Include the redirect URL (redirect_uri) which you specified when creating Knox OAuth2 application.

   4. Include a code_challenge as per the PKCE protocol.

      • First generate a code verifier, which, according to the PKCE protocol, 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.
      • Once the code verifier has been generated, hash it using SHA-256 code challenge method. The following are some examples of how to generate the code verifier and code challenge.
      • Bash example
      • Java example

      #!/bin/bash # Generate random code verifiercode_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); }}

   5. Specify code_challenge_method (Knox authorization server supports only SHA-256: code_challenge_method=S256).

   6. The state parameter, specifies an opaque value (a random string) used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. This parameter provides protection against certain attacks like Cross-Site Request Forgery (CSRF).

2. Knox authenticates your customer (using a Samsung account or other identity provider) and obtain their consent for you to manage their Knox cloud services. If the customer provides the consent, they are redirected to your application’s redirect URL with the authorization code and state parameter. Verify 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