OAuthConfig

View as Markdown

OAuthConfig

OAuthConfig holds the settings of the Contentstack app that the Java Management SDK uses for an Open Authorization (OAuth) sign-in. It holds the app UID, the client ID, the redirect URI, an optional client secret, the scopes and the region host. Use this class to

  • set options that the setOAuth method of Contentstack.Builder does not take, such as scopes or endpoint overrides
  • attach a TokenCallback that saves new tokens
  • read the authorization and token URLs that the SDK uses

Create one with OAuthConfig.builder(), set the values, and call build. Pass the result to the setOAuthConfig method of Contentstack.Builder. The setOAuth method of Contentstack.Builder builds one for you. Read it with client.getOAuthHandler().getConfig(). OAuthConfig has no public constructor and no setters, so its values stay fixed after build.

NameTypeDescription
appId String

appId, getAppId. UID of the Contentstack app.

clientId String

clientId, getClientId. OAuth client ID of the app.

redirectUri String

redirectUri, getRedirectUri. URI that receives the authorization code.

clientSecret String

clientSecret, getClientSecret. Client secret of the app.

scope String

scope, scopes, getScope, getScopesList. Scopes the app asks for.

host String

host, getHost. API host of the region.

tokenCallback TokenCallback

tokenCallback, getTokenCallback. Receives new tokens.

responseType String

responseType, getResponseType. Value of response_type in the URL.

authEndpoint String

authEndpoint, getAuthEndpoint. Authorization page override.

tokenEndpoint String

tokenEndpoint, getTokenEndpoint. Token endpoint override.

appId

appId sets the UID of the Contentstack app that the user authorizes.

NameTypeDescription
appId (required)String

UID of the Contentstack app.

Default: Not applicable

Returns: OAuthConfigBuilder. The same builder, for chaining.

Validation

  • There is no client-side validation at this call. appId stores the value as given.
  • build() on Contentstack.Builder throws IllegalArgumentException if the value is missing or blank, because the SDK cannot start a sign-in without it.

Behavior

  • The SDK puts the value in the path of the authorization page and sends it as app_id in the authorization URL and in every token request.
  • Read the value back with the getAppId method.

Example

Basic usage: set the required values

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.OAuthConfig;

public class SetAppId {
    public static void main(String[] args) {
        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("<REDIRECT_URI>")
                .build();

        Contentstack client = new Contentstack.Builder()
                .setOAuthConfig(config)
                .build();
        System.out.println(client.getOAuthHandler().getConfig().getAppId());
    }
}

Error handling: catch a missing app UID

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.OAuthConfig;

public class MissingAppId {
    public static void main(String[] args) {
        OAuthConfig config = OAuthConfig.builder()
                .clientId("<CLIENT_ID>")
                .redirectUri("<REDIRECT_URI>")
                .build(); // build() on OAuthConfig does not check the values
        try {
            new Contentstack.Builder().setOAuthConfig(config).build();
        } catch (IllegalArgumentException e) {
            // Thrown when appId, clientId or redirectUri is missing, or the redirect URI is not a valid URL
            System.out.println("Invalid OAuth configuration: " + e.getMessage());
        }
    }
}

authEndpoint

authEndpoint sets the full URL of the authorization page, in place of the URL the SDK derives from the host.

NameTypeDescription
authEndpoint (required)String

HTTPS URL of the authorization page. Unset, the SDK derives it from the host.

Default: Not applicable

Returns: OAuthConfigBuilder. The same builder, for chaining.

Validation

  • There is no client-side validation at this call.
  • authorize throws IllegalArgumentException if the value is not a valid URL or does not use https, because the SDK sends users only to an HTTPS page.

Behavior

  • The SDK appends the query string to the value as given, starting with ?. Pass a URL without a query string.
  • The status and revoke requests of OAuthHandler also add /status and /revoke to this value.

Example

Basic usage: point the sign-in at a fixed page

import com.contentstack.cms.models.OAuthConfig;

public class SetAuthEndpoint {
    public static void main(String[] args) {
        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("<REDIRECT_URI>")
                .authEndpoint("https://eu-app.contentstack.com/#!/apps/<APP_ID>/authorize")
                .build();
        System.out.println(config.getFormattedAuthorizationEndpoint());
    }
}

