public interface ClientBuilder
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.
The simplest usage is to just call the build()
method, for example:
Client client =Clients
.builder().build()
;
This will:
CacheManager
for enhanced performance (but please read
the Caching section below for effects/warnings).OKTA_CLIENT_TOKEN
. If either of
these values are present, they override any previously discovered value.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.
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();
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:
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.
If you want to specify a custom CacheManager
implementation:
CacheManager cacheManager = new MyCacheManagerImplementation();
Client client = Clients
.builder().setCacheManager(cacheManager).build();
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.
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).
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();
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.
Modifier and Type | Method and Description |
---|---|
Client |
build()
Constructs a new
Client instance based on the ClientBuilder's current configuration state. |
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 |
setKid(String kid)
Allows specifying the Key ID (kid) instead of relying on the YAML config.
|
ClientBuilder |
setOrgUrl(String baseUrl)
Sets the base URL of the Okta REST API to use.
|
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 . |
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 |
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 |
setProxy(com.okta.commons.http.config.Proxy proxy)
Sets the HTTP proxy to be used when communicating with the Okta API server.
|
ClientBuilder |
setRequestExecutorFactory(com.okta.commons.http.RequestExecutorFactory requestExecutorFactory)
Sets the
RequestExecutorFactory , otherwise it will be loaded as a Service / SPI
via the RequestExecutorFactory class. |
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 . |
static final String DEFAULT_CLIENT_API_TOKEN_PROPERTY_NAME
static final String DEFAULT_CLIENT_CACHE_ENABLED_PROPERTY_NAME
static final String DEFAULT_CLIENT_CACHE_TTL_PROPERTY_NAME
static final String DEFAULT_CLIENT_CACHE_TTI_PROPERTY_NAME
static final String DEFAULT_CLIENT_CACHE_CACHES_PROPERTY_NAME
static final String DEFAULT_CLIENT_ORG_URL_PROPERTY_NAME
static final String DEFAULT_CLIENT_CONNECTION_TIMEOUT_PROPERTY_NAME
static final String DEFAULT_CLIENT_AUTHENTICATION_SCHEME_PROPERTY_NAME
static final String DEFAULT_CLIENT_PROXY_PORT_PROPERTY_NAME
static final String DEFAULT_CLIENT_PROXY_HOST_PROPERTY_NAME
static final String DEFAULT_CLIENT_PROXY_USERNAME_PROPERTY_NAME
static final String DEFAULT_CLIENT_PROXY_PASSWORD_PROPERTY_NAME
static final String DEFAULT_CLIENT_AUTHORIZATION_MODE_PROPERTY_NAME
static final String DEFAULT_CLIENT_ID_PROPERTY_NAME
static final String DEFAULT_CLIENT_SCOPES_PROPERTY_NAME
static final String DEFAULT_CLIENT_PRIVATE_KEY_PROPERTY_NAME
static final String DEFAULT_CLIENT_KID_PROPERTY_NAME
static final String DEFAULT_CLIENT_REQUEST_TIMEOUT_PROPERTY_NAME
static final String DEFAULT_CLIENT_RETRY_MAX_ATTEMPTS_PROPERTY_NAME
static final String DEFAULT_CLIENT_TESTING_DISABLE_HTTPS_CHECK_PROPERTY_NAME
ClientBuilder setClientCredentials(ClientCredentials clientCredentials)
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)clientCredentials
- the token to use to authenticate requests to the Okta API server.ClientBuilder setProxy(com.okta.commons.http.config.Proxy proxy)
Proxy proxy = new Proxy("whatever.domain.com", 443);
Client client = Clients
.builder().setProxy(proxy).build();
proxy
- the Proxy
you need to use.ClientBuilder setCacheManager(CacheManager cacheManager)
CacheManager
that should be used to cache Okta REST resources, reducing round-trips to the
Okta API server and enhancing application performance.
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.
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.
cacheManager
- the CacheManager
that should be used to cache Okta REST resources, reducing
round-trips to the Okta API server and enhancing application performance.ClientBuilder setAuthorizationMode(AuthorizationMode authorizationMode)
Client client = Clients.builder()... // setApiKey, etc... .setAuthorizationMode(AuthorizationMode.SSWS) //set the SSWS authentication mode .build(); //build the Client
authorizationMode
- mode of authorization for requests to the Okta API server.ClientBuilder setScopes(Set<String> scopes)
documentation above
.scopes
- set of scopes for which the client requests access.ClientBuilder setPrivateKey(String privateKey)
documentation above
.privateKey
- either the fully qualified string path to the private key PEM file (or)
the full PEM payload content.ClientBuilder setPrivateKey(Path privateKeyPath)
documentation above
.privateKeyPath
- representing the path to private key PEM file.ClientBuilder setPrivateKey(InputStream privateKeyInputStream)
documentation above
.privateKeyInputStream
- representing an InputStream with private key PEM file content.ClientBuilder setPrivateKey(PrivateKey privateKey)
documentation above
.privateKey
- the PrivateKey
instance.ClientBuilder setClientId(String clientId)
documentation above
.clientId
- string representing the client ID.ClientBuilder setKid(String kid)
kid
- string representing the Key ID.ClientBuilder setConnectionTimeout(int timeout)
timeout
- connection and socket timeout in secondsClientBuilder setOrgUrl(String baseUrl)
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.
baseUrl
- the base URL of the Okta REST API to use.ClientBuilder setRetryMaxElapsed(int maxElapsed)
maxElapsed
- retry max elapsed duration in secondsClientBuilder setRetryMaxAttempts(int maxAttempts)
maxAttempts
- retry max attemptsClientBuilder setRequestExecutorFactory(com.okta.commons.http.RequestExecutorFactory requestExecutorFactory)
RequestExecutorFactory
, otherwise it will be loaded as a Service / SPI
via the RequestExecutorFactory
class.requestExecutorFactory
- that should be used to create the RequestExecutorCopyright © 2017–2023 Okta. All rights reserved.