Package com.okta.sdk.impl.client

Class DefaultClientBuilder

java.lang.Object

com.okta.sdk.impl.client.DefaultClientBuilder

All Implemented Interfaces:

ClientBuilder

public class DefaultClientBuilder
extends Object
implements ClientBuilder

The default ClientBuilder implementation. This looks for configuration files in the following locations and order of precedence (last one wins).

• classpath:com/okta/sdk/config/okta.properties
• classpath:com/okta/sdk/config/okta.yaml
• classpath:okta.properties
• classpath:okta.yaml
• ~/.okta/okta.yaml
• Environment Variables (with dot notation converted to uppercase + underscores)
• System Properties
• Programmatically

Please be aware that, in general, loading secrets (such as api-keys or PEM-content) from environment variables or system properties can lead to those secrets being leaked.

Since:

0.5.0

Field Summary

Fields inherited from interface com.okta.sdk.client.ClientBuilder

DEFAULT_CLIENT_API_TOKEN_PROPERTY_NAME, DEFAULT_CLIENT_AUTHENTICATION_SCHEME_PROPERTY_NAME, DEFAULT_CLIENT_AUTHORIZATION_MODE_PROPERTY_NAME, DEFAULT_CLIENT_CACHE_CACHES_PROPERTY_NAME, DEFAULT_CLIENT_CACHE_ENABLED_PROPERTY_NAME, DEFAULT_CLIENT_CACHE_TTI_PROPERTY_NAME, DEFAULT_CLIENT_CACHE_TTL_PROPERTY_NAME, DEFAULT_CLIENT_CONNECTION_TIMEOUT_PROPERTY_NAME, DEFAULT_CLIENT_ID_PROPERTY_NAME, DEFAULT_CLIENT_KID_PROPERTY_NAME, DEFAULT_CLIENT_OAUTH2_ACCESS_TOKEN_PROPERTY_NAME, DEFAULT_CLIENT_ORG_URL_PROPERTY_NAME, DEFAULT_CLIENT_PRIVATE_KEY_PROPERTY_NAME, DEFAULT_CLIENT_PROXY_HOST_PROPERTY_NAME, DEFAULT_CLIENT_PROXY_PASSWORD_PROPERTY_NAME, DEFAULT_CLIENT_PROXY_PORT_PROPERTY_NAME, DEFAULT_CLIENT_PROXY_USERNAME_PROPERTY_NAME, DEFAULT_CLIENT_REQUEST_TIMEOUT_PROPERTY_NAME, DEFAULT_CLIENT_RETRY_MAX_ATTEMPTS_PROPERTY_NAME, DEFAULT_CLIENT_SCOPES_PROPERTY_NAME, DEFAULT_CLIENT_TESTING_DISABLE_HTTPS_CHECK_PROPERTY_NAME

Constructor Summary

Constructors

Constructor	Description
DefaultClientBuilder()

Method Summary

