identidad_oidc_sdk 0.1.3

Flutter OIDC Authorization Code + PKCE client for Identidad.

identidad_oidc_sdk

Flutter OIDC client SDK for Identidad using Authorization Code + PKCE.

This is the package to use when your Flutter app needs to sign users in with Identidad. It is not just a token helper. It performs the interactive OIDC login flow end to end.

This package is the Flutter interactive OIDC client defined by the shared SDK requirements in ../../docs/sdk-specification.md.

This package mirrors the flow used by identidad.nist/scripts/oidc_browser_client.py:

• discovery from /.well-known/openid-configuration
• authorize redirect with state, nonce, and PKCE
• token exchange against /oauth/token using Identidad's JSON body contract
• validation of id_token and access_token against issuer JWKS

Install

dependencies:
  identidad_oidc_sdk: ^0.1.3

What this package does

• starts the OIDC login flow in the browser
• generates PKCE code_verifier and code_challenge
• sends state and nonce
• receives the callback redirect in the app
• exchanges the authorization code at /oauth/token
• validates id_token and access_token
• exposes Identidad assurance claims like AAL and IAL

If you only need token verification

If your app already has a token and does not need login, use identidad_sdk instead.

Package contents

• IdentidadOidcClient: high-level OIDC client for login, callback handling, and token exchange
• IdentidadOidcClientOptions: issuer, client, redirect, and authentication configuration
• IdentidadOidcAuthorizationSession: generated PKCE, state, and nonce data for split flows
• IdentidadOidcTokens: validated login result with raw token response plus typed claims
• IdentidadIdTokenClaims: typed id_token claims including profile fields and AAL / IAL
• VerifiedIdentidadIdToken: validated id_token header and payload
• IdentidadBrowserAuthenticator: abstraction for browser/deep-link handling
• FlutterWebAuthBrowserAuthenticator: default Flutter implementation using flutter_web_auth_2
• IdentidadBrowserAuthenticationOptions: browser options for the default authenticator, including HTTPS callback handling

Full login example

This example signs the user in with Identidad from a Flutter app:

import 'package:identidad_oidc_sdk/identidad_oidc_sdk.dart';
import 'package:identidad_sdk/identidad_sdk.dart';

final client = IdentidadOidcClient(
  const IdentidadOidcClientOptions(
    issuer: 'https://identidad.com.py',
    clientId: 'your-mobile-client',
    redirectUri: 'com.studio.myapp:/oauth/callback',
    scope: 'openid profile email',
    browserAuthenticationOptions: IdentidadBrowserAuthenticationOptions(
      preferEphemeral: true,
    ),
  ),
);

final tokens = await client.signIn(
  acrValues: 'aal2',
  ial: 'ial1',
);

// OIDC login result
print(tokens.idTokenClaims.sub);
print(tokens.idTokenClaims.email);

// Access token exposed with Identidad claims
print(tokens.accessTokenClaims.acr.wireValue);
print(tokens.accessTokenClaims.ial.wireValue);
print(tokens.accessTokenClaims.scopes);

if (!hasAalAtLeast(tokens.accessTokenClaims.acr, Aal.aal2)) {
  throw StateError('AAL2 is required');
}

The signIn() call:

• opens the browser
• redirects the user to Identidad
• receives the callback in your app
• exchanges the authorization code for tokens
• validates id_token and access_token

Requesting assurance

You can request Identidad assurance levels during login:

final tokens = await client.signIn(
  acrValues: 'aal2',
  ial: 'ial1',
);

Then enforce them in app code:

if (!hasAalAtLeast(tokens.accessTokenClaims.acr, Aal.aal2)) {
  throw StateError('AAL2 is required for this action');
}

Redirect URI

Register a redirect URI in your Identidad client, for example:

• com.studio.myapp:/oauth/callback
• https://app.example.com/auth.html

The same value must be passed to redirectUri in IdentidadOidcClientOptions.

If your redirectUri uses https, the default browser authenticator now derives the required httpsHost and httpsPath values for flutter_web_auth_2 automatically. Override them only if your platform setup needs something different:

const IdentidadOidcClientOptions(
  issuer: 'https://identidad.com.py',
  clientId: 'your-web-client',
  redirectUri: 'https://app.example.com/auth.html',
  browserAuthenticationOptions: IdentidadBrowserAuthenticationOptions(
    httpsHost: 'app.example.com',
    httpsPath: '/auth.html',
  ),
);

If your issuer is https://identidad.com.py, the SDK will discover:

• https://identidad.com.py/.well-known/openid-configuration
• the issuer authorization_endpoint
• the issuer token_endpoint
• the issuer jwks_uri

Advanced usage

You can split the flow if you want custom browser or deep-link handling:

final session = await client.createAuthorizationSession();
final authorizeUri = await client.buildAuthorizationUri(session);

// Open authorizeUri with your own browser/deep-link handler.
final callbackUri = Uri.parse('com.studio.myapp:/oauth/callback?code=...&state=...');

final tokens = await client.exchangeAuthorizationCallback(
  session: session,
  callbackUri: callbackUri,
);

Supported features

• Authorization Code + PKCE
• OIDC discovery
• state validation
• nonce validation
• id_token signature and claim validation
• access_token signature and claim validation
• AAL / IAL exposure through identidad_sdk
• optional confidential-client support with clientSecretPost or clientSecretBasic

Current limitations

• no QR login or cross-device login flow
• no passkey registration/assertion helpers
• no dedicated step-up client for /oauth/step-up/start or /oauth/step-up/confirm
• no logout helper
• no refresh-token helper API yet

Platform setup note

This package uses flutter_web_auth_2. Your app still needs the platform-specific callback/deep-link configuration for Android, iOS, and any other target platform you ship.

For Flutter Web, the callback URL must point to a page in your app that posts the callback URL back to the opener and then closes itself. A minimal web/auth.html page should:

• call window.opener.postMessage(...) or write the callback URL to localStorage
• invoke window.close() after the callback is sent

If that page does not exist, the login may succeed but the popup/tab will stay open.

Development

flutter pub get
flutter test

Publish

See RELEASING.md.