feat(oidc-client): implement stronger patterns

Author: cerebrl

e2e/oidc-app/src/main.ts

@@ -1,64 +1,21 @@
 import { oidc } from '@forgerock/oidc-client';
-import {
-  CallbackType,
-  Config,
-  FRAuth,
-  FRStep,
-  NameCallback,
-  PasswordCallback,
-} from '@forgerock/javascript-sdk';
 
 async function app() {
-  await Config.setAsync({
-    clientId: 'WebOAuthClient',
-    redirectUri: window.location.origin + '/',
-    scope: 'openid profile email me.read',
-    serverConfig: {
-      wellknown:
-        'https://openam-sdks.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration',
-    },
-  });
-
-  const step = await FRAuth.start();
-  console.log('Step:', step);
-
-  if ('callbacks' in step) {
-    const name = step.getCallbackOfType<NameCallback>(CallbackType.NameCallback);
-
-    const password = step.getCallbackOfType<PasswordCallback>(CallbackType.PasswordCallback);
-
-    name.setName('devicetestuser');
-    password.setPassword('password');
-  }
-
-  const success = await FRAuth.next(step as FRStep);
-  console.log('success:', success);
-
   const oidcClient = await oidc({
-    serverConfig: {
-      wellknown:
-        'https://openam-sdks.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration',
+    config: {
+      clientId: 'client_id',
+      redirectUri: 'https://example.com/redirect',
+      scope: 'openid',
+      serverConfig: {
+        wellknown:
+          'https://openam-sdks.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration',
+      },
     },
   });
 
-  if (oidcClient.error || !oidcClient.authorizeSilently || !oidcClient.createAuthorizeUrl) {
-    console.error('Error initializing oidc client:', oidcClient.error);
-    return;
-  }
-
-  const result = await oidcClient.authorizeSilently({
-    clientId: 'WebOAuthClient',
-    redirectUri: window.location.origin + '/',
-    responseType: 'code',
-    scope: 'openid',
-  });
+  const result = await oidcClient.authorize.url();
 
-  if ('error' in result) {
-    console.error('Error during authorization:', result.error);
-    return;
-  } else {
-    console.log('returning resolved params,', result);
-  }
+  console.log('Authorize URL:', result);
 }
 
 app();

packages/oidc-client/README.md

@@ -1,3 +1,22 @@
 # oidc-client
 
 A generic OpenID Connect (OIDC) client library for JavaScript and TypeScript, designed to work with any OIDC-compliant identity provider.
+
+```js
+// Initialize OIDC Client
+const oidcClient = oidc({ /* config */ });
+
+// Authorize API
+const authResponse = oidcClient.authorize.background(); // Returns code and state if successful, error and Auth URL if not
+const authUrl = oidcClient.authorize.url(); // Returns Auth URL or error
+
+// Tokens API
+const newTokens = oidcClient.tokens.exchange({ /* code, state */ }); // Returns new tokens or error
+const existingTokens = oidcClient.tokens.get(); // Returns existing tokens or error
+const revokeResponse = oidcClient.tokens.revoke(); // Returns null or error
+const endSessionResponse = oidcClient.tokens.endSession(); // Returns null or error
+
+// User API
+const user = oidcClient.user.info(); // Returns user object or error
+const logoutResponse = oidcClient.user.logout(); // Returns null or error
+```

packages/oidc-client/package.json

@@ -31,7 +31,6 @@
     "@forgerock/sdk-oidc": "workspace:*",
     "@forgerock/sdk-request-middleware": "workspace:*",
     "@forgerock/sdk-types": "workspace:*",
-    "@forgerock/storage": "workspace:*",
     "@reduxjs/toolkit": "catalog:"
   },
   "nx": {

packages/oidc-client/src/index.ts

@@ -1,2 +1 @@
-export * from './lib/token-store.js';
 export * from './lib/client.store.js';

packages/oidc-client/src/lib/authorize.request.ts

@@ -0,0 +1,59 @@
+import { iFrameManager } from '@forgerock/iframe-manager';
+import { createAuthorizeUrl, GetAuthorizationUrlOptions } from '@forgerock/sdk-oidc';
+
+import { createAuthorizeOptions, handleError, handleResponse } from './authorize.request.utils.js';
+
+import type { WellKnownResponse } from '@forgerock/sdk-types';
+
+import type { OidcConfig } from './config.types.js';
+
+export async function authorize(
+  wellknown: WellKnownResponse,
+  config: OidcConfig,
+  options?: GetAuthorizationUrlOptions,
+) {
+  const authorizePath = wellknown.authorization_endpoint;
+  const optionsWithDefaults = createAuthorizeOptions(config, options);
+  const authorizeUrl = await createAuthorizeUrl(authorizePath, optionsWithDefaults);
+
+  let response: Record<string, unknown>;
+
+  try {
+    /**
+     * If we support the pi.flow field, this means we are using a PingOne server.
+     * PingOne servers do not support redirection through iframes because they
+     * set iframe's to DENY.
+     */
+    if (wellknown.response_modes_supported?.includes('pi.flow')) {
+      /**
+       * We need to make a post (or a get) request and both are supported by
+       * PingOne.
+       */
+      const res = await fetch(authorizeUrl, {
+        method: 'POST',
+        credentials: 'include',
+      });
+
+      response = await res.json();
+    } else {
+      response = await iFrameManager().getParamsByRedirect({
+        url: authorizeUrl,
+        /***
+         * https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2
+         * The client MUST ignore unrecognized response parameters.
+         */
+        successParams: ['code', 'state'],
+        errorParams: ['error', 'error_description'],
+        timeout: config.serverConfig.timeout || 3000,
+      });
+    }
+
+    // Normalize response, for both success and failure, to handle both
+    // fetch and iframe
+    return await handleResponse(response, authorizePath, optionsWithDefaults);
+  } catch (error) {
+    // If an error occurs, we return an error response with the authorize URL
+    // so the application can handle the redirect.
+    return handleError(error, authorizePath, optionsWithDefaults);
+  }
+}

packages/oidc-client/src/lib/authorize.request.types.ts

@@ -0,0 +1,11 @@
+export interface AuthorizeSuccessResponse {
+  code: string;
+  state: string;
+  redirectUrl?: string; // Optional, used when the response is from a P1 server
+}
+
+export interface AuthorizeErrorResponse {
+  error: string;
+  error_description: string;
+  redirectUrl: string; // URL to redirect the user to for re-authorization
+}

packages/oidc-client/src/lib/authorize.request.utils.ts

@@ -0,0 +1,61 @@
+import { createAuthorizeUrl, GetAuthorizationUrlOptions } from '@forgerock/sdk-oidc';
+
+import { AuthorizeErrorResponse, AuthorizeSuccessResponse } from './authorize.request.types.js';
+import { OidcConfig } from './config.types.js';
+
+export function createAuthorizeOptions(
+  config: OidcConfig,
+  options?: GetAuthorizationUrlOptions,
+): GetAuthorizationUrlOptions {
+  return {
+    clientId: config.clientId,
+    redirectUri: config.redirectUri,
+    scope: config.scope || 'openid',
+    responseType: config.responseType || 'code',
+    ...options,
+  };
+}
+
+export async function handleResponse(
+  response: Record<string, unknown>,
+  authorizePath: string,
+  options: GetAuthorizationUrlOptions,
+) {
+  // Test if response is from a fetch to PingOne
+  if ('authorizeResponse' in response) {
+    const authorizeResponse = response.authorizeResponse as AuthorizeSuccessResponse;
+    return authorizeResponse;
+  }
+  // Test if response is from an iframe
+  if ('code' in response && 'state' in response) {
+    const authorizeResponse = response as unknown as AuthorizeSuccessResponse;
+    return authorizeResponse;
+  }
+
+  /**
+   * If we reach here, it means the response is missing code or state.
+   * Let's create a new authorize URL to redirect the user to the authorization endpoint
+   * provide it to the application so it can handle the redirect.
+   */
+  const newAuthorizeUrl = await createAuthorizeUrl(authorizePath, options);
+  return {
+    error: 'invalid_response',
+    error_description: 'Missing code or state in authorization response after redirect',
+    redirectUrl: newAuthorizeUrl,
+  } as AuthorizeErrorResponse;
+}
+
+export async function handleError(
+  error: unknown,
+  authorizePath: string,
+  options: GetAuthorizationUrlOptions,
+): Promise<AuthorizeErrorResponse> {
+  const message = error instanceof Error ? error.message : String(error);
+  const newAuthorizeUrl = await createAuthorizeUrl(authorizePath, options);
+
+  return {
+    error: 'network_error',
+    error_description: message || 'An error occurred while fetching the authorization URL',
+    redirectUrl: newAuthorizeUrl,
+  };
+}