OpenAM UI JS SDK

.github/workflows/deploy.yml

@@ -59,7 +59,7 @@ jobs:
         continue-on-error: true
         run: |
           mvn javadoc:aggregate -pl '-:openam-server,-:openam-server-only' \
-            -pl '-:openam-ui,-:openam-ui-ria,-:openam-ui-api' \
+            -pl '-:openam-ui,-:openam-ui-ria,-:openam-ui-api,-:openam-ui-js-sdk' \
             -pl '-:openam-server-auth-ui,-:openam-doc-ssoadm-ref,-:openam-liberty-schema' \
             -pl '-:openam-example-api-descriptor,-:openam-example-clientsdk-cli,-:openam-example-clientsdk-war'
       - name: Upload artifacts OpenAM Distribution Kit, containing all distributable artifacts

openam-server-only/pom.xml

@@ -108,6 +108,15 @@
                                     <overWrite>false</overWrite>
                                     <outputDirectory>${project.build.directory}/api</outputDirectory>
                                 </artifactItem>
+                                <artifactItem>
+                                    <groupId>org.openidentityplatform.openam</groupId>
+                                    <artifactId>openam-ui-js-sdk</artifactId>
+                                    <classifier>app</classifier>
+                                    <type>zip</type>
+                                    <overWrite>false</overWrite>
+                                    <outputDirectory>${project.build.directory}/extui</outputDirectory>
+                                    <includes>**/*</includes>
+                                </artifactItem>
                             </artifactItems>
                         </configuration>
                     </execution>
@@ -265,6 +274,14 @@
                             <targetPath>api</targetPath>
                             <filtering>true</filtering>
                         </webResource>
+                        <webResource>
+                            <directory>${project.build.directory}/extui/</directory>
+                            <includes>
+                                <include>**/**</include>
+                            </includes>
+                            <targetPath>extui</targetPath>
+                            <filtering>true</filtering>
+                        </webResource>
                         <webResource>
                             <directory>${basedir}/src/main/webapp</directory>
                             <includes>
@@ -567,6 +584,13 @@
             <type>jar</type>
         </dependency>
 
+        <dependency>
+            <groupId>org.openidentityplatform.openam</groupId>
+            <artifactId>openam-ui-js-sdk</artifactId>
+            <type>zip</type>
+            <classifier>app</classifier>
+        </dependency>
+
         <dependency>
             <groupId>org.openidentityplatform.openam</groupId>
             <artifactId>openam-core</artifactId>

openam-server-only/src/main/resources/services/amCORS.xml

@@ -40,7 +40,7 @@
                 serviceHierarchy="/DSAMEConfig/CORSService"
                 i18nFileName="amCORS"
                 resourceName="cors"
-                i18nKey="cors-service-description">
+                i18nKey="cors-service-description" revisionNumber="2">
             <Global>
                 <AttributeSchema name="cors-enabled"
                                  type="single"
@@ -93,6 +93,7 @@
                         <Value>Upgrade-Insecure-Requests</Value>
                         <Value>Referer</Value>
                         <Value>Cookie</Value>
+                        <Value>Accept-API-Version</Value>
                     </DefaultValues>
                 </AttributeSchema>
                 <AttributeSchema name="exposed-headers"

openam-ui/openam-ui-js-sdk/.env

@@ -0,0 +1,2 @@
+#VITE_OPENAM_SERVER=http://openam.example.org:8080
+#VITE_OPENAM_CONTEXT_PATH=/openam

openam-ui/openam-ui-js-sdk/.env.development

@@ -0,0 +1,2 @@
+VITE_OPENAM_SERVER=http://openam.example.org:8080
+VITE_OPENAM_CONTEXT_PATH=/openam

openam-ui/openam-ui-js-sdk/.gitignore

@@ -0,0 +1,29 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+
+*.zip
+
+example/

openam-ui/openam-ui-js-sdk/README.md

