Documentazione

Consulta la documentazione generale sull'integrazione con le nostre applicazioni e le pagine specifiche relative alle API.

Autenticazione OAuth 2.0 e OpenID Connect

Datev Koinos ha implementato gli standard web OAuth 2.0 e OpenID Connect per la comunicazione con il data center DATEV. OAuth 2.0 fornisce un codice o un token di accesso per l'autorizzazione, OpenID Connect consente al client di identificare l'utente in base all'autenticazione eseguita dal server di autorizzazione. OpenID Connect opera quindi a monte rispetto al protocollo OAuth 2.0 e lo estende:

OAuth 2.0: per l'autorizzazione: è il processo per verificare se l'entità che comunica ha accesso alla risorsa
OpenID Connect: per l'autenticazione: è la garanzia che l'entità che comunica è quella rivendicata

Il flusso di informazioni avviene generalmente come segue:

l'utente avvia il flusso di autorizzazione a partire dall'applicazione o servizio client facendo clic su un pulsante di accesso
il client invia la richiesta al server di autorizzazione (https://login.datev.it) includendo il proprio identificativo client o client_id e l'URI di reindirizzamento
il server di autorizzazione gestisce l'autenticazione dell'utente
se l'autenticazione va a buon fine, il server di autorizzazione restituisce al client la chiave di autorizzazione (codice o token)
il client, utilizzando la chiave di autorizzazione, può a questo punto richiedere al server contenente le risorse le informazioni relative all'utente
il server delle risorse convalida la chiave di autorizzazione e restituisce i dati richiesti al client

La richiesta di concessione dell'autorizzazione viene inviata unitamente ad alcuni dati di configurazione come parametri di query:

response_type: il tipo di risposta che si desidera ottenere dal server di autorizzazione
scope: elenco degli ambiti relativi all'utente a cui il client desidera accedere
client_id: identificativo fornito dal servizio di autorizzazione durante la configurazione del client per l'OAuth
redirect_uri: indirizzo a cui puntare quando il flusso OAuth è stato completato
client_secret: parametro opzionale fornito dal servizio di autorizzazione

L'indirizzo del server di autenticazione è

https://login.datev.it

Gli scope(s), o ambiti, in OAuth 2.0 vengono utilizzati per limitare l'accesso di un'applicazione ai dati di un utente, infatti l'autorizzazione viene concessa limitatamente solo agli ambiti concessi dall'utente. Quando il client effettua una richiesta al server delle autorizzazioni per la concessione dell'autorizzazione, invia un elenco di ambiti e il server di autorizzazione emette un token o un codice di autorizzazione limitato solo agli ambiti concessi. Per maggiori informazioni consultare la pagina Scope(s).

Endpoint di autorizzazione

L'endpoint di autorizzazione /connect/authorize può essere utilizzato per richiedere token o codici di autorizzazione tramite il browser. Questo processo in genere comporta l'autenticazione dell'utente finale e, facoltativamente, il consenso.

Nota: Il server di autenticazione Datev Koinos supporta un sottoinsieme dei parametri di richiesta di autorizzazione OpenID Connect e OAuth 2.0. Per un elenco completo, vedere qui.

client_id

identificativo del client (obbligatorio).

request

invece di fornire tutti i parametri come singoli parametri della query string, è possibile fornire un sottoinsieme o tutti come un JWT

request_uri

URL di un JWT preconfezionato contenente i parametri della richiesta

scope

uno o più scope registrati per quel client (obbligatorio)

redirect_uri

deve corrispondere esattamente a uno degli URI di reindirizzamento consentiti per quel client (obbligatorio)

response_type

id_token richiede un token di identità (sono consentiti solo ambiti di identità)

token richiede un token di accesso (sono consentiti solo gli ambiti delle risorse)

id_token token richiede un token di identità e un token di accesso

code richiede un codice di autorizzazione

code id_token richiede un codice di autorizzazione e un token di identità

code id_token token richiede un codice di autorizzazione, un token di identità e un token di accesso

response_mode

form_post invia la risposta del token come un POST del form invece di un reindirizzamento codificato frammento (opzionale)

state

il server di autorizzazione restituirà il valore di state nella risposta del token, questo serve per correlare la richiesta e il token di protezione e evitare attacchi ti tipo CSRF/replay attack (consigliato)

nonce

il server di autorizzazione restituirà il valore nonce nel token di risposta per proteggere dagli attacchi replay attack

Obbligatorio per le richieste di token via implicit grant.

prompt

none nessuna UI verrà mostrata durante la richiesta. Se ciò non è possibile (ad es. perché l'utente deve accedere o acconsentire) viene restituito un errore

login verrà mostrata l'interfaccia utente di accesso, anche se l'utente ha già effettuato l'accesso e ha una sessione valida

code_challenge

codice random da includere un una richiesta di autenticazione di tipo code per PKCE

code_challenge_method

plain indica che il valore in code_challenge è in chiaro (non consigliato) S256 indica che il valore è codificato in SHA256

login_hint

può essere utilizzato per precompilare il campo del nome utente nella pagina di accesso

ui_locales

fornisce un suggerimento sulla lingua di visualizzazione desiderata dell'interfaccia utente di accesso

max_age

se la sessione di accesso dell'utente supera l'età massima (in secondi), verrà visualizzata l'interfaccia utente di accesso

acr_values

consente il passaggio di ulteriori informazioni relative all'autenticazione - i seguenti valori per acr_values sono riservati:

idp:name_of_idp ignora la schermata di principale e ridirige la richiesta di autenticazione dell'utente direttamente al provider di identità selezionato (non attivo nell'attuale versione)

tenant:id_of_tenant utilizzato per selezionare l'area web corrente nel caso in cui l'utente abbia accesso a più aree

Esempio

GET https://login.datev.it/connect/authorize?
    client_id=client1&
    scope=openid email efat&
    response_type=code&
    redirect_uri=https://myapp/callback&
    code_challenge=BBDm9y2IPeWwLz....3ZSfOq63Aysm2BKD6P&
    code_challenge_method=S256&
    state=abc&
    nonce=xyz

Sono stati rimossi gli URL encoding e aggiunte le interruzioni di riga per migliorare la leggibilità.

Endpoint del token

L'endpoint del token /connect/token può essere utilizzato per richiedere i token a livello di codice.

Supporta le richieste con i grant di accesso di tipo password, authorization_code, client_credentials, refresh_token e urn:ietf:params:oauth:grant-type:device_code.

Nota: Il server di autenticazione Datev Koinos supporta un sottoinsieme dei parametri per la richiesta di token previsti da OpenID Connect e OAuth 2.0. Per un elenco completo, vedere qui.

client_id: identificativo del client (obbligatorio – può essere passato come campo nel corpo oppure come parametro dell'intestazione HTTP)
client_secret: chiave segreta del client può essere passata nel corpo della richiesta, oppure nell'intestazione come basic autentication header. Opzionale.
grant_type: authorization_code, client_credentials, password, refresh_token, urn:ietf:params:oauth:grant-type:device_code or custom
scope: uno o più scope registrati. Se non specificato, verrà emesso un token per tutti gli scope esplicitamente consentiti.
redirect_uri: obbligatorio per il grant di tipo authorization_code
code: il codice di autorizzazione (obbligatorio per il tipo di autorizzazione authorization_code)
code_verifier: codice di controllo (PKCE) per lo scambio dei codici di autorizzazione (obbligatorio per il tipo di autorizzazione authorization_code)
username: username del proprietario della risorsa (obbligatorio per il tipo di autorizzazione password)
password: password del proprietario della risorsa (obbligatorio per il tipo di autorizzazione password)
acr_values: consente il passaggio di ulteriori informazioni relative all'autenticazione - i seguenti valori per acr_values sono riservati:

idp:name_of_idp ignora la schermata di principale e ridirige la richiesta di autenticazione dell'utente direttamente al provider di identità selezionato (non attivo nell'attuale versione)

tenant:id_of_tenant utilizzato per selezionare l'area web corrente nel caso in cui l'utente abbia accesso a più aree
refresh_token: il token di aggiornamento dell'autorizzazione (obligatorio per il tipo di autorizzazione refresh_token)
device_code: il codice del dispositivo (richiesto per il tipo di autenticazione urn:ietf:params:oauth:grant-type:device_code)

Esempio

POST https://login.datev.it/connect/token
    CONTENT-TYPE application/x-www-form-urlencoded


    client_id=client1&
    client_secret=secret&
    grant_type=authorization_code&
    code=jQ2NjkwOTc...zMyOTFkYTg0ZTc5N2U1ZWI5YjNmZTJhOQ&
    code_verifier=7lJjKoO...712DKT5q4U&
    redirect_uri=https://myapp/callback&

Sono stati rimossi gli URL encoding e aggiunte le interruzioni di riga per migliorare la leggibilità.

Endpoint UserInfo

L'endpoint UserInfo può essere utilizzato per ottenere informazioni relative ad una identità utente (vedi specifiche).

Il chiamante deve inviare un token di accesso valido che rappresenti l'utente. A seconda degli scope concessi, l'endpoint UserInfo restituirà le attestazioni mappate (nella richiesta di autenticazione deve essere stato richiesto almeno lo scope openid).

Esempio

GET /connect/userinfo
Authorization: Bearer <access_token>

HTTP/1.1 200 OK
Content-Type: application/json

{
    "sub": "248289761001",
    "name": "Mario Rossi",
    "given_name": "Mario",
    "family_name": "Rossi",
    "role": [
        "user",
        "admin"
    ]
}