Package com.okta.sdk.client

Interface ClientBuilder

All Known Implementing Classes:
DefaultClientBuilder
public interface ClientBuilder

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

Since:
0.5.0

  • Field Details

    • DEFAULT_CLIENT_API_TOKEN_PROPERTY_NAME

      static final String DEFAULT_CLIENT_API_TOKEN_PROPERTY_NAME
      See Also:

    • DEFAULT_CLIENT_CACHE_ENABLED_PROPERTY_NAME

      static final String DEFAULT_CLIENT_CACHE_ENABLED_PROPERTY_NAME
      See Also:

    • DEFAULT_CLIENT_CACHE_TTL_PROPERTY_NAME

      static final String DEFAULT_CLIENT_CACHE_TTL_PROPERTY_NAME
      See Also:

    • DEFAULT_CLIENT_CACHE_TTI_PROPERTY_NAME

      static final String DEFAULT_CLIENT_CACHE_TTI_PROPERTY_NAME
      See Also:

    • DEFAULT_CLIENT_CACHE_CACHES_PROPERTY_NAME

      static final String DEFAULT_CLIENT_CACHE_CACHES_PROPERTY_NAME
      See Also:

    • DEFAULT_CLIENT_ORG_URL_PROPERTY_NAME

      static final String DEFAULT_CLIENT_ORG_URL_PROPERTY_NAME
      See Also:

    • DEFAULT_CLIENT_CONNECTION_TIMEOUT_PROPERTY_NAME

      static final String DEFAULT_CLIENT_CONNECTION_TIMEOUT_PROPERTY_NAME
      See Also:

    • DEFAULT_CLIENT_AUTHENTICATION_SCHEME_PROPERTY_NAME

      static final String DEFAULT_CLIENT_AUTHENTICATION_SCHEME_PROPERTY_NAME
      See Also:

    • DEFAULT_CLIENT_PROXY_PORT_PROPERTY_NAME

      static final String DEFAULT_CLIENT_PROXY_PORT_PROPERTY_NAME
      See Also:

    • DEFAULT_CLIENT_PROXY_HOST_PROPERTY_NAME

      static final String DEFAULT_CLIENT_PROXY_HOST_PROPERTY_NAME
      See Also:

    • DEFAULT_CLIENT_PROXY_USERNAME_PROPERTY_NAME

      static final String DEFAULT_CLIENT_PROXY_USERNAME_PROPERTY_NAME
      See Also:

    • DEFAULT_CLIENT_PROXY_PASSWORD_PROPERTY_NAME

      static final String DEFAULT_CLIENT_PROXY_PASSWORD_PROPERTY_NAME
      See Also:

    • DEFAULT_CLIENT_AUTHORIZATION_MODE_PROPERTY_NAME

      static final String DEFAULT_CLIENT_AUTHORIZATION_MODE_PROPERTY_NAME
      See Also:

    • DEFAULT_CLIENT_ID_PROPERTY_NAME

      static final String DEFAULT_CLIENT_ID_PROPERTY_NAME
      See Also:

    • DEFAULT_CLIENT_SCOPES_PROPERTY_NAME

      static final String DEFAULT_CLIENT_SCOPES_PROPERTY_NAME
      See Also:

    • DEFAULT_CLIENT_PRIVATE_KEY_PROPERTY_NAME

      static final String DEFAULT_CLIENT_PRIVATE_KEY_PROPERTY_NAME
      See Also:

    • DEFAULT_CLIENT_OAUTH2_ACCESS_TOKEN_PROPERTY_NAME

      static final String DEFAULT_CLIENT_OAUTH2_ACCESS_TOKEN_PROPERTY_NAME
      See Also:

    • DEFAULT_CLIENT_KID_PROPERTY_NAME

      static final String DEFAULT_CLIENT_KID_PROPERTY_NAME
      See Also:

    • DEFAULT_CLIENT_REQUEST_TIMEOUT_PROPERTY_NAME

      static final String DEFAULT_CLIENT_REQUEST_TIMEOUT_PROPERTY_NAME
      See Also:

    • DEFAULT_CLIENT_RETRY_MAX_ATTEMPTS_PROPERTY_NAME

      static final String DEFAULT_CLIENT_RETRY_MAX_ATTEMPTS_PROPERTY_NAME
      See Also:

    • DEFAULT_CLIENT_TESTING_DISABLE_HTTPS_CHECK_PROPERTY_NAME

      static final String DEFAULT_CLIENT_TESTING_DISABLE_HTTPS_CHECK_PROPERTY_NAME
      See Also:

  • Method Details

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

 ...

 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.

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

    • setCustomJwtSigner

      ClientBuilder setCustomJwtSigner(UnaryOperator<byte[]> jwtSigner, String algorithm)
      Allows specifying a custom signer for signing JWT token, instead of using a locally stored private key.
      Parameters:
      jwtSigner - the JWT signer instance.
      Returns:
      the ClientBuilder instance for method chaining.
      Since:
      16.x.x

    • setOAuth2AccessToken

      ClientBuilder setOAuth2AccessToken(String oAuth2AccessToken)
      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.
      Parameters:
      oAuth2AccessToken - the token string.
      Returns:
      the ClientBuilder instance for method chaining.
      Since:
      10.2.x

    • setClientId

      ClientBuilder setClientId(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(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(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

    • build

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