Modifier and Type	Method	Description
ApiClient	build()	Constructs a new ApiClient instance based on the ClientBuilder's current configuration state.
protected org.apache.hc.client5.http.impl.classic.HttpClientBuilder	createHttpClientBuilder(ClientConfiguration clientConfig)	Override to customize the client, allowing one to add additional interceptors.
protected org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManagerBuilder	createHttpClientConnectionManagerBuilder(ClientConfiguration clientConfig)	Override to customize the connection manager, allowing the increase of max connections
protected org.apache.hc.client5.http.config.RequestConfig.Builder	createHttpRequestConfigBuilder(ClientConfiguration clientConfig)	Override to customize the request config
ClientConfiguration	getClientConfiguration()
ClientBuilder	setAuthorizationMode(AuthorizationMode authorizationMode)	Overrides the default (very secure) Okta SSWS Digest Authentication Scheme used to authenticate every request sent to the Okta API server.
ClientBuilder	setCacheManager(CacheManager cacheManager)	Sets the CacheManager that should be used to cache Okta REST resources, reducing round-trips to the Okta API server and enhancing application performance.
ClientBuilder	setClientCredentials(ClientCredentials clientCredentials)	Allows specifying an ApiKey instance directly instead of relying on the default location + override/fallback behavior defined in the documentation above.
ClientBuilder	setClientId(String clientId)	Allows specifying the client ID instead of relying on the default location + override/fallback behavior defined in the documentation above.
ClientBuilder	setConnectionTimeout(int timeout)	Sets both the timeout until a connection is established and the socket timeout (i.e.
ClientBuilder	setCustomJwtSigner(UnaryOperator<byte[]> jwtSigner, String algorithm)	Allows specifying a custom signer for signing JWT token, instead of using a locally stored private key.
ClientBuilder	setKid(String kid)	Allows specifying the Key ID (kid) instead of relying on the YAML config.
ClientBuilder	setOAuth2AccessToken(String oAuth2AccessToken)	Allows specifying the user obtained OAuth2 access token to be used by the SDK.
ClientBuilder	setOrgUrl(String baseUrl)	Sets the base URL of the Okta REST API to use.
ClientBuilder	setPrivateKey(InputStream privateKeyStream)	Allows specifying the private key (PEM file) path (for private key jwt authentication) directly instead of relying on the default location + override/fallback behavior defined in the documentation above.
ClientBuilder	setPrivateKey(String privateKey)	Allows specifying the private key (PEM file) path (for private key jwt authentication) directly instead of relying on the default location + override/fallback behavior defined in the documentation above.
ClientBuilder	setPrivateKey(Path privateKeyPath)	Allows specifying the private key (PEM file) path (for private key jwt authentication) directly instead of relying on the default location + override/fallback behavior defined in the documentation above.
ClientBuilder	setPrivateKey(PrivateKey privateKey)	Allows specifying the private key (PEM file) path (for private key jwt authentication) directly instead of relying on the default location + override/fallback behavior defined in the documentation above.
ClientBuilder	setProxy(com.okta.commons.http.config.Proxy proxy)	Sets the HTTP proxy to be used when communicating with the Okta API server.
ClientBuilder	setRetryMaxAttempts(int maxAttempts)	Sets the maximum number of attempts to retrying before giving up.
ClientBuilder	setRetryMaxElapsed(int maxElapsed)	Sets the maximum number of seconds to wait when retrying before giving up.
ClientBuilder	setScopes(Set<String> scopes)	Allows specifying a list of scopes directly instead of relying on the default location + override/fallback behavior defined in the documentation above.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

DefaultClientBuilder

public DefaultClientBuilder()

Method Details

setProxy

public ClientBuilder setProxy(com.okta.commons.http.config.Proxy proxy)

Description copied from interface: ClientBuilder

Sets the HTTP proxy to be used when communicating with the Okta API server. For example:

 Proxy proxy = new Proxy("whatever.domain.com", 443);
 Client client = Clients.builder().setProxy(proxy).build();
 

Specified by:

setProxy in interface ClientBuilder

Parameters:

proxy - the Proxy you need to use.

Returns:

the ClientBuilder instance for method chaining.

setCacheManager

public ClientBuilder setCacheManager(CacheManager cacheManager)

Description copied from interface: ClientBuilder

Sets the CacheManager that should be used to cache Okta REST resources, reducing round-trips to the Okta API server and enhancing application performance. Single JVM Applications

If your application runs on a single JVM-based applications, the CacheManagerBuilder should be sufficient for your needs. You create a CacheManagerBuilder by using the Caches utility class, for example:

 import static com.okta.sdk.cache.Caches.*;

 ...

 ApiClient client = Clients.builder()...
     .setCacheManager(
         newCacheManager()
         .withDefaultTimeToLive(1, TimeUnit.DAYS) //general default
         .withDefaultTimeToIdle(2, TimeUnit.HOURS) //general default
         .withCache(forResource(User.class) //User-specific cache settings
             .withTimeToLive(1, TimeUnit.HOURS)
             .withTimeToIdle(30, TimeUnit.MINUTES))
         .withCache(forResource(Group.class) //Group-specific cache settings
             .withTimeToLive(2, TimeUnit.HOURS))
         .build() //build the CacheManager
     )
     .build(); //build the Client
 

The above TTL and TTI times are just examples showing API usage - the times themselves are not recommendations. Choose TTL and TTI times based on your application requirements.

Multi-JVM / Clustered Applications

The default CacheManager instances returned by the CacheManagerBuilder might not be sufficient for a multi-instance application that runs on multiple JVMs and/or hosts/servers, as there could be cache-coherency problems across the JVMs. See the CacheManagerBuilder JavaDoc for additional information.

In these multi-JVM environments, you will likely want to create a simple CacheManager implementation that wraps your distributed Caching API/product of choice and then plug that implementation in to the Okta SDK via this method. Hazelcast is one known cluster-safe caching product, and the Okta SDK has out-of-the-box support for this as an extension module. See the top-level class JavaDoc for a Hazelcast configuration example.

Specified by:

setCacheManager in interface ClientBuilder

Parameters:

cacheManager - the CacheManager that should be used to cache Okta REST resources, reducing round-trips to the Okta API server and enhancing application performance.

Returns:

the ClientBuilder instance for method chaining

setConnectionTimeout

public ClientBuilder setConnectionTimeout(int timeout)

Description copied from interface: ClientBuilder

Sets both the timeout until a connection is established and the socket timeout (i.e. a maximum period of inactivity between two consecutive data packets). A timeout value of zero is interpreted as an infinite timeout.

Specified by:

setConnectionTimeout in interface ClientBuilder

Parameters:

timeout - connection and socket timeout in seconds

Returns:

the ClientBuilder instance for method chaining

setClientCredentials

public ClientBuilder setClientCredentials(ClientCredentials clientCredentials)

Description copied from interface: ClientBuilder

Allows specifying an ApiKey instance directly instead of relying on the default location + override/fallback behavior defined in the documentation above. Currently, you should use a com.okta.sdk.impl.api.TokenClientCredentials (if you are NOT using an okta.yaml file)

Specified by:

setClientCredentials in interface ClientBuilder

Parameters:

clientCredentials - the token to use to authenticate requests to the Okta API server.

Returns:

the ClientBuilder instance for method chaining.

setRetryMaxElapsed

public ClientBuilder setRetryMaxElapsed(int maxElapsed)

Description copied from interface: ClientBuilder

Sets the maximum number of seconds to wait when retrying before giving up.

Specified by:

setRetryMaxElapsed in interface ClientBuilder

Parameters:

maxElapsed - retry max elapsed duration in seconds

Returns:

the ClientBuilder instance for method chaining

setRetryMaxAttempts

public ClientBuilder setRetryMaxAttempts(int maxAttempts)

Description copied from interface: ClientBuilder

Sets the maximum number of attempts to retrying before giving up.

Specified by:

setRetryMaxAttempts in interface ClientBuilder

Parameters:

maxAttempts - retry max attempts

Returns:

the ClientBuilder instance for method chaining

build

public ApiClient build()

Description copied from interface: ClientBuilder

Constructs a new ApiClient instance based on the ClientBuilder's current configuration state.

Specified by:

build in interface ClientBuilder

Returns:

a new ApiClient instance based on the ClientBuilder's current configuration state.

createHttpClientBuilder

protected org.apache.hc.client5.http.impl.classic.HttpClientBuilder createHttpClientBuilder(ClientConfiguration clientConfig)

Override to customize the client, allowing one to add additional interceptors.

Parameters:

clientConfig - the current ClientConfiguration

Returns:

an HttpClientBuilder initialized with default configuration

createHttpRequestConfigBuilder

protected org.apache.hc.client5.http.config.RequestConfig.Builder createHttpRequestConfigBuilder(ClientConfiguration clientConfig)

Override to customize the request config

Parameters:

clientConfig - the current clientConfig

Returns:

a RequestConfig.Builder initialized with default configuration

createHttpClientConnectionManagerBuilder

protected org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManagerBuilder createHttpClientConnectionManagerBuilder(ClientConfiguration clientConfig)

Override to customize the connection manager, allowing the increase of max connections

Parameters:

clientConfig - the current clientConfig

Returns:

a PoolingHttpClientConnectionManagerBuilder initialized with default configuration

setOrgUrl

public ClientBuilder setOrgUrl(String baseUrl)

Description copied from interface: ClientBuilder

Sets the base URL of the Okta REST API to use. If unspecified, this value defaults to https://api.okta.com/v1 - the most common use case for Okta's public SaaS cloud.

Customers using Okta's Enterprise HA cloud might need to configure this to be https://enterprise.okta.io/v1 for example.

Specified by:

setOrgUrl in interface ClientBuilder

Parameters:

baseUrl - the base URL of the Okta REST API to use.

Returns:

the ClientBuilder instance for method chaining

setAuthorizationMode

public ClientBuilder setAuthorizationMode(AuthorizationMode authorizationMode)

Description copied from interface: ClientBuilder

Overrides the default (very secure) Okta SSWS Digest Authentication Scheme used to authenticate every request sent to the Okta API server.

 Client client = Clients.builder()...
    // setApiKey, etc...
    .setAuthorizationMode(AuthorizationMode.SSWS) //set the SSWS authentication mode
    .build(); //build the Client
 

Specified by:

setAuthorizationMode in interface ClientBuilder

Parameters:

authorizationMode - mode of authorization for requests to the Okta API server.

Returns:

the ClientBuilder instance for method chaining.

setScopes

public ClientBuilder setScopes(Set<String> scopes)

Description copied from interface: ClientBuilder

Allows specifying a list of scopes directly instead of relying on the default location + override/fallback behavior defined in the documentation above.

Specified by:

setScopes in interface ClientBuilder

Parameters:

scopes - set of scopes for which the client requests access.

Returns:

the ClientBuilder instance for method chaining.

setPrivateKey

public ClientBuilder setPrivateKey(String privateKey)

Description copied from interface: ClientBuilder

Allows specifying the private key (PEM file) path (for private key jwt authentication) directly instead of relying on the default location + override/fallback behavior defined in the documentation above.

Specified by:

setPrivateKey in interface ClientBuilder

Parameters:

privateKey - either the fully qualified string path to the private key PEM file (or) the full PEM payload content.

Returns:

the ClientBuilder instance for method chaining.

setPrivateKey

public ClientBuilder setPrivateKey(Path privateKeyPath)

Description copied from interface: ClientBuilder

Allows specifying the private key (PEM file) path (for private key jwt authentication) directly instead of relying on the default location + override/fallback behavior defined in the documentation above.

Specified by:

setPrivateKey in interface ClientBuilder

Parameters:

privateKeyPath - representing the path to private key PEM file.

Returns:

the ClientBuilder instance for method chaining.

setPrivateKey

public ClientBuilder setPrivateKey(InputStream privateKeyStream)

Description copied from interface: ClientBuilder

Allows specifying the private key (PEM file) path (for private key jwt authentication) directly instead of relying on the default location + override/fallback behavior defined in the documentation above.

Specified by:

setPrivateKey in interface ClientBuilder

Parameters:

privateKeyStream - representing an InputStream with private key PEM file content.

Returns:

the ClientBuilder instance for method chaining.

setPrivateKey

public ClientBuilder setPrivateKey(PrivateKey privateKey)

Description copied from interface: ClientBuilder

Allows specifying the private key (PEM file) path (for private key jwt authentication) directly instead of relying on the default location + override/fallback behavior defined in the documentation above.

Specified by:

setPrivateKey in interface ClientBuilder

Parameters:

privateKey - the PrivateKey instance.

Returns:

the ClientBuilder instance for method chaining.

setCustomJwtSigner

public ClientBuilder setCustomJwtSigner(UnaryOperator<byte[]> jwtSigner,
 String algorithm)

Description copied from interface: ClientBuilder

Allows specifying a custom signer for signing JWT token, instead of using a locally stored private key.

Specified by:

setCustomJwtSigner in interface ClientBuilder

Parameters:

jwtSigner - the JWT signer instance.

Returns:

the ClientBuilder instance for method chaining.

setClientId

public ClientBuilder setClientId(String clientId)

Description copied from interface: ClientBuilder

Allows specifying the client ID instead of relying on the default location + override/fallback behavior defined in the documentation above.

Specified by:

setClientId in interface ClientBuilder

Parameters:

clientId - string representing the client ID.

Returns:

the ClientBuilder instance for method chaining.

setOAuth2AccessToken

public ClientBuilder setOAuth2AccessToken(String oAuth2AccessToken)

Description copied from interface: ClientBuilder

Allows specifying the user obtained OAuth2 access token to be used by the SDK. The SDK will NOT obtain access token automatically (using the supplied private key) when this is set.

Specified by:

setOAuth2AccessToken in interface ClientBuilder

Parameters:

oAuth2AccessToken - the token string.

Returns:

the ClientBuilder instance for method chaining.

setKid

public ClientBuilder setKid(String kid)

Description copied from interface: ClientBuilder

Allows specifying the Key ID (kid) instead of relying on the YAML config.

Specified by:

setKid in interface ClientBuilder

Parameters:

kid - string representing the Key ID.

Returns:

the ClientBuilder instance for method chaining.

getClientConfiguration

public ClientConfiguration getClientConfiguration()