build

build creates an OAuthConfig object from the values set on the builder.

Returns: OAuthConfig. A new configuration.

Validation

  • build does not check the values and does not throw.
  • The SDK checks them when you call build() on Contentstack.Builder after setOAuthConfig. Call validate to check them earlier.

Behavior

  • OAuthConfig has no setters, so its values stay fixed after build.
  • Pass the result to the setOAuthConfig method of Contentstack.Builder.

Example

Basic usage: build and check a configuration

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.OAuthConfig;

public class BuildOAuthConfig {
    public static void main(String[] args) {
        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("<REDIRECT_URI>")
                .build();
        try {
            config.validate();
        } catch (IllegalArgumentException e) {
            System.out.println("Invalid OAuth configuration: " + e.getMessage());
            return;
        }
        Contentstack client = new Contentstack.Builder()
                .setOAuthConfig(config)
                .build();
        System.out.println(client.isOAuthConfigured()); // true
    }
}

builder

builder creates an empty builder for an OAuthConfig object.

Returns: OAuthConfigBuilder. A new configuration builder.

Validation

  • There is no client-side validation.
  • builder does not throw.

Behavior

  • builder is a static method of OAuthConfig. The returned type is OAuthConfig.OAuthConfigBuilder.
  • OAuthConfig has no public constructor, so builder is the way to create one yourself.
  • Set at least appId, clientId and redirectUri, then call build.

Example

Basic usage: build a configuration for a PKCE sign-in

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.OAuthConfig;

public class BuildPkceConfig {
    public static void main(String[] args) {
        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("<REDIRECT_URI>")
                .build();

        Contentstack client = new Contentstack.Builder()
                .setOAuthConfig(config)
                .build();
        System.out.println(client.getOAuthHandler().authorize());
    }
}

clientId

clientId sets the Open Authorization (OAuth) client ID of the app.

NameTypeDescription
clientId (required)String

OAuth client ID of the app.

Default: Not applicable

Returns: OAuthConfigBuilder. The same builder, for chaining.

Validation

  • There is no client-side validation at this call. clientId stores the value as given.
  • build() on Contentstack.Builder throws IllegalArgumentException if the value is missing or blank, because the SDK cannot start a sign-in without it.

Behavior

  • The SDK sends the value as client_id in the authorization URL and in every token request.
  • Read the value back with the getClientId method.

Example

Basic usage: set the client ID

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.OAuthConfig;

public class SetClientId {
    public static void main(String[] args) {
        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("<REDIRECT_URI>")
                .build();

        Contentstack client = new Contentstack.Builder()
                .setOAuthConfig(config)
                .build();
        System.out.println(client.getOAuthHandler().getConfig().getClientId());
    }
}

clientSecret

clientSecret sets the client secret of the app, so the SDK uses the secret instead of Proof Key for Code Exchange (PKCE).

NameTypeDescription
clientSecret (required)String

Client secret of the app. Unset, the SDK uses PKCE.

Default: Not applicable

Returns: OAuthConfigBuilder. The same builder, for chaining.

Validation

  • There is no client-side validation.
  • Leave clientSecret unset, or pass null, for PKCE. An empty string turns PKCE on for the authorization URL but makes the authorization code exchange send an empty secret without the PKCE verifier, so the exchange fails.

Behavior

  • With a secret, the SDK sends it as client_secret in the authorization code exchange and in every refresh request, and the authorization URL carries no PKCE challenge.
  • Without a secret, the SDK uses PKCE. isPkceEnabled reports the mode.
  • Keep the secret on a server. Do not ship it in an app that runs on a user's device.

Example

Basic usage: use a client secret on a server

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.OAuthConfig;

public class SetClientSecret {
    public static void main(String[] args) {
        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("<REDIRECT_URI>")
                .clientSecret(System.getenv("CONTENTSTACK_CLIENT_SECRET"))
                .build();

        Contentstack client = new Contentstack.Builder()
                .setOAuthConfig(config)
                .build();
        System.out.println(config.isPkceEnabled()); // false when the variable holds a secret
    }
}

getAppId

getAppId returns the UID of the Contentstack app that appId set.

Returns: String. The app UID, or null.