@@ -0,0 +1,144 @@
+# OpenAM Alternative Frontend SDK
+
+OpenAM is a robust access management solution, but integrating it with modern frontend applications can be complex and time-consuming. This SDK aims to simplify that process by providing pre-built React components and a flexible, modular setup, saving developers significant time while ensuring secure, seamless integration with OpenAM.
+
+This project is intended to provide an alternative frontend SDK for interacting with Open Identity Platform's OpenAM authentication services. It is built using modern web technologies and aims to simplify the integration process for developers.
+
+## Features
+- **Ease of Use**: Pre-configured React components ready for integration.
+- **Modular & Flexible**: Easily swap components and customize the SDK to suit your needs.
+- **TypeScript Support**: Enhance development experience with type safety and better code completion.
+- **Seamless Integration**: Easily integrate OpenAM with minimal configura
+
+# Prerequisites
+- Node.js 22 LTS and newer
+- OpenAM 14 and newer
+
+## Installation
+
+Clone and build the source code
+
+```bash
+git clone https://github.com/OpenIdentityPlatform/openam-js-sdk.git
+```
+
+```bash
+cd openam-js-sdk
+npm install
+npm run build
+```
+
+## Usage
+
+### As an Application
+
+Copy the contents of the `dist/app` folder into your OpenAM WAR file (or the extracted WAR contents in your web container), e.g., into a directory like `extui`, so it could be accessible in your OpenAM context path, for example, http://openam.example.org:8080/openam/extui
+
+You can also run the application in a standalone server. The only condition, the servers shold be on the same subdomain, so OpenAM's cookies could be sent from the frontend application.
+
+
+## As an SDK library
+
+To install the SDK, use npm or yarn:
+
+```bash
+npm install <path to openam-js-sdk folder> #for example /home/user/projects/openam-js-sdk
+# or
+yarn add <path to openam-js-sdk folder>
+``` 
+## Usage
+Here's a basic example of how to use the SDK in a React application:
+
+```tsx
+import React from 'react';
+import OpenAMUI from 'openam-js-sdk';
+
+const App = () => {
+  return (
+      <OpenAMUI />
+  );
+};
+```
+
+## Customization
+
+You can customize the SDK by providing your own UI components and styles. 
+
+To customize the application behaviour, customise the following settings:
+
+```ts
+export interface Config {
+    openamServer: string; //OpenAM server host, for example http://openam.example.org:8080
+    openamContextPath: string; //OpenAM context path, for example /openam
+    LoginForm: LoginForm; //LoginForm interface implementation
+    UserForm: UserForm; //UserForm interface implementation
+    ErrorForm: ErrorForm; //ErrorForm interface implementation
+    CallbackElement: CallbackElement; //CallbackElement interface implementation
+    ActionElements: ActionElements; //ActionElements interface implementation
+    redirectOnSuccessfulLogin: boolean; //redirects user on successful login to the target URL, otherwise shows a profile.
+    getOpenAmUrl: () => string; //returns a full OpenAM URL, for example http://openam.example.org:8080/openam
+}
+```
+
+for example
+
+```tsx
+//update the default configuration
+import { setConfig } from 'openam-js-sdk'
+
+setConfig({
+  openamServer: 'https://openam.example.org:443',
+  openamContextPath: '/am',
+  errorForm: ({ error, resetError }) => {
+    return <div>
+      <h1>An error occurred</h1>
+      <p>{error?.message}</p>
+      <input type="button" value="Retry" onClick={() => resetError()} />
+    </div>
+})
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <OpenAMUI />
+  </StrictMode>,
+)
+```
+
+There are components you can override:
+
+```tsx
+// renders a login form with callbacks
+export type LoginForm = React.FC<{
+  authData: AuthData,
+  setCallbackValue: (i: number, val: string) => void,
+  doLogin: (action: string) => void
+}> 
+
+// renders a callback such as NameCallback, PasswordCallback and so on
+export type CallbackElement = React.FC<{
+    callback: Callback
+    setCallbackValue: (val: string) => void
+}>
+
+// renders a user profile form
+export type UserForm = React.FC<{
+  userData: UserData,
+  setUserData: (userData: UserData) => void
+  saveHandler: () => void
+  savePasswordHandler: (password: string) => void
+}>
+
+// renders an authentication error form
+export type ErrorForm = React.FC<{
+    error: AuthError,
+    resetError: () => void
+}>
+
+// renders submit buttons; if there are no ConfirmationCallback in the callbacks array, renders the default button
+export type ActionElements = React.FC<{callbacks: Callback[]}>
+```
+
+
+## Contributing
+Contributions are welcome! Please fork the repository and submit a pull request with your changes. Make sure to follow the coding standards and include tests for any new features.
+

openam-ui/openam-ui-js-sdk/assembly/app-zip.xml

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ * The contents of this file are subject to the terms of the Common Development and
+ * Distribution License (the License). You may not use this file except in compliance with the
+ * License.
+ *
+ * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
+ * specific language governing permission and limitations under the License.
+ *
+ * When distributing Covered Software, include this CDDL Header Notice in each file and include
+ * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
+ * Header, with the fields enclosed by brackets [] replaced by your own identifying
+ * information: "Portions copyright [year] [name of copyright owner]".
+ *
+ * Copyright 2025 3A Systems LLC.
+-->
+<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.2.0"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.2.0 http://maven.apache.org/xsd/assembly-2.2.0.xsd">
+    <id>app</id>
+    <baseDirectory>/</baseDirectory>
+    <formats>
+        <format>zip</format>
+    </formats>
+    <fileSets>
+        <fileSet>
+            <directory>target/app</directory>
+            <outputDirectory>/</outputDirectory>
+        </fileSet>
+    </fileSets>
+</assembly>

openam-ui/openam-ui-js-sdk/assembly/lib-zip.xml

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ * The contents of this file are subject to the terms of the Common Development and
+ * Distribution License (the License). You may not use this file except in compliance with the
+ * License.
+ *
+ * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
+ * specific language governing permission and limitations under the License.
+ *
+ * When distributing Covered Software, include this CDDL Header Notice in each file and include
+ * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
+ * Header, with the fields enclosed by brackets [] replaced by your own identifying
+ * information: "Portions copyright [year] [name of copyright owner]".
+ *
+ * Copyright 2025 3A Systems LLC.
+-->
+<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.2.0"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.2.0 http://maven.apache.org/xsd/assembly-2.2.0.xsd">
+    <id>lib</id>
+    <baseDirectory>/</baseDirectory>
+    <formats>
+        <format>zip</format>
+    </formats>
+    <fileSets>
+        <fileSet>
+            <directory>target/lib</directory>
+            <outputDirectory>/</outputDirectory>
+        </fileSet>
+    </fileSets>
+</assembly>

openam-ui/openam-ui-js-sdk/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs['recommended-latest'],
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

openam-ui/openam-ui-js-sdk/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>openam-js-sdk</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>