Implement OAuth 2.0 with Java Management SDK

You can use OAuth 2.0 in the Java Management SDK to securely access Contentstack APIs through token-based authentication. The SDK handles token acquisition, refresh, and management for you, so you focus on building features instead of handling authentication.

Note: Use contentstack-management-java v1.8.0 or later with a registered OAuth app in Contentstack.

Prerequisites

• Install contentstack-management-java v1.8.0 or later
• Register an OAuth application in Contentstack
• Collect required credentials:
  • client_id
  • client_secret (optional, not needed for PKCE flow)
  • app_id
  • redirect_uri

OAuth 2.0 Flow

The SDK simplifies the OAuth 2.0 flow by handling token acquisition, refresh, and storage.

1. User Authorization: The SDK generates an authorization URL and directs the user to Contentstack’s Authorization Server to log in and grant access to the application.
2. Access Granted: The Authorization Server redirects the user back to the app’s redirect_uri with an authorization code.
3. Exchange Authorization Code for Tokens: The SDK exchanges the code for:
   • An access token for authenticated API requests.
   • A refresh token to renew the access token when it expires.
4. Store Tokens: The SDK stores tokens in memory and provides hooks to persist them securely across sessions.
5. Make Authenticated API Requests: The SDK automatically attaches the access token to outgoing API requests, allowing your app to securely interact with Contentstack APIs.
6. Automatically Refresh Tokens: When the access token expires, the SDK uses the refresh token to request a new one without interrupting the current session.
7. Logout and Clear Tokens: On logout, the SDK clears stored tokens and can optionally revoke access.

Using OAuth in Java Management SDK

The following steps show the OAuth 2.0 flow in the Java Management SDK, from authorization to logout.

1. Initialize the OAuth Handler

   Use the following code to initialize OAuth with the required credentials.

   Contentstack client = new Contentstack.Builder()
   .setHost("api.contentstack.io") // optional, region-specific
   .setOAuth(APP_ID, CLIENT_ID,REDIRECT_URI, CLIENT_SECRET) // Standard OAuth
   // or use PKCE if client_secret is not available
   .build();

   Parameters

   Parameter	Type	Description
   appId	Required	Your registered App ID.
   clientId	Required	Your OAuth Client ID.
   redirectUri	Required	The URL where the user is redirected after login and consent.
   responseType	Optional	Set to code by default. You can customize it based on your OAuth settings.
   clientSecret	Optional	Required for standard OAuth flows (skip if using PKCE).
   scope	Optional	Permissions requested, such as read-only or full access, depending on your app’s requirements.

2. Start the Authorization Flow

   The getOAuthAuthorizationUrl() method redirects the user to Contentstack’s OAuth server to login and authorize your app. To log in, use the code below:

   String authUrl = client.getOAuthAuthorizationUrl();
   // Example: open in browser
   Desktop.getDesktop().browse(new URI(authUrl));
   // Example: load in WebView
   webView.loadUrl(authUrl);

3. Handle Redirect and Exchange Token

   After authorization, the server redirects the user back to your redirect_uri with an authorization code. Handle this redirect in your app using the exchangeOAuthCode(code) method.

   // Example: Android WebView
   webView.setWebViewClient(new WebViewClient() {
     @Override
     public boolean shouldOverrideUrlLoading(WebView view, String url) {
       if (url.startsWith(REDIRECT_URI)) {
         Uri uri = Uri.parse(url);
         String code = uri.getQueryParameter("code");
         if (code != null) {
           client.exchangeOAuthCode(code)
             .thenAccept(tokens -> {
               // Success - SDK will use tokens automatically
             })
             .exceptionally(error -> {
               // Add error-handling logic here
               return null;
             });
         }
         return true;
       }
       return false;
     }
   });

   The exchangeOAuthCode(code) method returns a CompletableFuture with access and refresh tokens.

4. Token Storage

   Use the TokenCallback interface to implement custom logic for securely storing and clearing tokens in memory.

   public class TokenStorageHandler implements TokenCallback {
     @Override
     public void onTokensUpdated(OAuthTokens tokens) {
       // TODO: Implement your storage logic
       // Examples:
       // - Save to SharedPreferences (Android)
       // - Save to encrypted file (Desktop)
       // - Save to secure database (Server)
     }
   
     @Override
     public void onTokensCleared() {
       // TODO: Implement your clear logic
       // Remove tokens from your storage
     }
   }
   
   // Add the handler to your OAuth handler
   Contentstack client = new Contentstack.Builder()
     .setTokenCallback(new TokenStorageHandler())
     .setOAuth(APP_ID, CLIENT_ID, REDIRECT_URI, CLIENT_SECRET)
     .build();

5. Make Authenticated API Requests

   To make authenticated API requests, use the following code snippet. The SDK automatically adds the access token to the Authorization header as a Bearer token for all outgoing requests.

   Stack stack = client.stack("stack_api_key");
   Response<ResponseBody> entryResult =
     stack.contentType("contentType_uid").entry("entry_uid").fetch().execute();
       

6. Refresh Access Token

   To refresh the access token when it expires, use the following code snippet. The SDK uses the refresh token to automatically request a new one.

   client.refreshOAuthToken()
     .thenAccept(newTokens -> {
       // Tokens refreshed - SDK will use them automatically
     })
     .exceptionally(error -> {
       // Add logic to handle token refresh errors
       return null;
     });

   This ensures that your application continues to make authenticated requests without requiring the user to log in again.

7. Logout and Revoke Access

   Use the logout() method to log out the user and revoke authorization:

   // logout (clear tokens)
   client.oauthLogout()
     .thenRun(() -> {
       // Logged out successfully
     });
   
   // Logout and revoke authorization
   client.oauthLogout(true) // true = revoke authorization
     .thenRun(() -> {
       // Logged out and revoked
     });

   Reference

   Methods	Description
   getOAuthAuthorizationUrl()	Get authorization URL for user login.
   exchangeOAuthCode(code)	Exchange authorization code for tokens.
   refreshOAuthToken()	Manually refresh the access token.
   setTokenCallback(callback)	Set handler for token storage events.
   oauthLogout()	Logout and clear tokens.
   oauthLogout(true)	Logout and revoke authorization.

Token Storage

After authentication, tokens are managed in memory. However, if needed, you can store them using the following methods:

Web Applications

Choose a storage strategy based on session duration and security:

• Session Storage: Temporary storage that lasts only till the browser session. Ideally used for short-lived sessions for increased security.
  sessionStorage.setItem('access_token', oauthHandler.getAccessToken());
      

• Local Storage: Stores tokens persistently across sessions but is more vulnerable to XSS. Use it carefully.
  localStorage.setItem('access_token', oauthHandler.getAccessToken());
      

• Cookies: Tokens are sent automatically with HTTP requests. Use secure attributes to enhance protection.
  document.cookie = `access_token=${oauthHandler.getAccessToken()}; path=/; Secure; HttpOnly`;
      

Mobile and Server Applications

1. Android Applications

   Choose based on your security requirements:

   • EncryptedSharedPreferences
     • Android's recommended secure storage
     • Handles encryption automatically
     • Best for most Android applications
   • Android Keystore
     • Hardware-backed security when available
     • Highest level of security
     • Suitable for storing sensitive credentials
2. Desktop/Server Applications

   Choose based on your application's needs:

   • In-memory Storage
     • Tokens exist only during runtime
     • Cleared when application exits
     • Best for short-running applications
   • Encrypted File Storage
     • Persistent storage between sessions
     • Must implement proper encryption
     • Suitable for long-running applications