Autenticazione

Le API di Docebo utilizzano il framework OAuth 2.0 nella maggior parte degli scenari coinvolgendo servizi di terze parti, inclusi autenticazione e autorizzazione per server web, e applicazioni installate e client-side. Le credenziali dell'app OAuth 2.0 possono essere ottenute nella pagina delle impostazioni API e SSO di Docebo. Per ulteriori informazioni, consultare l'articolo Attivare e gestire l'app API e SSO.

L'applicazione client richiederà un token di accesso dal LMS, lo estrarrà dalla risposta e lo invierà a ciascuna API REST a cui si desidera accedere.

Attivare e configurare l'app API e SSO di Docebo

Prima di tutto, è necessario attivare e configurare l'app API & SSO nella piattaforma Docebo. Per ulteriori informazioni su come configurare correttamente l'app e ottenere le proprie credenziali OAuth 2.0, consultare l'articolo Attivare e gestire l'app API e SSO.

Ottenere un token di accesso

Per poter accedere ai dati privati della piattaforma Docebo Learn tramite un'API Docebo, l'applicazione deve prima ottenere un token di accesso che consenta l'accesso alla risorsa REST interessata. Un singolo token di accesso può accedere a più API. Il parametro scope controlla l'insieme di risorse e operazioni che un token di accesso consente.

Per ottenere un token di accesso, è necessario effettuare una chiamata a questo endpoint. Si preghi di notare che il comportamento delle seguenti chiamate API dipenderà dal livello utente utilizzato per ottenere il token di accesso, in base alle autorizzazioni definite in piattaforma.

https://<sottodominio.docebosaas.com>/oauth2/token

Per informazioni relative al token OAuth2 e ai parametri da includere nelle richieste sottostanti, consultare la documentazione ufficiale OAuth2 (si apre in una nuova scheda).

Utilizzare il tipo di autorizzazione Resource Owner Password Credentials

Il seguente codice offre un esempio di chiamata con il tipo di autorizzazione impostato su Resource Owner Password Credentials (credenziali della password del proprietario della risorsa):

curl -X POST https://<sottodominio.docebosaas.com>/oauth2/token \
  -F client_id=<client_id> \
  -F client_secret=<client_secret> \
  -F grant_type=password \
  -F scope=api \
  -F username=<nome> \
  -F password=<password>

Risposta:

{
  "access_token": "87b567fa3de847fb3adef9492b294bb83f8cd266",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "api",
  "refresh_token":"7db6e6a331223fa0473cfcdf62eb8fec26407a5b"
}

Utilizzare il tipo di autorizzazione Client Credentials

Ecco un esempio di chiamata con il tipo di autorizzazione impostato su Client Credentials (credenziali del client):

curl -X POST https://<sottodominio.docebosaas.com>/oauth2/token \
  -F client_id=My-Client-Name \
  -F client_secret=ed8c18b099c1f9b8714aaef87001fa3de3a7183d \
  -F grant_type=client_credentials \
  -F scope=api

Risposta:

{
  "access_token": "87b567fa3de847fb3adef9492b294bb83f8cd266",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "api"
}

Attenzione! Con le nuove API 7.0, disponibili su https://LMS.docebosaas.com/api-browser/, il sistema richiede un'autorizzazione utente specifica per funzionare correttamente. Per questo motivo, non sarà possibile utilizzare le credenziali del client per chiamare questo tipo di API.

Utilizzare il tipo di autorizzazione Authorization Code + Implicit

Se l'applicazione utilizza il tipo di autorizzazione Authorization Code, avviare il flusso di autorizzazione con il seguente URL:

https://<sottodominio.docebosaas.com>/oauth2/authorize

Utilizzare il tipo di autorizzazione JWT Bearer

I JSON Web Token sono un metodo aperto e standard (RFC 7519) per trasmettere informazioni (attestazioni) in modo sicuro tra due parti. Per ulteriori informazioni, consultare la documentazione sulla norma RFC-7519 (si apre in una nuova scheda). È possibile utilizzare la tecnologia JWT per ottenere un token consentendo l'accesso alle API di Docebo.

Si può generare un token JWT con il metodo preferito. Alcuni esempi, così come librerie per molti linguaggi di programmazione, sono disponibili sul sito jwt.io (si apre in una nuova scheda).

Per creare un JSON WEB Token che possa essere utilizzato per l'autenticazione all'interno di Docebo, impostare l'algoritmo di firma su RS256 e caricare la chiave pubblica nell'app API e SSO in piattaforma dopo aver selezionato il tipo di autorizzazione JTW Bearer. Il seguente codice offre un esempio di chiave pubblica:

-----BEGIN PUBLIC KEY-----
MIGeMA0GCSqGSIb3DQEBAQUAA4GMADCBiAKBgGOrtjv/oPcaWIQL7h3DwvGbWFhH
fAIP02pPPw1Cp8h0SUkmGAWUGKCNH2WuIeNxPlRZKmW86aivknrRtEN3QW6eEsFZ
ZSIKVmUPekKrSpvYmYwkTCnwCb4gpDu1ZPEde8VXhQjLRl7ielUktzzbXW7v1HmI
fDASHvMvIl4kwGA/AgMBAAE=
-----END PUBLIC KEY-----