Validation

  • There is no client-side validation.
  • getAppId does not throw.

Behavior

  • Returns null when the builder never set the value. A client cannot use such a configuration, because the SDK rejects it at build time.

Example

Basic usage: read the value from a client

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.OAuthConfig;

public class ReadAppId {
    public static void main(String[] args) {
        Contentstack client = new Contentstack.Builder()
                .setOAuth("<APP_ID>", "<CLIENT_ID>", "<REDIRECT_URI>")
                .build();
        OAuthConfig config = client.getOAuthHandler().getConfig();
        System.out.println(config.getAppId());
    }
}

getAuthEndpoint

getAuthEndpoint returns the authorization page URL that authEndpoint set.

Returns: String. The authorization page override, or null.

Validation

  • There is no client-side validation.
  • getAuthEndpoint does not throw.

Behavior

  • Returns the value as given, without the HTTPS check.
  • Returns null when the configuration holds no override. getFormattedAuthorizationEndpoint returns the URL that the SDK uses in both cases.

Example

Basic usage: read the value from a client

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.OAuthConfig;

public class ReadAuthEndpoint {
    public static void main(String[] args) {
        Contentstack client = new Contentstack.Builder()
                .setOAuth("<APP_ID>", "<CLIENT_ID>", "<REDIRECT_URI>")
                .build();
        OAuthConfig config = client.getOAuthHandler().getConfig();
        System.out.println(config.getAuthEndpoint()); // null, setOAuth sets no override
    }
}

getClientId

getClientId returns the Open Authorization (OAuth) client ID that clientId set.

Returns: String. The client ID, or null.

Validation

  • There is no client-side validation.
  • getClientId does not throw.

Behavior

  • Returns null when the builder never set the value. A client cannot use such a configuration, because the SDK rejects it at build time.

Example

Basic usage: read the value from a client

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.OAuthConfig;

public class ReadClientId {
    public static void main(String[] args) {
        Contentstack client = new Contentstack.Builder()
                .setOAuth("<APP_ID>", "<CLIENT_ID>", "<REDIRECT_URI>")
                .build();
        OAuthConfig config = client.getOAuthHandler().getConfig();
        System.out.println(config.getClientId());
    }
}

getClientSecret

getClientSecret returns the client secret that clientSecret set.

Returns: String. The client secret, or null.

Validation

  • There is no client-side validation.
  • getClientSecret does not throw.

Behavior

  • Returns null for a PKCE configuration. The setOAuth method of Contentstack.Builder stores no secret when you pass null or a blank value.
  • The value is a secret. Do not log it.

Example

Basic usage: read the value from a client

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.OAuthConfig;

public class ReadClientSecret {
    public static void main(String[] args) {
        Contentstack client = new Contentstack.Builder()
                .setOAuth("<APP_ID>", "<CLIENT_ID>", "<REDIRECT_URI>")
                .build();
        OAuthConfig config = client.getOAuthHandler().getConfig();
        // Report the mode without printing the secret
        System.out.println(config.getClientSecret() == null ? "PKCE" : "Client secret");
    }
}

getFormattedAuthorizationEndpoint

getFormattedAuthorizationEndpoint returns the URL of the authorization page that the SDK uses to start a sign-in.

Returns: String. The authorization page URL without query parameters.

Validation

  • Throws IllegalArgumentException if authEndpoint set a value that is not a valid HTTPS URL.
  • Otherwise getFormattedAuthorizationEndpoint does not throw.

Behavior

  • Returns the authEndpoint value when set.
  • Otherwise derives the URL from the host, for example https://app.contentstack.com/#!/apps/{appId}/authorize without a host. The host method lists the derived URLs.
  • The URL carries no query parameters. authorize returns the full URL to open.

Example

Basic usage: print the authorization page

import com.contentstack.cms.models.OAuthConfig;

public class PrintAuthorizationPage {
    public static void main(String[] args) {
        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("<REDIRECT_URI>")
                .host("eu-api.contentstack.com")
                .build();
        System.out.println(config.getFormattedAuthorizationEndpoint());
        // https://eu-app.contentstack.com/#!/apps/<APP_ID>/authorize
    }
}

getHost

getHost returns the API host from which the SDK derives the sign-in URLs.

