Library for accessing Applica's IAM REST services.

| Info | Details | | -------------- | ------------------------------------------------------ | | Latest version | 5.0.* | | Author | Roberto Conte Rosito | | Repository | https://bitbucket.org/applicaguru/iam-client | | Pipeline | https://bitbucket.org/applicaguru/iam-client/pipelines |

Preface

The @applica-software-guru/iam-client library is a REST client that enables integration with Applica IAM services. Its implementation is based on the principles and guidelines defined in the React-Admin project.

How to use

The library can be used with react-admin as an authProvider (its original purpose) or directly as a tool to perform login, update authentication tokens, and generally maintain a valid user session state, taking advantage of all methods exposed by an Applica IAM provider.

To install the library:

npm i @applica-software-guru/iam-client

You can use it within a react-admin project as an authProvider by following the official guide.

Configuration

You can configure and persist an instance of authProvider using the useAuthProvider method:

@applica-software-guru/iam-client

Client library for integration with Applica's IAM service. Provides helpers for authentication, device management (PIN login), tokens, profiles, and related utilities.

Compatibility Notice

• Latest explicitly supported react-admin version: react-admin v5
• Recommended peer dependencies: react and react-dom (see package.json for exact ranges)

Prerequisites

• Node.js (recommended): 18.x or 20.x (20+ recommended for development with the latest dependencies)
• npm or yarn
• TypeScript (if you use typing in your project)

Installation Install the library in your project:

npm install @applica-software-guru/iam-client
# or
# yarn add @applica-software-guru/iam-client

If you use TypeScript, make sure you have typings and typescript installed as devDependencies.

Peer dependencies The library requires the host project to provide react and react-dom. The minimum version and ranges are declared in the package's package.json: check the file for updated details.

Quick usage Minimal example (TypeScript):

import { createAuthProvider } from '@applica-software-guru/iam-client';

const auth = createAuthProvider({ apiUrl: 'https://iam.example.com' });

// classic login
await auth.login({ username: '[email protected]', password: 'secret' });

// register device and use PIN login
const device = await auth.registerDevice('device-code-123');
await auth.resetPin(userId, '1234');
const result = await auth.pinLogin('device-code-123', '1234');

For API details, see the types in src/types.ts and the methods exposed in src/provider.ts.

Encryption notes (PIN login)

• The client encrypts the PIN with AES and sends a Base64-encoded payload in this format (string before B64): ivHex::saltHex::ciphertextBase64
• Key derivation: PBKDF2 with HMAC-SHA1, iterations and length specified by the AesUtil instance (the client uses 128, 1000 for server compatibility).
• Make sure the server interprets iv and salt as hexadecimals and uses PBKDF2WithHmacSHA1 for key derivation.

These choices are necessary to interoperate with the Java server implementation (format and deterministic hashing).

Useful scripts

• npm test — runs the test suite (Vitest)
• npm run build — builds the library with Vite
• npm run eslint — runs ESLint on the codebase
• npm run format — formats code with Prettier

Run tests locally

# install dependencies
npm install
# run tests
npm test

If tests hang or there are errors related to jsdom/vitest, check the Node version in use (20+ recommended for some configurations) or use compatible dependency versions (the repository contains notes on downgrading in case of incompatibility).

Contributions and development

• Before opening a PR, run npm run lint and npm test to ensure everything passes.
• Open a dedicated branch for dependency changes or major updates.

Common issues

• Deprecated warnings like abab / domexception: caused by transitive dependencies of jsdom. Solutions:
  • Update Node to the recommended version (20+)
  • Update jsdom when possible or accept the warning if the impact is only informational
• ESLint v9: if your environment runs ESLint 9, there is a compatible eslint.config.mjs in the repository that loads the old .eslintrc via compat plugin.

License MIT

If you wish, I can:

• further update the peerDependencies section with multi-major ranges (e.g., to support React 17/18/19),
• add more detailed examples on pinLogin (e.g., exact payload),
• generate a "Changelog" or "Upgrade notes" section for the latest versions.

Let me know which you prefer and I'll proceed. const isImpersonating = await authProvider.isImpersonating(); await authProvider.stopImpersonating();

Documentation

Comprehensive documentation for all AuthProvider methods and usage scenarios is available in the docs/ folder:

• Overview
• React-Admin Integration
• User Login
• User Logout
• Session Validation
• Token Validation
• Get User Identity
• Get User Permissions
• Get User Roles
• User Impersonation
• Stop Impersonation
• Check Impersonation Status
• Device Registration
• Set or Reset PIN
• PIN Login
• Change Password
• Password Recovery
• Update User Profile
• User Registration
• Account Activation
• Third-Party Login
• Storage Usage

Each file contains method signatures, parameter details, usage examples, and notes.

For a general introduction, see docs/overview.md. For React-Admin integration, see docs/react-admin-integration.md. For storage customization, see docs/storage.md.