# Class OidcClient

java.lang.Object
com.codename1.io.oidc.OidcClient

public final class OidcClient extends Object

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.

- ## Method Summary

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

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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