Returns: String. The API host, or null.

Validation

  • There is no client-side validation.
  • getHost does not throw.

Behavior

  • Returns null when the builder never called host. The SDK then uses the North America hosts.
  • The setOAuth method of Contentstack.Builder stores the host of the builder at the time of the call, api.contentstack.io by default.

Example

Basic usage: read the value from a client

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.OAuthConfig;

public class ReadOAuthHost {
    public static void main(String[] args) {
        Contentstack client = new Contentstack.Builder()
                .setOAuth("<APP_ID>", "<CLIENT_ID>", "<REDIRECT_URI>")
                .build();
        OAuthConfig config = client.getOAuthHandler().getConfig();
        System.out.println(config.getHost()); // api.contentstack.io
    }
}

getRedirectUri

getRedirectUri returns the redirect URI that redirectUri set.

Returns: String. The redirect URI, or null.

Validation

  • There is no client-side validation.
  • getRedirectUri does not throw.

Behavior

  • Returns null when the builder never set the value. A client cannot use such a configuration, because the SDK rejects it at build time.

Example

Basic usage: read the value from a client

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.OAuthConfig;

public class ReadRedirectUri {
    public static void main(String[] args) {
        Contentstack client = new Contentstack.Builder()
                .setOAuth("<APP_ID>", "<CLIENT_ID>", "<REDIRECT_URI>")
                .build();
        OAuthConfig config = client.getOAuthHandler().getConfig();
        System.out.println(config.getRedirectUri());
    }
}

getResponseType

getResponseType returns the response_type value that the SDK puts in the authorization URL.

Returns: String. The response type for the authorization URL.

Validation

  • There is no client-side validation.
  • getResponseType does not throw.

Behavior

  • Returns code when the builder never called responseType, or called it with null.

Example

Basic usage: read the response type

import com.contentstack.cms.models.OAuthConfig;

public class ReadResponseType {
    public static void main(String[] args) {
        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("<REDIRECT_URI>")
                .build();
        System.out.println(config.getResponseType()); // code
    }
}

getScope

getScope returns the scopes that the app asks for, as one string with a space between scopes.

Returns: String. The space-separated scopes, or null.

Validation

  • There is no client-side validation.
  • getScope does not throw.

Behavior

  • Returns null when neither scope nor scopes set a value.

Example

Basic usage: read the scopes

import com.contentstack.cms.models.OAuthConfig;

public class ReadConfigScope {
    public static void main(String[] args) {
        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("<REDIRECT_URI>")
                .scopes("user:read", "cm.stacks.management:read")
                .build();
        System.out.println(config.getScope()); // user:read cm.stacks.management:read
    }
}

getScopesList

getScopesList returns the scopes that the app asks for as a list, one scope per element.

Returns: List<String>. The scopes as a list.

Validation

  • There is no client-side validation.
  • Known issue: In 1.16.0 on Java 8, getScopesList throws NoSuchMethodError when the configuration holds no scope, because the SDK calls a method that Java 9 added. Check that getScope returns a non-empty value first, or run on Java 9 or later.

Behavior

  • getScopesList splits the scope string at each single space.
  • Returns an empty list when the configuration holds no scope.
  • The returned list has a fixed size. Calling add or remove on it throws UnsupportedOperationException.

Example

Basic usage: list the scopes

import com.contentstack.cms.models.OAuthConfig;
import java.util.List;

public class ListConfigScopes {
    public static void main(String[] args) {
        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("<REDIRECT_URI>")
                .scope("user:read cm.stacks.management:read")
                .build();
        String scope = config.getScope();
        if (scope != null && !scope.trim().isEmpty()) {
            List<String> scopes = config.getScopesList();
            System.out.println(scopes.size()); // 2
        }
    }
}

getTokenCallback

getTokenCallback returns the callback that tokenCallback set.

Returns: TokenCallback. The token event callback, or null.

Validation

  • There is no client-side validation.
  • getTokenCallback does not throw.

Behavior

  • Returns null when the configuration holds no callback.
  • With the setOAuth method of Contentstack.Builder, the value is the callback from setTokenCallback, when you call setTokenCallback before setOAuth.

Example