Per consentire al LMS di autenticare l'utente, sono necessarie le seguenti informazioni:

iss (attestazione dell'emittente)

Deve contenere il client ID configurato in piattaforma Docebo per il SSO.

sub (attestazione del soggetto)

Deve contenere il nome utente che si desidera utilizzare per accedere alla piattaforma Docebo.

aud (attestazione del pubblico)

Deve contenere lo hostname della piattaforma Docebo (senza protocollo) in cui si desidera autenticare.

iat (attestazione di emissione)

Deve contenere la data di creazione del token con data e ora nel formato Unix.

exp (attestazione di scadenza)

Deve contenere la data di scadenza con data e ora nel formato Unix.

Il payload del token, quindi, apparirà così:

{
  "alg": "RS256",
  "typ": "JWT"
}
{
  "iss": "<client_id>",
  "sub": "<username_docebo>",
  "aud": "<sottodominio.docebosaas.com>",
  "iat": "1510649850",
  "exp": "2554329600"
}

Una volta che si firma il token con la chiave privata, si otterrà un token JWT codificato e pronto per essere inviato per l'autenticazione. Il seguente riquadro offre un esempio di token JWT codificato:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJjbGllbnRfaWRfaGVyZSIsInN1YiI6
InVzZXJuYW1lX2hlcmUiLCJhdWQiOiJ5b3VybG1zLmRvY2Vib3NhYXMuY29tIiwiaWF0IjoiMTUxM
DY0OTg1MCIsImV4cCI6IjI1NTQzMjk2MDAifQ.mrA_k6OClsczj9kEz_jeGZxlusCmzOJWLyDGEp5
A3BttCBna9aKP2_AqCaiwhntjrQ9L6NBEH9oxHr4pM2G9tyeSEGxD0VLVe3CoDljzMgvMdyyK8HP4
0QtALCYEuVF2BIpS8Mz2KhvysKhzVJR71suwaAYnR0I7G8_kAlUR9Ck

Quindi, si potrà inviare i dati all'endpoint di autenticazione. Il seguente riquadro offre un esempio di chiamata con il tipo di autorizzazione impostato su JWT Bearer:

curl -X POST
https://<sottodominio.docebosaas.com>/oauth2/token \
-F grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
-F scope=api \
-F assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJEb2NlYm9PRU0iLCJ\
  zdWIiOiJyaWNjYXJkby5nYWxpbWJlcnRpQGRvY2Viby5jb20iLCJhdWQiOiJyZ2FsaW1iZXJ0aS\
  5kb2NlYm9zYWFzLmNvbSIsImlhdCI6IjE1MTA2NDk4NTAiLCJleHAiOiIyNTU0MzI5NjAwIn0.n\
  0Sr0Cy3wjE7C-TqJLTi1JfZjnWnXcKoCidCtz4o8HsaHI0LomM5Ln3gWOqJXq5EI67yDr9L_EwA\
  44-_lFKVjV8FAmUU72ZU6indDXP7SaCMEmqQu5tbo9AnW_RKHGoAXPWspH95iZe_VaM0SFjmHbo\
  ZXGgPmEt3aNfhaJBBzIcLuk1EIcGZEqtN4ENVp_MREtCMrFg3yMyx47dcf0rmBvizkmthTW1so8\
  TG7OXgTfNR0tzPNAOPGbRqciSgfcBNb_ftalW0gE3unAnXpfqMD-8gcUq-c43DfTOiCeNm-ZBLm\
  rVoKeUXshyDjf0JOrP8kReIQ9mWIyI0-gvh5-UMVQ

Risposta:

{
  "access_token": "87b567fa3de672fb3adef9492b294bb83f8cd266",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "api"
}

Inviare il token per l'accesso a un'API

Dopo aver ottenuto un token di accesso, l'applicazione deve fornirlo a ogni chiamata delle API di Docebo nell'intestazione di autorizzazione HTTP, con il seguente formato:

Bearer <token_di_accesso>

Esempio:

curl -X GET https://<sottodominio.docebosaas.com>/learn/v1/courses \
  -H 'Authorization: Bearer 2af6ac532cfef197b00f69639aeeef86621d1975'

Aggiornare il token di accesso

Poiché i token hanno una durata limitata di 14 giorni, l'applicazione può ottenerne uno nuovo utilizzando l'endpoint del token se deve accedere a un'API Docebo oltre questa durata. Un token di aggiornamento consente all'applicazione di ottenere nuovi token di accesso.

Assicurarsi di seguire le linee guida delineate nella documentazione ufficiale OAuth2 (si apre in una nuova scheda) riguardo all'utilizzo e alla memorizzazione sicura di un token di aggiornamento.

Inviare il token di accesso per il single sign-on

Dopo aver ottenuto un token di accesso, l'applicazione deve inserire il token in un formato URL specifico per consentire il SSO:

https://<LMS>.docebosaas.com/learn;type=oauth2_response;access_token=<token>;expires_in=4000;token_type=bearer;scope=api

Attenzione! Per utilizzare un dominio personalizzato, si dovrà sostituire LMS.docebosaas.com con l'URL del proprio dominio personalizzato.