Salta ai contenuti

Gestire le applicazioni per l'API

Se un altro sistema (per esempio il Suo sistema HR o ERP) deve inviare richieste tramite l’interfaccia di programmazione (API), ha bisogno di un accesso: un’applicazione con ID client e segreto. Lo crea qui e lo consegna al Suo integratore.

Sezione Applicazioni con un'applicazione: nome, Attiva, Illimitata, ID client con simbolo di copia, durata di validità dei token e URL di reindirizzamento
  1. Con Crea applicazione crea un nuovo accesso.
  2. Accanto al nome è indicato Attiva o Disattivata e, con validità illimitata, anche Illimitata.
  3. ID client: con il simbolo accanto (Copia l’ID client) lo copia.
  4. Durata di validità dei token e il numero di URL di reindirizzamento (Nessuno, se non ce ne sono).
  5. Tramite ⋮ raggiunge tutte le azioni per l’applicazione, vedi più sotto.
Finestra Nuova applicazione con nome, descrizione, durata di validità dei token, URL di reindirizzamento consentiti e ambiti
  1. Clicchi su Crea applicazione e inserisca un Nome, per esempio «sistema HR».
  2. Descrizione: facoltativa, quale sistema usa questo accesso.
  3. Durata di validità dei token: per quanto tempo vale un token che l’altro sistema ottiene. Inserisca un numero e scelga ora/e, giorno/i, settimana/e, mese/i o anno/i, oppure Illimitata. Le nuove applicazioni partono con 30 giorni.
  4. URL di reindirizzamento consentiti: necessari solo se le persone accedono tramite questa applicazione. Inserisca un indirizzo completo con https:// e clicchi su Aggiungi. Per un accesso solo API lasci il campo vuoto.
  5. Ambiti (scope): quali dati l’applicazione riceve sulle persone che accedono. openid, profile, email e mobile sono attivati; un clic disattiva o attiva un ambito. In altro … inserisce un ambito proprio.
  6. Clicchi su Crea applicazione.

Che cosa significano le singole unità e quale numero massimo è ammesso è spiegato nell’applicazione actaPASS; il campo segue le stesse regole in entrambe le app.

Durata di validità dei token con la scelta Illimitata e l'avvertenza gialla

Se sceglie Illimitata, actaSIGN avverte: un token illimitato non scade mai. Chi lo possiede può agire a nome di questa applicazione. Se possibile, scelga una durata limitata.

Subito dopo la creazione actaSIGN mostra l’ID client e il Segreto (client secret). actaSIGN li genera entrambi da solo.

Finestra con ID client e segreto reso illeggibile, avvertenza, casella Ho conservato il segreto al sicuro e pulsante Fatto
  1. Copi l’ID client con Copia.
  2. Copi il Segreto (client secret) con Copia e lo conservi al sicuro. Viene mostrato solo questa volta.
  3. Metta la spunta Ho conservato il segreto al sicuro.
  4. Clicchi su Fatto. Prima la finestra non si può chiudere.

Se il segreto va perso, ne crei uno nuovo (⋮ → Crea nuovo segreto). Quello precedente non vale più.

Se l’altro sistema non può ottenere da solo un token, crei un token Bearer e lo consegni al Suo integratore.

  1. Apra ⋮ → Modifica, in Durata di validità dei token scelga l’unità Illimitata e clicchi su Salva.
  2. Apra ⋮ accanto all’applicazione e scelga Crea token Bearer. La voce c’è solo per un’applicazione attiva la cui durata di validità salvata è Illimitata.
  3. actaSIGN ottiene il token da actaPASS e lo mostra una volta, con la data fino alla quale è valido. Lo copi con Copia.
  4. Metta la spunta Ho conservato il token al sicuro e clicchi su Fatto.

L’altro sistema invia il token con ogni richiesta API nell’intestazione Authorization: Bearer …. Ogni clic su Crea token Bearer crea un nuovo token; quelli precedenti restano validi finché non li revoca come descritto più sotto.

Modificare, bloccare o eliminare un’applicazione

Sezione intitolata “Modificare, bloccare o eliminare un’applicazione”
Menu aperto di un'applicazione con Modifica, Crea token Bearer, Crea nuovo segreto, Disattiva ed Elimina
Voce del menu ⋮ Che cosa succede
Modifica Modificare nome, descrizione, durata di validità, URL di reindirizzamento e ambiti. Una nuova durata di validità vale per i token emessi da ora in poi.
Crea token Bearer Vedi più sopra.
Crea nuovo segreto Dopo una richiesta di conferma, un nuovo segreto, mostrato una volta come alla creazione. Quello precedente non funziona più, e tutti i token dell’applicazione vengono revocati subito.
Disattiva Dopo una richiesta di conferma l’applicazione non riceve più token, e tutti i token esistenti vengono revocati subito.
Attiva Compare per un’applicazione disattivata. Può di nuovo ottenere token; i token revocati con la disattivazione restano non validi.
Elimina Dopo una richiesta di conferma (Elimina definitivamente) l’applicazione viene eliminata, e tutti i suoi token vengono revocati subito. L’operazione non può essere annullata.
Richiesta di conferma Disattivare l'applicazione con l'indicazione che tutti i token esistenti vengono revocati subito

Dopo la disattivazione, l’eliminazione o un nuovo segreto, actaSIGN indica quanti token sono stati revocati, per esempio «2 token sono stati revocati.»

Per bloccare subito un token, per esempio perché è finito nelle mani sbagliate, in actaSIGN scelga per l’applicazione ⋮ → Crea nuovo segreto, Disattiva o Elimina. Tutti i token ancora validi dell’applicazione vengono allora revocati subito, in actaSIGN e in actaPASS, anche i token creati con Crea token Bearer. L’altro sistema ha poi bisogno di un nuovo segreto o di un nuovo token.

Se vuole bloccare solo i token e tenere il segreto (per esempio perché è stato trasmesso un token Bearer, ma il segreto è al sicuro), scelga ⋮ → Disattiva e poi ⋮ → Attiva. L’altro sistema ottiene poi nuovi token con il suo segreto; un nuovo token Bearer lo crea come descritto sopra.

Vede e modifica le stesse applicazioni anche in actaPASS sotto Configurare l’accesso API per altri sistemi (lì «Applicazioni»). Una modifica in un posto vale subito anche nell’altro.

  • In actaSIGN (consigliato): solo qui Crea nuovo segreto, Disattiva ed Elimina revocano subito i token esistenti.
  • In actaPASS: se gestisce un conto aziendale con più tenant. Blocchi comunque i token in actaSIGN. actaPASS non prevede la disattivazione; un’applicazione disattivata la riattiva in actaSIGN.
  • Vengono revocati i token che l’applicazione ha ottenuto da sola o che sono stati creati con Crea token Bearer. Le persone che hanno effettuato l’accesso nel browser tramite l’applicazione restano connesse.
  • Un’applicazione disattivata compare tratteggiata e in grigio nell’elenco. Per essa non può creare un token Bearer.
  • Segreto e token non compaiono mai nel log audit. Lì è indicato solo chi ha creato, modificato, disattivato o eliminato un’applicazione o creato un token, e quanti token sono stati revocati.
  • Se actaSIGN segnala «actaPASS non ha emesso un token», riprovi più tardi. Se l’errore persiste, si rivolga al supporto.