Merge pull request #344 from ForgeRock/justin_oidc-mods

feat(oidc-client): implement authorize API

Author: cerebrl

.changeset/dirty-queens-design.md

@@ -0,0 +1,11 @@
+---
+'@forgerock/iframe-manager': minor
+'@forgerock/sdk-oidc': minor
+'@forgerock/oidc-client': minor
+---
+
+Implement authorize functionality in oidc-client
+
+- Provide authorize URL method for URL creation
+- Provide background method for authorization without redirection
+- Introduce Micro from the Effect package

.gitignore

@@ -6,6 +6,7 @@
 .npm/_logs
 
 # Generated code
+logs/*
 tmp/
 e2e/**/dist
 */dist/*

CLAUDE.md

@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is the Ping JavaScript SDK - a monorepo containing multiple packages for web applications integrating with the Ping platform. The SDK provides APIs for user authentication, device management, and accessing Ping-secured resources.
+
+## Development Commands
+
+### Core Commands
+
+- `pnpm build` - Build all affected packages
+- `pnpm test` - Run tests for all affected packages
+- `pnpm lint` - Lint all affected packages
+- `pnpm format` - Format code using Prettier
+- `pnpm nx typecheck` - Run TypeScript type checking
+
+### Package Management
+
+- `pnpm create-package` - Generate a new library package using Nx
+- `pnpm nx serve <package-name>` - Serve a specific package in development
+- `pnpm nx test <package-name> --watch` - Run tests for a specific package in watch mode
+
+### E2E Testing
+
+- `pnpm test:e2e` - Run end-to-end tests for affected packages
+- Individual e2e apps are in `e2e/` directory with their own test suites
+
+## Architecture
+
+### Monorepo Structure
+
+The repository uses **Nx** as the monorepo tool with the following structure:
+
+```
+packages/
+├── davinci-client/          # DaVinci flow orchestration client
+├── device-client/           # Device management (binding, profiles, WebAuthn)
+├── oidc-client/            # OpenID Connect authentication client
+├── protect/                # Ping Protect fraud detection
+├── sdk-effects/            # Effect-based utilities (logger, storage, etc.)
+│   ├── iframe-manager/
+│   ├── logger/
+│   ├── oidc/
+│   ├── sdk-request-middleware/
+│   └── storage/
+├── sdk-types/              # Shared TypeScript types
+└── sdk-utilities/          # Common utilities (PKCE, URL handling)
+```
+
+### Key Packages
+
+- **davinci-client**: State management for DaVinci authentication flows using Redux Toolkit
+- **oidc-client**: OIDC authentication with token management and storage
+- **device-client**: Device binding, profiles, OATH, Push, and WebAuthn capabilities
+- **protect**: Fraud detection and risk assessment integration
+- **sdk-effects**: Effect-based architecture packages for common functionalities
+
+### Technology Stack
+
+- **Package Manager**: pnpm with workspace configuration
+- **Build Tool**: Vite for building and bundling
+- **Testing**: Vitest for unit tests, Playwright for e2e tests
+- **State Management**: Redux Toolkit (in davinci-client)
+- **TypeScript**: Strict typing with composite project configuration
+- **Linting**: ESLint with Prettier integration
+
+### Nx Configuration
+
+- Uses target defaults for build, test, lint, and typecheck
+- Caching enabled for build and test targets
+- Workspace layout configured for packages and e2e apps
+- Parallel execution limited to 1 for consistency
+
+### Package Dependencies
+
+Packages use workspace references (`workspace:*`) for internal dependencies and catalog references (`catalog:`) for shared external dependencies like `@reduxjs/toolkit`.
+
+### Testing Strategy
+
+- Unit tests: Vitest with coverage reporting
+- E2E tests: Playwright with dedicated test apps in `e2e/` directory
+- Mock API server available in `e2e/mock-api-v2/` for testing
+
+## Development Notes
+
+- All packages are built as ES modules with TypeScript declarations
+- Use `pnpm nx affected` commands to run tasks only on changed packages
+- The repository uses conventional commits and automated releases via changesets
+- Individual packages can be tested independently using their specific build/test scripts

e2e/oidc-app/package.json

@@ -9,6 +9,7 @@
     "serve": "pnpm nx nxServe"
   },
   "dependencies": {
+    "@forgerock/javascript-sdk": "^4.8.2",
     "@forgerock/oidc-client": "workspace:*"
   },
   "nx": {

e2e/oidc-app/src/main.ts

@@ -1 +1,37 @@
-console.log('Starting OIDC App...');
+import { oidc } from '@forgerock/oidc-client';
+
+async function app() {
+  const oidcClient = await oidc({
+    config: {
+      clientId: 'WebOAuthClient',
+      redirectUri: 'http://localhost:8443/',
+      scope: 'openid',
+      serverConfig: {
+        wellknown:
+          'https://openam-sdks.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration',
+      },
+    },
+  });
+
+  // create object from URL query parameters
+  const urlParams = new URLSearchParams(window.location.search);
+  const code = urlParams.get('code');
+  // const state = urlParams.get('state');
+  // get error and error_description if they exist
+  const error = urlParams.get('error');
+  // const errorDescription = urlParams.get('error_description');
+
+  if (!code && !error) {
+    const response = await oidcClient.authorize.background();
+
+    if ('error' in response) {
+      console.error('Authorization Error:', response);
+      // window.location.assign(response.redirectUrl);
+      return;
+    } else if ('code' in response) {
+      console.log('Authorization Code:', response.code);
+    }
+  }
+}
+
+app();

packages/davinci-client/src/lib/davinci.api.ts

@@ -267,6 +267,7 @@ export const davinciApi = createApi({
             login: 'redirect', // TODO: improve this in SDK to be more semantic
             redirectUri: state?.config?.redirectUri,
             responseType: state?.config?.responseType as 'code',
+            responseMode: 'pi.flow',
             scope: state?.config?.scope,
           });
           const url = new URL(authorizeUrl);

packages/oidc-client/README.md

@@ -1,3 +1,26 @@
 # 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

@@ -26,8 +26,13 @@
     "test:watch": "pnpm nx nxTest --watch"
   },
   "dependencies": {
+    "@forgerock/iframe-manager": "workspace:*",
+    "@forgerock/sdk-logger": "workspace:*",
+    "@forgerock/sdk-oidc": "workspace:*",
+    "@forgerock/sdk-request-middleware": "workspace:*",
     "@forgerock/sdk-types": "workspace:*",
-    "@forgerock/storage": "workspace:*"
+    "@reduxjs/toolkit": "catalog:",
+    "effect": "^3.12.7"
   },
   "nx": {
     "tags": ["scope:package"]

packages/oidc-client/src/index.ts

@@ -1 +1,7 @@
-export * from './lib/token-store.js';
+/*
+ * Copyright (c) 2025 Ping Identity Corporation. All rights reserved.
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+export * from './lib/client.store.js';

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

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) 2025 Ping Identity Corporation. All rights reserved.
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+import { CustomLogger } from '@forgerock/sdk-logger';
+import { GetAuthorizationUrlOptions } from '@forgerock/sdk-oidc';
+import { Micro } from 'effect';
+
+import {
+  authorizeFetchµ,
+  createAuthorizeUrlµ,
+  authorizeIframeµ,
+  buildAuthorizeOptionsµ,
+  createAuthorizeErrorµ,
+} from './authorize.request.utils.js';
+
+import type { WellKnownResponse } from '@forgerock/sdk-types';
+
+import type { OidcConfig } from './config.types.js';
+import { AuthorizeErrorResponse, AuthorizeSuccessResponse } from './authorize.request.types.js';
+
+export async function authorizeµ(
+  wellknown: WellKnownResponse,
+  config: OidcConfig,
+  log: CustomLogger,
+  options?: GetAuthorizationUrlOptions,
+) {
+  return buildAuthorizeOptionsµ(wellknown, config, options).pipe(
+    Micro.flatMap(([url, config, options]) => createAuthorizeUrlµ(url, config, options)),
+    Micro.tap((url) => log.debug('Authorize URL created', url)),
+    Micro.tapError((url) => Micro.sync(() => log.error('Error creating authorize URL', url))),
+    Micro.flatMap(([url, config, options]) => {
+      if (options.responseMode === 'pi.flow') {
+        /**
+         * 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.
+         */
+        return authorizeFetchµ(url).pipe(
+          Micro.flatMap((response) => {
+            if ('authorizeResponse' in response) {
+              log.debug('Received authorize response', response.authorizeResponse);
+              return Micro.succeed(response.authorizeResponse);
+            }
+            log.error('Error in authorize response', response);
+            return Micro.fail(createAuthorizeErrorµ(response, wellknown, config, options));
+          }),
+        );
+      } else {
+        /**
+         * If the response mode is not pi.flow, then we are likely using a traditional
+         * redirect based server supporting iframes. An example would be PingAM.
+         */
+        return authorizeIframeµ(url, config).pipe(
+          Micro.flatMap((response) => {
+            if ('code' in response && 'state' in response) {
+              log.debug('Received authorization code', response);
+              return Micro.succeed(response as unknown as AuthorizeSuccessResponse);
+            }
+            log.error('Error in authorize response', response);
+            const errorResponse = response as unknown as AuthorizeErrorResponse;
+            return Micro.fail(createAuthorizeErrorµ(errorResponse, wellknown, config, options));
+          }),
+        );
+      }
+    }),
+  );
+}