Libreria per l'accesso ai servizi REST IAM di Applica.

| Info | Dettagli | | --------------- | ------------------------------------------------------ | | Ultima versione | 5.0.* | | Autore | Roberto Conte Rosito | | Repository | https://bitbucket.org/applicaguru/iam-client | | Pipeline | https://bitbucket.org/applicaguru/iam-client/pipelines |

Prefazione

La libreria @applica-software-guru/iam-client è un client REST che consente l'integrazione di servizi IAM Applica. La sua implementazione si basa sui principi e le linee guida definite all'interno del progetto React-Admin.

Come si usa

La libreria può essere utilizzata in associazione a react-admin come authProvider (scopo per cui è nata) oppure direttamente come strumento per eseguire il login, aggiornare i token di autenticazione e, in generale, mantenere uno stato di sessione valido per l'utente potendo usufruire di tutti i metodi esposti da un provider IAM Applica.

Per installare la libreria:

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

Puoi utilizzarla all'interno di un progetto react-admin come authProvider seguendo la guida ufficiale.

Configurazione

Puoi configurare e rendere persistente un'istanza di authProvider utilizzando il metodo useAuthProvider:

@applica-software-guru/iam-client

Libreria client per l'integrazione con il servizio IAM di Applica. Fornisce helper per autenticazione, gestione device (PIN login), token, profili e utilità correlate.

Attenzione compatibilità

• Ultima versione di react-admin esplicitamente supportata: react-admin v5
• Peer dependencies raccomandate: react e react-dom (vedi package.json per i range esatti)

Prerequisiti

• Node.js (consigliato): 18.x o 20.x (20+ raccomandato per sviluppo con le dipendenze più recenti)
• npm o yarn
• TypeScript (se usi la tipizzazione nel progetto)

Installazione Installa la libreria nel tuo progetto:

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

Se usi TypeScript, assicurati di avere le tipizzazioni e typescript installati come devDependencies.

Peer dependencies La libreria richiede che il progetto host fornisca react e react-dom. La versione minima e i range sono dichiarati in package.json del pacchetto: controlla il file per i dettagli aggiornati.

Uso rapido Esempio minimo (TypeScript):

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

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

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

// registrare dispositivo e usare PIN login
const device = await auth.registerDevice('device-code-123');
await auth.resetPin(userId, '1234');
const result = await auth.pinLogin('device-code-123', '1234');

Per dettagli sull'API, guarda i tipi in src/types.ts e i metodi esposti in src/provider.ts.

Note crittografia (PIN login)

• Il client cifra il PIN con AES e invia un payload codificato in Base64 con questo formato (stringa prima della B64): ivHex::saltHex::ciphertextBase64
• Derivazione chiave: PBKDF2 con HMAC-SHA1, iterazioni e lunghezza specificate dall'istanza AesUtil (il client usa valore 128, 1000 per compatibilità col server).
• Assicurati che il server interpreti iv e salt come esadecimali e che usi PBKDF2WithHmacSHA1 per derivare la chiave.

Queste scelte sono necessarie per interoperare con l'implementazione server Java (format e hashing deterministico).

Script utili

• npm test — esegue la suite di test (Vitest)
• npm run build — build della libreria con Vite
• npm run eslint — esegue ESLint sulla codebase
• npm run format — formatta il codice con Prettier

Eseguire localmente i test

# installa dipendenze
npm install
# esegui i test
npm test

Se i test restano bloccati o ci sono errori legati a jsdom/vitest, verifica la versione di Node in uso (20+ raccomandato per alcune configurazioni) o usa le versioni di dipendenze compatibili (il repository contiene note su downgrade in caso di incompatibilità).

Contributi e sviluppo

• Prima di aprire PR, esegui npm run lint e npm test per assicurarti che tutto passi.
• Apri una branch dedicata per le modifiche di dipendenze o per aggiornamenti major.

Problemi comuni

• Warning deprecati come abab / domexception: causati da dipendenze transitive di jsdom. Soluzioni:
  • Aggiornare Node alla versione raccomandata (20+)
  • Aggiornare jsdom quando possibile o accettare il warning se l'impatto è solo informativo
• ESLint v9: se il tuo ambiente esegue ESLint 9, è presente eslint.config.mjs compatibile nel repository che carica la vecchia .eslintrc tramite plugin compat.

License MIT

Se vuoi, posso:

• aggiornare ulteriormente la sezione dei peerDependencies con range multi-major (es. per supportare React 17/18/19),
• aggiungere esempi più dettagliati su pinLogin (es. payload esatto),
• generare una sezione "Changelog" o "Upgrade notes" per le versioni più recenti.

Dimmi quale di queste preferisci e procedo. const isImpersonating = await authProvider.isImpersonating(); await authProvider.stopImpersonating();

## Storage

Puoi utilizzare uno storage differente dal `localStorage` presente all'interno del browser (per esempio se devi utilizzare questa libreria all'interno di un applicativo react-admin), per farlo devi passare un'istanza di `Storage` al metodo `useAuthProvider`:

```javascript
import { LocalStorage } from '@applica-software-guru/iam-client';

const storage = new LocalStorage();
const authProvider = useAuthProvider({ apiUrl, storage });

Se utilizzi la libreria sul web puoi utilizzare l'implementazione LocalStorage che non è altro che un wrapper di window.localStorage.

Di seguito un esempio di implementazione di MemoryStorage:

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

/**
 * Implementazione di StorageInterface che utilizza un oggetto in memoria.
 */
class MemoryStorage implements StorageInterface {
  storage: any;

  constructor() {
    this.storage = {};
  }

  getItem(key: string): Promise<string> {
    if (typeof this.storage[key] === 'undefined') {
      return Promise.resolve('');
    }
    return Promise.resolve(this.storage[key]);
  }
  setItem(key: string, value: string): Promise<void> {
    this.storage[key] = value;
    return Promise.resolve();
  }
  removeItem(key: string): Promise<void> {
    delete this.storage[key];
    return Promise.resolve();
  }
}

export default MemoryStorage;