Basic usage: read the value from a client

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.OAuthConfig;
import com.contentstack.cms.oauth.TokenCallback;

public class ReadTokenCallback {
    public static void main(String[] args) {
        Contentstack client = new Contentstack.Builder()
                .setOAuth("<APP_ID>", "<CLIENT_ID>", "<REDIRECT_URI>")
                .build();
        OAuthConfig config = client.getOAuthHandler().getConfig();
        TokenCallback callback = config.getTokenCallback();
        System.out.println(callback != null ? "Callback set" : "No callback");
    }
}

getTokenEndpoint

getTokenEndpoint returns the URL that the SDK sends the authorization code exchange and refresh requests to.

Returns: String. The token endpoint URL.

Validation

  • Throws IllegalArgumentException if tokenEndpoint set a value that is not a valid HTTPS URL.
  • Otherwise getTokenEndpoint does not throw.

Behavior

  • Returns the tokenEndpoint value when set.
  • Otherwise derives the URL from the host, for example https://developerhub-api.contentstack.com/token without a host. The host method lists the derived URLs.

Example

Basic usage: print the token endpoint

import com.contentstack.cms.models.OAuthConfig;

public class PrintTokenEndpoint {
    public static void main(String[] args) {
        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("<REDIRECT_URI>")
                .build();
        System.out.println(config.getTokenEndpoint()); // https://developerhub-api.contentstack.com/token
    }
}

host

host sets the Content Management API host of your region, from which the SDK derives the authorization page and the token endpoint.

NameTypeDescription
host (required)String

API host of the region, such as eu-api.contentstack.com. Unset, North America.

Default: Not applicable

Returns: OAuthConfigBuilder. The same builder, for chaining.

Validation

  • There is no client-side validation at this call.
  • A host that is not a bare host name under contentstack.com or contentstack.io does not throw. The SDK ignores it and uses the North America hosts.

Behavior

  • Pass the API host of the region, such as eu-api.contentstack.com. The SDK derives the two URLs in the table below from it:
HostAuthorization pageToken endpoint
Not set, or api.contentstack.iohttps://app.contentstack.com/#!/apps/{appId}/authorizehttps://developerhub-api.contentstack.com/token
eu-api.contentstack.comhttps://eu-app.contentstack.com/#!/apps/{appId}/authorizehttps://eu-developerhub-api.contentstack.com/token
  • For other hosts, the SDK replaces -api. with -app. for the authorization page and with -developerhub-api. for the token endpoint.
  • authEndpoint and tokenEndpoint override the derived URLs.
  • When you use OAuthConfig without host, the SDK uses the North America hosts even when Contentstack.Builder sets another region.

Example

Basic usage: sign in through the EU region

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.OAuthConfig;

public class SetEuHost {
    public static void main(String[] args) {
        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("<REDIRECT_URI>")
                .host("eu-api.contentstack.com")
                .build();
        System.out.println(config.getTokenEndpoint()); // https://eu-developerhub-api.contentstack.com/token

        Contentstack client = new Contentstack.Builder()
                .setRegion("eu")
                .setOAuthConfig(config)
                .build();
        System.out.println(client.getOAuthHandler().authorize());
    }
}

isPkceEnabled

isPkceEnabled reports whether the sign-in uses Proof Key for Code Exchange (PKCE) instead of a client secret.

Returns: boolean. True when the flow uses PKCE.

Validation

  • There is no client-side validation.
  • isPkceEnabled does not throw.

Behavior

  • Returns true when the client secret is null, empty or blank.
  • With PKCE, the SDK adds a code challenge to the authorization URL and sends the matching verifier in the authorization code exchange.

Example

Basic usage: report the sign-in mode

import com.contentstack.cms.models.OAuthConfig;

public class ReportPkce {
    public static void main(String[] args) {
        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("<REDIRECT_URI>")
                .build();
        System.out.println(config.isPkceEnabled() ? "PKCE" : "Client secret"); // PKCE
    }
}

redirectUri

redirectUri sets the URI that Contentstack sends the user back to, with the authorization code, after sign-in.

NameTypeDescription
redirectUri (required)String

URI that receives the authorization code.

Default: Not applicable

Returns: OAuthConfigBuilder. The same builder, for chaining.

