|
| 1 | +# OpenAM Alternative Frontend SDK |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +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. |
| 6 | + |
| 7 | +## Features |
| 8 | +- **Ease of Use**: Pre-configured React components ready for integration. |
| 9 | +- **Modular & Flexible**: Easily swap components and customize the SDK to suit your needs. |
| 10 | +- **TypeScript Support**: Enhance development experience with type safety and better code completion. |
| 11 | +- **Seamless Integration**: Easily integrate OpenAM with minimal configuration. |
| 12 | + |
| 13 | +# Prerequisites |
| 14 | +- Node.js 22 LTS and newer |
| 15 | +- OpenAM 14 and newer |
| 16 | + |
| 17 | +## Installation |
| 18 | + |
| 19 | +Clone and build the source code |
| 20 | + |
| 21 | +```bash |
| 22 | +git clone https://github.com/OpenIdentityPlatform/openam-js-sdk.git |
| 23 | +``` |
| 24 | + |
| 25 | +```bash |
| 26 | +cd openam-js-sdk |
| 27 | +npm install |
| 28 | +npm run build |
| 29 | +``` |
| 30 | + |
| 31 | +## Usage |
| 32 | + |
| 33 | +### As an Application |
| 34 | + |
| 35 | +Copy the contents of the `target/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 |
| 36 | + |
| 37 | +You can also run the application in a standalone server. The only condition, the servers should be on the same subdomain, so OpenAM's cookies could be sent from the frontend application. |
| 38 | + |
| 39 | + |
| 40 | +## As an SDK library |
| 41 | + |
| 42 | +To install the SDK, use npm or yarn: |
| 43 | + |
| 44 | +```bash |
| 45 | +npm install <path to openam-js-sdk folder> #for example /home/user/projects/openam-js-sdk |
| 46 | +# or |
| 47 | +yarn add <path to openam-js-sdk folder> |
| 48 | +``` |
| 49 | +## Usage |
| 50 | +Here's a basic example of how to use the SDK in a React application: |
| 51 | + |
| 52 | +```tsx |
| 53 | +import React from 'react'; |
| 54 | +import { OpenAMUI } from 'openam-js-sdk'; |
| 55 | + |
| 56 | +const App = () => { |
| 57 | + return ( |
| 58 | + <OpenAMUI /> |
| 59 | + ); |
| 60 | +}; |
| 61 | +``` |
| 62 | + |
| 63 | +## Customization |
| 64 | + |
| 65 | +You can customize the SDK by providing your own UI components and styles. |
| 66 | + |
| 67 | +To customize the application behaviour, customise the following settings: |
| 68 | + |
| 69 | +```ts |
| 70 | +export interface Config { |
| 71 | + openamServer: string; //OpenAM server host, for example http://openam.example.org:8080 |
| 72 | + openamContextPath: string; //OpenAM context path, for example /openam |
| 73 | + LoginForm: LoginForm; //LoginForm interface implementation |
| 74 | + UserForm: UserForm; //UserForm interface implementation |
| 75 | + ErrorForm: ErrorForm; //ErrorForm interface implementation |
| 76 | + CallbackElement: CallbackElement; //CallbackElement interface implementation |
| 77 | + ActionElements: ActionElements; //ActionElements interface implementation |
| 78 | + redirectOnSuccessfulLogin: boolean; //redirects user on successful login to the target URL, otherwise shows a profile. |
| 79 | + getOpenAmUrl: () => string; //returns a full OpenAM URL, for example http://openam.example.org:8080/openam |
| 80 | +} |
| 81 | +``` |
| 82 | + |
| 83 | +for example |
| 84 | + |
| 85 | +```tsx |
| 86 | +// update the default configuration |
| 87 | +import React, { StrictMode } from 'react'; |
| 88 | +import { createRoot } from 'react-dom/client'; |
| 89 | +import { OpenAMUI, setConfig } from 'openam-js-sdk'; |
| 90 | + |
| 91 | +setConfig({ |
| 92 | + openamServer: 'https://openam.example.org:443', |
| 93 | + openamContextPath: '/am', |
| 94 | + ErrorForm: ({ error, resetError }) => { |
| 95 | + return ( |
| 96 | + <div> |
| 97 | + <h1>An error occurred</h1> |
| 98 | + <p>{error?.message}</p> |
| 99 | + <input |
| 100 | + type="button" |
| 101 | + value="Retry" |
| 102 | + onClick={() => resetError()} |
| 103 | + /> |
| 104 | + </div> |
| 105 | + ); |
| 106 | + }, |
| 107 | +}); |
| 108 | + |
| 109 | +createRoot(document.getElementById('root')!).render( |
| 110 | + <StrictMode> |
| 111 | + <OpenAMUI /> |
| 112 | + </StrictMode>, |
| 113 | +); |
| 114 | +``` |
| 115 | + |
| 116 | +There are components you can override: |
| 117 | + |
| 118 | +```tsx |
| 119 | +// renders a login form with callbacks |
| 120 | +export type LoginForm = React.FC<{ |
| 121 | + authData: AuthData, |
| 122 | + setCallbackValue: (i: number, val: string) => void, |
| 123 | + doLogin: (action: string) => void |
| 124 | +}> |
| 125 | + |
| 126 | +// renders a callback such as NameCallback, PasswordCallback and so on |
| 127 | +export type CallbackElement = React.FC<{ |
| 128 | + callback: Callback |
| 129 | + setCallbackValue: (val: string) => void |
| 130 | +}> |
| 131 | + |
| 132 | +// renders a user profile form |
| 133 | +export type UserForm = React.FC<{ |
| 134 | + userData: UserData, |
| 135 | + setUserData: (userData: UserData) => void |
| 136 | + saveHandler: () => void |
| 137 | + savePasswordHandler: (password: string) => void |
| 138 | +}> |
| 139 | + |
| 140 | +// renders an authentication error form |
| 141 | +export type ErrorForm = React.FC<{ |
| 142 | + error: AuthError, |
| 143 | + resetError: () => void |
| 144 | +}> |
| 145 | + |
| 146 | +// renders submit buttons; if there are no ConfirmationCallback in the callbacks array, renders the default button |
| 147 | +export type ActionElements = React.FC<{callbacks: Callback[]}> |
| 148 | +``` |
| 149 | +
|
| 150 | +
|
| 151 | +## Contributing |
| 152 | +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. |
| 153 | +
|
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4&size=40){kind=avatar}
0 commit comments