Package com.okta.sdk.client

Interface ClientBuilder

  • public interface ClientBuilder
    A Builder design pattern used to construct Client instances.

    The ClientBuilder is used to construct Client instances with Okta credentials, Proxy and Cache configuration. Understanding caching is extremely important when creating a Client instance, so please ensure you read the Caching section below.

    Usage

    The simplest usage is to just call the build() method, for example:

     Client client = Clients.builder().build();

    This will:

    • Automatically enable a simple in-memory CacheManager for enhanced performance (but please read the Caching section below for effects/warnings).
    • Automatically attempt to find your API credentials values in a number of default/conventional locations and then use the discovered values. Without any other configuration, the following locations will be each be checked, in order:
    1. The environment variable OKTA_CLIENT_TOKEN. If either of these values are present, they override any previously discovered value.
    2. The system properties okta.client.token. If this value is present, it will override any previously discovered values.

    SECURITY NOTICE: While the okta.client.token system property or environment variable OKTA_CLIENT_TOKEN may be used to represent your API Key Secret as mentioned above, this is not recommended: process listings on a machine will expose process arguments (like system properties) or environment variables, thus exposing the secret value to anyone that can read process listings. As always, secret values should never be exposed to anyone other than the person that owns the API Key.

    While an API Key ID may be configured anywhere (and be visible by anyone), it is recommended to use a private read-only file to represent API Key secrets. Never commit secrets to source code or version control.

    Explicit API Key Configuration

    The above default API Key searching heuristics may not be suitable to your needs. In that case, you will likely need to explicitly configure your API Key. For example:

     ClientCredentials clientCredentials = new TokenClientCredentials("apiToken");

 Client client = Clients.builder().setClientCredentials(clientCredentials).build();

    Caching

    By default, a simple production-grade in-memory CacheManager will be enabled when the Client instance is created. This CacheManager implementation has the following characteristics:

    • It assumes a default time-to-live and time-to-idle of 1 hour for all cache entries.
    • It auto-sizes itself based on your application's memory usage. It will not cause OutOfMemoryExceptions. (It does this by retaining only 100 strong references to cached objects. Additional cached objects are weakly referenced, ensuring the garbage collector can evict weakly referenced cache entries if it needs more memory for your application.).

    but, please note:

    The default cache manager is not suitable for an application deployed across multiple JVMs.

    This is because the default implementation is 100% in-memory (in-process) in the current JVM. If more than one JVM is deployed with the same application codebase - for example, a web application deployed on multiple identical hosts for scaling or high availability - each JVM would have it's own in-memory cache. Multiple disconnected caches for the same data will cause cache coherency problems and likely cause errors in your application!

    As a result, if your application that uses a Okta Client instance is deployed across multiple JVMs, you SHOULD ensure that the Client is configured with a CacheManager implementation that uses coherent and clustered/distributed memory.

    Custom CacheManager

    If you want to specify a custom CacheManager implementation:

     CacheManager cacheManager = new MyCacheManagerImplementation();
 Client client = Clients.builder().setCacheManager(cacheManager).build();

    Application deployed on a single JVM

    If your application is deployed on a single JVM and you still want to use the default CacheManager implementation, but the default cache configuration does not meet your needs, you can specify a different configuration. For example:

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

 ...

 Caches.newCacheManager()
     .withDefaultTimeToLive(300, TimeUnit.SECONDS) // default
     .withDefaultTimeToIdle(300, TimeUnit.SECONDS) //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))

     //... etc ...

     .build(); //build the CacheManager

    See the Caches utility class and the CacheManagerBuilder docs for more information.

    Application deployed across multiple JVMs

    If your application is deployed across multiple JVMs (for example a web app deployed on multiple web nodes for scale and/or high availability), you will likely need to specify a custom CacheManager implementation that is based on network distributed/coherent memory. For example, an implementation might delegate to a Hazelcast or Redis cluster. For example, if using the out-of-the-box Hazelcast plugin:

     import com.okta.sdk.hazelcast.HazelcastCacheManager;
 // ... etc ...

 //Get a HazelcastInstance from your app/config.  This can be a HazelcastClient instance too:
 HazelcastInstance hazelcastInstance = getHazelcastInstanceOrHazelcastClient();

 CacheManager cacheManager = new HazelcastCacheManager(hazelcastInstance);
 Client client = Clients.builder().setCacheManager(cacheManager).build();

    NOTE: it should be noted that Memcache DOES NOT guarantee cache coherency. It is strongly recommended that you do not use Memcache as your clustered caching solution (memcache is fine for caching files, etc, but not data that is expected to be coherent across multiple cluster nodes).

    Disable Caching

    While production applications will usually enable a working CacheManager as described above, you might wish to disable caching entirely when testing or debugging to remove 'moving parts' for better clarity into request/response behavior. You can do this by configuring a disabled CacheManager instance. For example:

     Client client = Clients.builder().setCacheManager(
     Caches.newDisabledCacheManager()
 ).build();

    Single Instance

    Finally, it should be noted that, after building a client instance, that same instance should be used everywhere in your application. Creating multiple client instances in a single application could have negative side effects:

    As mentioned above, a client has a CacheManager reference. If your application uses multiple client instances, each client's referenced CacheManager would likely become out of sync with the others, making your cache incoherent. This will likely result in exposing stale data to your application and could data errors.

    If you must have multiple Client instances in your application, you should ensure that each client references the same exact CacheManager instance to guarantee cache coherency.

    Since:
    0.5.0

    • Field Detail

      • DEFAULT_CLIENT_API_TOKEN_PROPERTY_NAME

        static final java.lang.String DEFAULT_CLIENT_API_TOKEN_PROPERTY_NAME
        See Also:
        Constant Field Values

      • DEFAULT_CLIENT_CACHE_ENABLED_PROPERTY_NAME

        static final java.lang.String DEFAULT_CLIENT_CACHE_ENABLED_PROPERTY_NAME
        See Also:
        Constant Field Values

      • DEFAULT_CLIENT_CACHE_TTL_PROPERTY_NAME

        static final java.lang.String DEFAULT_CLIENT_CACHE_TTL_PROPERTY_NAME
        See Also:
        Constant Field Values

      • DEFAULT_CLIENT_CACHE_TTI_PROPERTY_NAME

        static final java.lang.String DEFAULT_CLIENT_CACHE_TTI_PROPERTY_NAME
        See Also:
        Constant Field Values

      • DEFAULT_CLIENT_CACHE_CACHES_PROPERTY_NAME

        static final java.lang.String DEFAULT_CLIENT_CACHE_CACHES_PROPERTY_NAME
        See Also:
        Constant Field Values

      • DEFAULT_CLIENT_ORG_URL_PROPERTY_NAME

        static final java.lang.String DEFAULT_CLIENT_ORG_URL_PROPERTY_NAME
        See Also:
        Constant Field Values

      • DEFAULT_CLIENT_CONNECTION_TIMEOUT_PROPERTY_NAME

        static final java.lang.String DEFAULT_CLIENT_CONNECTION_TIMEOUT_PROPERTY_NAME
        See Also:
        Constant Field Values

      • DEFAULT_CLIENT_AUTHENTICATION_SCHEME_PROPERTY_NAME

        static final java.lang.String DEFAULT_CLIENT_AUTHENTICATION_SCHEME_PROPERTY_NAME
        See Also:
        Constant Field Values

      • DEFAULT_CLIENT_PROXY_PORT_PROPERTY_NAME

        static final java.lang.String DEFAULT_CLIENT_PROXY_PORT_PROPERTY_NAME
        See Also:
        Constant Field Values

      • DEFAULT_CLIENT_PROXY_HOST_PROPERTY_NAME

        static final java.lang.String DEFAULT_CLIENT_PROXY_HOST_PROPERTY_NAME
        See Also:
        Constant Field Values

      • DEFAULT_CLIENT_PROXY_USERNAME_PROPERTY_NAME

        static final java.lang.String DEFAULT_CLIENT_PROXY_USERNAME_PROPERTY_NAME
        See Also:
        Constant Field Values

      • DEFAULT_CLIENT_PROXY_PASSWORD_PROPERTY_NAME

        static final java.lang.String DEFAULT_CLIENT_PROXY_PASSWORD_PROPERTY_NAME
        See Also:
        Constant Field Values

      • DEFAULT_CLIENT_AUTHORIZATION_MODE_PROPERTY_NAME

        static final java.lang.String DEFAULT_CLIENT_AUTHORIZATION_MODE_PROPERTY_NAME
        See Also:
        Constant Field Values

      • DEFAULT_CLIENT_ID_PROPERTY_NAME

        static final java.lang.String DEFAULT_CLIENT_ID_PROPERTY_NAME
        See Also:
        Constant Field Values

      • DEFAULT_CLIENT_SCOPES_PROPERTY_NAME

        static final java.lang.String DEFAULT_CLIENT_SCOPES_PROPERTY_NAME
        See Also:
        Constant Field Values

      • DEFAULT_CLIENT_PRIVATE_KEY_PROPERTY_NAME

        static final java.lang.String DEFAULT_CLIENT_PRIVATE_KEY_PROPERTY_NAME
        See Also:
        Constant Field Values

      • DEFAULT_CLIENT_KID_PROPERTY_NAME

        static final java.lang.String DEFAULT_CLIENT_KID_PROPERTY_NAME
        See Also:
        Constant Field Values

      • DEFAULT_CLIENT_REQUEST_TIMEOUT_PROPERTY_NAME

        static final java.lang.String DEFAULT_CLIENT_REQUEST_TIMEOUT_PROPERTY_NAME
        See Also:
        Constant Field Values

      • DEFAULT_CLIENT_RETRY_MAX_ATTEMPTS_PROPERTY_NAME

        static final java.lang.String DEFAULT_CLIENT_RETRY_MAX_ATTEMPTS_PROPERTY_NAME
        See Also:
        Constant Field Values

      • DEFAULT_CLIENT_TESTING_DISABLE_HTTPS_CHECK_PROPERTY_NAME

        static final java.lang.String DEFAULT_CLIENT_TESTING_DISABLE_HTTPS_CHECK_PROPERTY_NAME
        See Also:
        Constant Field Values

    • Method Detail

      • setClientCredentials

        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. Currently you should use a com.okta.sdk.impl.api.TokenClientCredentials (if you are NOT using an okta.yaml file)
        Parameters:
        clientCredentials - the token to use to authenticate requests to the Okta API server.
        Returns:
        the ClientBuilder instance for method chaining.

      • setProxy

        ClientBuilder setProxy​(com.okta.commons.http.config.Proxy proxy)
        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();
        Parameters:
        proxy - the Proxy you need to use.
        Returns:
        the ClientBuilder instance for method chaining.

      • setCacheManager

        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.

        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.*;

 ...

 Client 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.

        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

      • setAuthorizationMode

        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. 
         Client client = Clients.builder()...
    // setApiKey, etc...
    .setAuthorizationMode(AuthorizationMode.SSWS) //set the SSWS authentication mode
    .build(); //build the Client
        Parameters:
        authorizationMode - mode of authorization for requests to the Okta API server.
        Returns:
        the ClientBuilder instance for method chaining.
        Since:
        1.6.0

      • setScopes

        ClientBuilder setScopes​(java.util.Set<java.lang.String> scopes)
        Allows specifying a list of scopes directly instead of relying on the default location + override/fallback behavior defined in the documentation above.
        Parameters:
        scopes - set of scopes for which the client requests access.
        Returns:
        the ClientBuilder instance for method chaining.
        Since:
        1.6.0

      • setPrivateKey

        ClientBuilder setPrivateKey​(java.lang.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.
        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.
        Since:
        1.6.0

      • setPrivateKey

        ClientBuilder setPrivateKey​(java.nio.file.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.
        Parameters:
        privateKeyPath - representing the path to private key PEM file.
        Returns:
        the ClientBuilder instance for method chaining.
        Since:
        3.0.0

      • setPrivateKey

        ClientBuilder setPrivateKey​(java.io.InputStream privateKeyInputStream)
        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.
        Parameters:
        privateKeyInputStream - representing an InputStream with private key PEM file content.
        Returns:
        the ClientBuilder instance for method chaining.
        Since:
        3.0.0

      • setPrivateKey

        ClientBuilder setPrivateKey​(java.security.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.
        Parameters:
        privateKey - the PrivateKey instance.
        Returns:
        the ClientBuilder instance for method chaining.
        Since:
        3.0.0

      • setClientId

        ClientBuilder setClientId​(java.lang.String clientId)
        Allows specifying the client ID instead of relying on the default location + override/fallback behavior defined in the documentation above.
        Parameters:
        clientId - string representing the client ID.
        Returns:
        the ClientBuilder instance for method chaining.
        Since:
        1.6.0

      • setKid

        ClientBuilder setKid​(java.lang.String kid)
        Allows specifying the Key ID (kid) instead of relying on the YAML config.
        Parameters:
        kid - string representing the Key ID.
        Returns:
        the ClientBuilder instance for method chaining.
        Since:
        4.0.1

      • setConnectionTimeout

        ClientBuilder setConnectionTimeout​(int timeout)
        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.
        Parameters:
        timeout - connection and socket timeout in seconds
        Returns:
        the ClientBuilder instance for method chaining

      • setOrgUrl

        ClientBuilder setOrgUrl​(java.lang.String baseUrl)
        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.

        Parameters:
        baseUrl - the base URL of the Okta REST API to use.
        Returns:
        the ClientBuilder instance for method chaining

      • setRetryMaxElapsed

        ClientBuilder setRetryMaxElapsed​(int maxElapsed)
        Sets the maximum number of seconds to wait when retrying before giving up.
        Parameters:
        maxElapsed - retry max elapsed duration in seconds
        Returns:
        the ClientBuilder instance for method chaining

      • setRetryMaxAttempts

        ClientBuilder setRetryMaxAttempts​(int maxAttempts)
        Sets the maximum number of attempts to retrying before giving up.
        Parameters:
        maxAttempts - retry max attempts
        Returns:
        the ClientBuilder instance for method chaining

      • setRequestExecutorFactory

        ClientBuilder setRequestExecutorFactory​(com.okta.commons.http.RequestExecutorFactory requestExecutorFactory)
        Sets the RequestExecutorFactory, otherwise it will be loaded as a Service / SPI via the RequestExecutorFactory class.
        Parameters:
        requestExecutorFactory - that should be used to create the RequestExecutor
        Returns:
        the ClientBuilder instance for method chaining

      • build

        Client build()
        Constructs a new Client instance based on the ClientBuilder's current configuration state.
        Returns:
        a new Client instance based on the ClientBuilder's current configuration state.