Validation

  • There is no client-side validation at this call. redirectUri stores the value as given.
  • build() on Contentstack.Builder throws IllegalArgumentException if the value is missing or blank, because the SDK cannot start a sign-in without it.
  • build() on Contentstack.Builder also throws IllegalArgumentException if java.net.URL cannot parse the value. http and https URIs pass. A custom scheme such as myapp://callback fails, because java.net.URL does not know the scheme.

Behavior

  • The SDK sends the value as redirect_uri in the authorization URL and in the authorization code exchange request.
  • Read the authorization code from the code query parameter of the request that reaches this URI, and pass it to the exchangeCodeForToken method of OAuthHandler.

Example

Basic usage: set a local redirect URI

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.OAuthConfig;

public class SetRedirectUri {
    public static void main(String[] args) {
        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("http://localhost:8080/callback")
                .build();

        Contentstack client = new Contentstack.Builder()
                .setOAuthConfig(config)
                .build();
        System.out.println(client.getOAuthHandler().getConfig().getRedirectUri());
    }
}

responseType

responseType sets the response_type value that the SDK puts in the authorization URL.

NameTypeDescription
responseType (required)String

Value of response_type in the URL. Unset, code.

Default: Not applicable

Returns: OAuthConfigBuilder. The same builder, for chaining.

Validation

  • There is no client-side validation.
  • responseType(null) restores the default, code.

Behavior

  • The default is code, the value for the authorization code flow that the SDK supports.
  • The SDK sends the value unchanged. The authorization code exchange in exchangeCodeForToken always uses the authorization code grant, whatever this value is.

Example

Basic usage: set the default response type explicitly

import com.contentstack.cms.models.OAuthConfig;

public class SetResponseType {
    public static void main(String[] args) {
        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("<REDIRECT_URI>")
                .responseType("code")
                .build();
        System.out.println(config.getResponseType()); // code
    }
}

scope

scope sets the permissions that the app asks for, as one string with a space between scopes.

NameTypeDescription
scope (required)String

Scopes separated by spaces. Unset, the URL carries no scope.

Default: Not applicable

Returns: OAuthConfigBuilder. The same builder, for chaining.

Validation

  • There is no client-side validation.
  • scope(null) clears the scopes.

Behavior

  • When the value is not blank, authorize adds it to the authorization URL as scope.
  • scopes sets the same value from a list. The last call of either method wins.

Example

Basic usage: ask for two scopes

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.OAuthConfig;

public class SetScope {
    public static void main(String[] args) {
        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("<REDIRECT_URI>")
                .scope("user:read cm.stacks.management:read")
                .build();

        Contentstack client = new Contentstack.Builder()
                .setOAuthConfig(config)
                .build();
        System.out.println(client.getOAuthHandler().authorize());
    }
}

scopes

scopes sets the permissions that the app asks for, from a list or from separate strings.

NameTypeDescription
scopes (required)List<String>

Scopes to ask for. Unset, the URL carries no scope.

Default: Not applicable

Returns: OAuthConfigBuilder. The same builder, for chaining.

Overloads

  • scopes(List<String> scopes)
  • scopes(String... scopes)

Validation

  • There is no client-side validation.
  • null, an empty list, or no arguments clears the scopes.
  • scopes(null) does not compile, because both overloads accept null. Call scope(null) instead.

Behavior

  • scopes joins the values with a space and stores the result as the scope string. scopes("user:read", "cm.stacks.management:read") stores user:read cm.stacks.management:read.
  • scope sets the same value as one string. The last call of either method wins.

Example

Basic usage: pass separate strings

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.OAuthConfig;

public class SetScopesVarargs {
    public static void main(String[] args) {
        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("<REDIRECT_URI>")
                .scopes("user:read", "cm.stacks.management:read")
                .build();

        Contentstack client = new Contentstack.Builder()
                .setOAuthConfig(config)
                .build();
        System.out.println(config.getScope()); // user:read cm.stacks.management:read
    }
}

Pass a list: build the scopes at runtime

import com.contentstack.cms.models.OAuthConfig;
import java.util.ArrayList;
import java.util.List;

