OAuthConfig
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.
| Name | Type | Description |
|---|---|---|
| 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.
| Name | Type | Description |
|---|---|---|
| appId (required) | String | UID of the Contentstack app. |
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.
| Name | Type | Description |
|---|---|---|
| authEndpoint (required) | String | HTTPS URL of the authorization page. Unset, the SDK derives it from the host. |
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.
| Name | Type | Description |
|---|---|---|
| clientId (required) | String | OAuth client ID of the app. |
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).
| Name | Type | Description |
|---|---|---|
| clientSecret (required) | String | Client secret of the app. Unset, the SDK uses PKCE. |
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
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.
| Name | Type | Description |
|---|---|---|
| host (required) | String | API host of the region, such as eu-api.contentstack.com. Unset, North America. |
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:
| Host | Authorization page | Token endpoint |
|---|---|---|
| Not set, or api.contentstack.io | https://app.contentstack.com/#!/apps/{appId}/authorize | https://developerhub-api.contentstack.com/token |
| eu-api.contentstack.com | https://eu-app.contentstack.com/#!/apps/{appId}/authorize | https://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.
| Name | Type | Description |
|---|---|---|
| redirectUri (required) | String | URI that receives the authorization code. |
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.
| Name | Type | Description |
|---|---|---|
| responseType (required) | String | Value of response_type in the URL. Unset, code. |
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.
| Name | Type | Description |
|---|---|---|
| scope (required) | String | Scopes separated by spaces. Unset, the URL carries no scope. |
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.
| Name | Type | Description |
|---|---|---|
| scopes (required) | List<String> | Scopes to ask for. Unset, the URL carries no scope. |
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.
| Name | Type | Description |
|---|---|---|
| tokenCallback (required) | TokenCallback | Receives the tokens after each exchange or refresh. |
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.
| Name | Type | Description |
|---|---|---|
| tokenEndpoint (required) | String | HTTPS URL of the token endpoint. Unset, the SDK derives it from the host. |
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());
}
}
}