Skip to main content

Login Utente

Il flusso di autenticazione di un utente all'interno di TS Digital si suddivide in 2 parti: generazione di un nonce e generazione del token JWT.

Generazione di un nonce

Un nonce è una stringa generata randomicamente utilizzata per assicurare l'univocità di una richiesta di login verso TS Digital. La generazione del nonce è effettuata attraverso una chiamata all'apposita API:

[POST] /api/v3/nonces

Headers

Sono richiesti gli header standard di TS Digital, con l'eccezione dell'header Authorization.

Body

{
  "id": "mail@test.com"
}
  • id: identificativo dell'utente all'interno di TS Digital. Per le utenze personali si tratta dell'indirizzo email utilizzato in fase di registrazione, per le utenze tecniche si tratta invece dell'ID fornito al momento della creazione della stessa.

Risposte

Tutte le risposte sono in formato JSON

HTTP 200

Il nonce è stato generato con successo

{
  "nonce": "nonce-string"
}
  • nonce: il nonce generato per l'utente, da utilizzare nella chiamata di generazione del token JWT

HTTP 400

Parametro obbligatorio mancante nella richiesta

{
  "code": "string",
  "status": "string",
  "error": "string",
  "message": "string",
  "timestamp": "string"
}

HTTP 404

Non esiste alcun utente con l'ID specificato

{
  "code": "string",
  "status": "string",
  "error": "string",
  "message": "string",
  "timestamp": "string"
}

HTTP 500

Si è verificato un errore interno del server nella generazione del nonce

{
  "code": "string",
  "status": "string",
  "error": "string",
  "message": "string",
  "timestamp": "string"
}

Generazione del token JWT

Il token JWT è il token di autenticazione utilizzato per tutte le chiamate effettuate verso i servizi di TS Digital. All'interno del token sono disponibili alcuni dati sull'utente e sul token stesso:

{
  "sub": "id-utente",
  "passwordExpirationDate": 32506271999999,
  "iss": "https://agyo.io",
  "tsId": "tsid@tsid.com",
  "given_name": "Name",
  "locale": "it-IT",
  "uid": "uuid-v4-identifier",
  "aud": "https://agyo.io",
  "provider": "agyo",
  "name": "Name Surname",
  "appKey": false,
  "userType": "P",
  "exp": 1600109670,
  "family_name": "Surname",
  "iat": 1600088070,
  "jti": "uuid-v4-identifier",
  "hash": "token hash"
}

 

  • sub: soggetto a cui fa riferimento il token. Corrisponde con la mail per le utenze personali e ad un UUIDV4 per le utenze tecniche/applicative
  • passwordExpirationDate: unix timestamp (in millisecondi) della data di scadenza della password associata all'utente
  • iss: issuer del token
  • tsId: mail dell'account Teamsystem ID associato all'utenza TS Digital, se presente
  • given_name: nome dell'utente
  • locale: locale dell'utente
  • uid: identificativo univoco dell'utente all'interno di TS Digital
  • aud: audience bersaglio del token
  • provider: provider che ha generato il token
  • name: stringa che combina first_name e family_name
  • appKey: se true, il token fa riferimento ad una utenza applicativa
  • userType: enum che indica la tipologia di utente cui fa riferimento il token. I valori possibili sono:
    • P: utenza personale
    • T: utenza tecnica
    • A: utenza applicativa
  • exp: data di scadenza del token, espressa come unix timestamp (secondi)
  • family_name: cognome dell'utente
  • iat: data di creazione del token, espressa come unix timestamp (secondi)
  • jti: identificativo univoco del token
  • hash: hash del token. Utilizzato dal servizio di autenticazione e autorizzazione per assicurare che il token non sia contraffatto.

Il token JWT può essere generato, una volta recuperato il nonce, utilizzando la seguente API:

[POST] /api/v3/tokens

Headers

Sono richiesti gli header standard di TS Digital, con l'eccezione dell'header Authorization.

Body

{
  "id": "string",
  "digest": "string",
  "resources": [
    "string"
  ]
}
  • id: identificativo dell'utente all'interno di TS Digital. Per le utenze personali si tratta dell'indirizzo email utilizzato in fase di registrazione, per le utenze tecniche si tratta invece dell'ID fornito al momento della creazione della stessa.
  • digest: digest ottenuto applicando la formula sha256(sha256(userId + password) + nonce), dove:
    • sha256 è una funzione in grado di calcolare il digest SHA-256 di una data stringa
    • userId è l'identificativo dell'utente fornito nel parametro id
    • password è la password dell'utente
    • nonce il nonce recuperato tramite l'apposita API
  • resources: (deprecato) array di risorse per le quali il token deve avere i permessi

Risposte

Tutte le risposte sono in formato JSON

HTTP 200

Il nonce è stato generato con successo

{
  "refreshToken": "string",
  "accessToken": "string",
  "tokenType": "Bearer"
}
  • refreshToken: token utilizzabile per ottenere un nuovo accessToken. Da utilizzare al posto del parametro digest in questa stessa chiamata
  • accessToken: token d'autenticazione. Utilizzabile come valore per l'header Authorization in ogni servizio di TS Digital
  • tokenType: tipologia di token ritornato. Unico valore possibile: Bearer

HTTP 400

Parametro obbligatorio mancante nella richiesta

{
  "code": "string",
  "status": "string",
  "error": "string",
  "message": "string",
  "timestamp": "string"
}

HTTP 401

Il digest fornito è errato

{
  "code": "string",
  "status": "string",
  "error": "string",
  "message": "string",
  "timestamp": "string"
}

HTTP 404

Non esiste alcun utente con l'ID specificato

{
  "code": "string",
  "status": "string",
  "error": "string",
  "message": "string",
  "timestamp": "string"
}

HTTP 500

Si è verificato un errore interno del server nella generazione del token

{
  "code": "string",
  "status": "string",
  "error": "string",
  "message": "string",
  "timestamp": "string"
}
Back to top