public class SetScopesList {
    public static void main(String[] args) {
        List<String> requested = new ArrayList<String>();
        requested.add("user:read");
        requested.add("cm.stacks.management:read");

        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("<REDIRECT_URI>")
                .scopes(requested)
                .build();
        System.out.println(config.getScope());
    }
}

tokenCallback

tokenCallback sets the callback that the SDK calls each time it stores new tokens, so you can save them.

NameTypeDescription
tokenCallback (required)TokenCallback

Receives the tokens after each exchange or refresh.

Default: Not applicable

Returns: OAuthConfigBuilder. The same builder, for chaining.

Validation

  • There is no client-side validation.
  • An exception that your callback throws fails the token request. The future of that request completes with the exception.

Behavior

  • TokenCallback is an interface in com.contentstack.cms.oauth with two methods, void onTokensUpdated(OAuthTokens tokens) and void onTokensCleared().
  • The SDK calls onTokensUpdated after every successful code exchange and refresh, including a refresh that the SDK starts before a request.
  • The SDK calls it on the background thread that ran the token request.
  • In 1.16.0, no SDK method calls onTokensCleared, including logout.
  • With setOAuthConfig, the callback from the setTokenCallback method of Contentstack.Builder does not apply. Set it here instead.

Example

Basic usage: save new tokens

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.OAuthConfig;
import com.contentstack.cms.models.OAuthTokens;
import com.contentstack.cms.oauth.TokenCallback;

public class SaveTokensCallback {
    public static void main(String[] args) {
        TokenCallback callback = new TokenCallback() {
            @Override
            public void onTokensUpdated(OAuthTokens tokens) {
                // Save the tokens in your secret store
                System.out.println("New tokens, expiring at " + tokens.getExpiresAt());
            }

            @Override
            public void onTokensCleared() {
                System.out.println("Tokens cleared");
            }
        };

        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("<REDIRECT_URI>")
                .tokenCallback(callback)
                .build();
        Contentstack client = new Contentstack.Builder()
                .setOAuthConfig(config)
                .build();
        System.out.println(client.getOAuthHandler().authorize());
    }
}

tokenEndpoint

tokenEndpoint sets the full URL of the token endpoint, in place of the URL the SDK derives from the host.

NameTypeDescription
tokenEndpoint (required)String

HTTPS URL of the token endpoint. Unset, the SDK derives it from the host.

Default: Not applicable

Returns: OAuthConfigBuilder. The same builder, for chaining.

Validation

  • There is no client-side validation at this call.
  • A value that is not a valid URL or does not use https makes each token request fail. The future of exchangeCodeForToken or refreshAccessToken completes with an exception whose cause chain holds an IllegalArgumentException.

Behavior

  • The SDK sends the authorization code exchange and every refresh request to this URL.

Example

Basic usage: set the token endpoint of the EU region

import com.contentstack.cms.models.OAuthConfig;

public class SetTokenEndpoint {
    public static void main(String[] args) {
        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("<REDIRECT_URI>")
                .tokenEndpoint("https://eu-developerhub-api.contentstack.com/token")
                .build();
        System.out.println(config.getTokenEndpoint());
    }
}

validate

validate checks that the configuration holds the values a sign-in needs.

Returns: void. This method returns nothing.

Validation

  • Throws IllegalArgumentException if appId, clientId or redirectUri is null or blank, because the authorization URL and the token requests need all three.
  • Throws IllegalArgumentException if java.net.URL cannot parse redirectUri. A custom scheme such as myapp://callback fails.
  • validate does not check the client secret, the host or the endpoint overrides.

Behavior

  • The SDK calls validate when you build a client with this configuration, and when you call the setOAuth method of Contentstack.Builder.
  • Call it yourself to check a configuration before you build the client.

Example

Error handling: check a configuration before use

import com.contentstack.cms.models.OAuthConfig;

public class ValidateOAuthConfig {
    public static void main(String[] args) {
        OAuthConfig config = OAuthConfig.builder()
                .appId("<APP_ID>")
                .clientId("<CLIENT_ID>")
                .redirectUri("myapp://callback")
                .build();
        try {
            config.validate();
        } catch (IllegalArgumentException e) {
            // Thrown here because java.net.URL does not know the myapp scheme
            System.out.println("Invalid OAuth configuration: " + e.getMessage());
        }
    }
}