Class STS

java.lang.Object
com.eqixiac.equinix.EquinixClient
com.eqixiac.equinix.STS
All Implemented Interfaces:
Closeable, AutoCloseable
public final class STS extends EquinixClient
The primary entry point for accessing the Equinix Security Token Service (STS) API (STS v1).

The STS exchanges OpenID Connect (OIDC) ID tokens - issued by trusted OIDC providers - for Equinix access tokens (RFC 8693 token exchange), and manages the trust relationships and discovery metadata that underpin that exchange:

  • tokens() - the OAuth 2.0 token exchange (POST /v1/token) and the granted-access-policy listing (POST /v1/accessPoliciesGranted).
  • oidcProviders() - registration and lifecycle (create / page / patch / delete / suspend / resume) of trusted OIDC providers within a root project.
  • discovery() - the unauthenticated discovery endpoints: the JSON Web Key Set (GET /jwks) and the OpenID Connect discovery document (GET /.well-known/openid-configuration).

Each accessor uses lazy initialization - the internal client is created on first access and reused for subsequent calls.

Service host and authentication

STS requests go to the service's own host, https://sts.eqix.equinix.com, declared as the hostName of the STS functional area in apiParams_STS.json. The unified gateway https://api.equinix.com answers 404 for every STS path. The OAuth client-credentials login (when one is needed) still goes to api.equinix.com. Override the host with getEquinixClient().setDomainEndPoint("STS", ...).

The token exchange, granted-access-policy listing, JWKS and OpenID discovery endpoints are unauthenticated in the specification: they never trigger an Equinix login and are sent without a bearer header. A workload that holds only an OIDC ID token can therefore use withoutCredentials(); OIDC-provider management still needs Equinix credentials.

Quick Start

BasicEquinixCredentials credentials = new BasicEquinixCredentials("clientId", "clientSecret");
STS sts = new STS(credentials);

StsToken token = sts.tokens().generate(new TokenRequest()
    .grantType("urn:ietf:params:oauth:grant-type:token-exchange")
    .subjectToken(idToken)
    .subjectTokenType("urn:ietf:params:oauth:token-type:id_token")
    .scope(StsScope.projectPolicies("abc-123")));

// Workload identity federation: no Equinix client secret needed for the exchange itself.
StsToken federated = STS.withoutCredentials().tokens().generate(request);
Author:
ianjones
See Also:

  • Constructor Details

    • STS

      public STS(EquinixCredentials equinixCredentials)
      Creates a new STS client using the provided credentials. Authentication occurs automatically on the first API call.
      Parameters:
      equinixCredentials - the OAuth2 credentials for authenticating with Equinix APIs

    • STS

      public STS(EquinixCredentials equinixCredentials, boolean isSandBoxed)
      Creates a new STS client with optional sandbox mode.
      Parameters:
      equinixCredentials - the OAuth2 credentials for authenticating with Equinix APIs
      isSandBoxed - true to use the sandbox environment for testing; false for production

    • STS

      public STS(EquinixCredentialsProvider credentialsProvider)
      Creates a new STS client whose credentials are resolved through the given provider. Authentication occurs automatically on the first API call.
      Parameters:
      credentialsProvider - supplies the OAuth2 credentials for authenticating with Equinix APIs

    • STS

      public STS(EquinixCredentialsProvider credentialsProvider, boolean isSandBoxed)
      Creates a new STS client over a custom credentials provider, with optional sandbox mode.
      Parameters:
      credentialsProvider - supplies the OAuth2 credentials for authenticating with Equinix APIs
      isSandBoxed - true to use the sandbox environment for testing; false for production

    • STS

      public STS(EquinixCredentials equinixCredentials, EquinixConfig config)
      Creates a new STS client with explicit EquinixConfig options.
      Parameters:
      equinixCredentials - the OAuth2 credentials for authenticating with Equinix APIs
      config - the construction-time options

    • STS

      public STS(EquinixCredentialsProvider credentialsProvider, EquinixConfig config)
      Creates a new STS client over a custom credentials provider with explicit EquinixConfig options.
      Parameters:
      credentialsProvider - supplies the OAuth2 credentials for authenticating with Equinix APIs
      config - the construction-time options

  • Method Details

    • withoutCredentials

      public static STS withoutCredentials()
      Creates an STS client with no Equinix credentials, for workload identity federation: the token exchange (tokens()) and discovery (discovery()) work without a login. Calling an operation that needs an Equinix bearer token (the oidcProviders() management API) fails with an EquinixClientException naming the missing credentials.
      Returns:
      a credential-less STS client targeting production

    • tokens

      public STSTokens tokens()
      Returns the client for the STS OAuth 2.0 token exchange (POST /v1/token) and the granted-access-policy listing (POST /v1/accessPoliciesGranted).
      Returns:
      the STSTokens client

    • oidcProviders

      public STSOidcProviders oidcProviders()
      Returns the client for managing trusted OIDC providers within a root project (/v1/projects/{projectId}/oidcProviders).
      Returns:
      the STSOidcProviders client

    • discovery

      public STSDiscovery discovery()
      Returns the client for the STS unauthenticated discovery endpoints - the JSON Web Key Set (GET /jwks) and the OpenID Connect discovery document (GET /.well-known/openid-configuration).
      Returns:
      the STSDiscovery client