public final class OidcClient

  1. Object
  2. OidcClient

Modern OpenID Connect / OAuth 2.0 client. Built around the authorization-code flow with PKCE (RFC 7636) and the system browser. Use it as the foundation for all new sign-in integrations:

OidcClient.discover("https://accounts.google.com").ready(new SuccessCallback<OidcClient>() {
    public void onSucess(OidcClient client) {
        client.setClientId("YOUR_CLIENT_ID")
              .setRedirectUri("com.example.app:/oauth2redirect")
              .setScopes("openid", "email", "profile");
        client.authorize().ready(new SuccessCallback<OidcTokens>() {
            public void onSucess(OidcTokens tokens) {
                // use tokens.getAccessToken() / tokens.getIdToken()
            }
        });
    }
});

What this gives you that Oauth2 does not

  • Discovery via .well-known/openid-configuration so you only configure the issuer URL, not five separate endpoints
  • PKCE S256 on every flow (mandatory; many providers now require it)
  • System-browser sign-in via SystemBrowser (the previous class used an in-app WebView that modern IdPs reject)
  • Refresh-token flow surfaced as a first-class method
  • ID-token claim decoding via OidcTokens.getClaim(String)
  • Pluggable TokenStore persistence
  • Nonce + state verification on every authorization round-trip

Things this class deliberately does NOT do

  • Verify the ID token signature. This requires the provider’s JWKS and ECDSA/RSA verification, which is not feasible on every supported platform without pulling in a heavy dep. The remedy is: trust the TLS connection to the well-known issuer (i.e. always discover, never pass tokens to a server without re-validating server-side).
  • Implicit / hybrid / device flows. Use the lower-level ConnectionRequest APIs if you need those.

Methods

public static OidcClient create(OidcConfiguration configuration)Constructs a client from an already-known OidcConfiguration.
public static AsyncResource<OidcClient> discover(String issuer)Fetches <issuer>/.well-known/openid-configuration and resolves with an OidcClient pre-populated with the discovered endpoints.
public OidcConfiguration getConfiguration()
public OidcClient setClientId(String clientId)
public OidcClient setClientSecret(String clientSecret)
public OidcClient setRedirectUri(String redirectUri)
public OidcClient setScopes(String... scopes)
public OidcClient setScopes(List<String> scopes)
public OidcClient setAuthorizationParameters(String... kv)Extra name=value parameters appended to the authorization-endpoint URL.
public OidcClient setTokenParameters(String... kv)Extra name=value parameters sent as form data on every token-endpoint POST.
public OidcClient setTokenStore(TokenStore store)Swaps the token persistence strategy.
public OidcClient setStoreKey(String key)Override the key under which tokens are stored.
public OidcClient setEnforceNonce(boolean enforce)false skips the nonce claim check on the returned ID token.
public OidcClient setResponseMode(String mode)Sets the response_mode parameter sent on the authorization URL (e.g. "form_post" for Apple Sign-In with the web fallback).
public AsyncResource<OidcTokens> authorize()Launches an authorization-code flow with PKCE.
public AsyncResource<OidcTokens> refresh(String refreshToken)Exchanges a stored refresh token for a fresh access token.
public AsyncResource<OidcTokens> loadStoredTokens()Returns previously-saved tokens for this client (or null).
public AsyncResource<OidcTokens> refreshIfExpired(int leewaySeconds)Loads stored tokens; if they are within leewaySeconds of expiring, runs a refresh and saves the new tokens.
public AsyncResource<Boolean> revoke(String token)Sends a token-revocation request to the issuer (RFC 7009).
public AsyncResource<Boolean> clearStoredTokens()Clears any stored tokens for this client.

Inherited methods

Method details

create

public static OidcClient create(OidcConfiguration configuration)
Constructs a client from an already-known OidcConfiguration. Use discover(String) when you’d rather pull the endpoints from the provider’s .well-known/openid-configuration document.

discover

public static AsyncResource<OidcClient> discover(String issuer)

Fetches <issuer>/.well-known/openid-configuration and resolves with an OidcClient pre-populated with the discovered endpoints. The returned client still needs clientId, redirectUri and scopes before authorize() will work.

Trailing slashes on issuer are tolerated.

getConfiguration

public OidcConfiguration getConfiguration()

setClientId

public OidcClient setClientId(String clientId)

setClientSecret

public OidcClient setClientSecret(String clientSecret)

setRedirectUri

public OidcClient setRedirectUri(String redirectUri)

setScopes

public OidcClient setScopes(String... scopes)

setScopes

public OidcClient setScopes(List<String> scopes)

setAuthorizationParameters

public OidcClient setAuthorizationParameters(String... kv)
Extra name=value parameters appended to the authorization-endpoint URL. Use for provider-specific options like Google’s prompt=consent or Apple’s response_mode=form_post. Values are URL-encoded.

setTokenParameters

public OidcClient setTokenParameters(String... kv)
Extra name=value parameters sent as form data on every token-endpoint POST.

setTokenStore

public OidcClient setTokenStore(TokenStore store)
Swaps the token persistence strategy. Defaults to TokenStore.DefaultStorageTokenStore.

setStoreKey

public OidcClient setStoreKey(String key)
Override the key under which tokens are stored. Defaults to the issuer + client-id pair so that multiple clients can coexist.

setEnforceNonce

public OidcClient setEnforceNonce(boolean enforce)
false skips the nonce claim check on the returned ID token. Only disable when you have a very good reason (e.g. provider known not to echo the nonce); the default is to enforce.

setResponseMode

public OidcClient setResponseMode(String mode)
Sets the response_mode parameter sent on the authorization URL (e.g. "form_post" for Apple Sign-In with the web fallback).

authorize

public AsyncResource<OidcTokens> authorize()
Launches an authorization-code flow with PKCE. The user is sent to the system browser to sign in; the returned AsyncResource completes with the token set or errors with OidcException (e.g. USER_CANCELLED, STATE_MISMATCH).

refresh

public AsyncResource<OidcTokens> refresh(String refreshToken)
Exchanges a stored refresh token for a fresh access token. Pass the value returned from OidcTokens.getRefreshToken() on a previous flow. The new tokens are persisted via the current TokenStore.

loadStoredTokens

public AsyncResource<OidcTokens> loadStoredTokens()
Returns previously-saved tokens for this client (or null). Combine with refreshIfExpired(int) to silently bring the session back to life on app launch.

refreshIfExpired

public AsyncResource<OidcTokens> refreshIfExpired(int leewaySeconds)
Loads stored tokens; if they are within leewaySeconds of expiring, runs a refresh and saves the new tokens. Completes with null when nothing is stored or when the stored token has no refresh token and has already expired.

revoke

public AsyncResource<Boolean> revoke(String token)
Sends a token-revocation request to the issuer (RFC 7009). Silently no-ops when the issuer does not advertise a revocation_endpoint.

clearStoredTokens

public AsyncResource<Boolean> clearStoredTokens()
Clears any stored tokens for this client. Does not call the issuer’s revocation endpoint – combine with revoke(String) if you want a proper sign-out.