Quickstarts
Collegare la propria applicazione per l'accesso tramite OpenID Connect, con guide da copiare e incollare per il flusso generico, Node, Python e React.
Queste guide portano un'applicazione ad autenticare gli utenti tramite la piattaforma con OpenID Connect (OIDC). Conviene iniziare dal flusso generico per comprendere gli elementi in gioco e passare poi alla guida corrispondente al proprio stack.
| Guida | A che cosa serve |
|---|---|
| OpenID Connect (Authorization Code + PKCE) | Il protocollo in sé, con HTTP puro e curl. Va letta per prima; le altre si basano su di essa. |
| Backend Node / Express | Un'applicazione web renderizzata dal server o basata su API, in Node.js. |
| Backend Python / Flask | Un'applicazione web renderizzata dal server, in Python. |
| Applicazione single-page React | Un'applicazione browser priva di backend proprio. |
| Client Financial-grade API (FAPI 2.0) | Un'applicazione con profilo di sicurezza FAPI 2.0: private key JWT, pushed authorization request, DPoP. |
| Proteggere un'API | L'altro lato: validare gli access token della piattaforma nella propria API e applicare gli scope. |
Per chiamare la REST API di gestione della piattaforma da un servizio backend (non per l'accesso degli utenti), utilizzare invece il quickstart machine-to-machine in API.
Prima di iniziare
-
Registrare la propria applicazione. Nella Admin Console, aggiungere un'applicazione e scegliere il tipo OIDC corrispondente al proprio deployment: un client confidential per tutto ciò che dispone di un backend in grado di custodire un secret (Node/Express, Python/Flask), oppure un client public per un'applicazione single-page o nativa che non può farlo. Vedere Applicazioni.
-
Annotare le credenziali. Un client confidential ha un client ID e un client secret; un client public ha soltanto un client ID e si affida a PKCE. Il secret va custodito sul server, mai nel codice del browser.
-
Aggiungere il proprio redirect URI. Registrare l'URL esatto a cui la piattaforma riporta l'utente dopo l'accesso (per esempio
https://app.example.com/callback). I redirect URI vengono confrontati carattere per carattere: schema, host, porta, percorso e barra finale devono essere identici; i wildcard non sono supportati. -
Conoscere i propri endpoint. Tutto ciò che segue è reperibile nel documento di configurazione OpenID della propria istanza:
https://<your-domain>/.well-known/openid-configurationSostituire
<your-domain>con il dominio di accesso della propria istanza (il proprio dominio personalizzato, se presente, altrimenti l'host della piattaforma). Questo documento elencaauthorization_endpoint,token_endpoint,userinfo_endpoint,jwks_urieend_session_endpoint. Il documento di discovery va considerato la fonte autorevole: conviene lasciarlo leggere alla propria libreria anziché fissare i percorsi nel codice.
Gli endpoint in sintesi
A titolo di orientamento, questi sono i percorsi standard:
| Scopo | Percorso |
|---|---|
| Discovery | /.well-known/openid-configuration |
| Autorizzazione | /authorize |
| Token | /oauth/token |
| UserInfo | /userinfo |
| Chiavi di firma (JWKS) | /.well-known/jwks |
| Disconnessione (end session) | /logout |
PKCE è obbligatorio per i client public e per le applicazioni con un profilo di sicurezza Financial-grade API, e S256 è l'unico metodo di challenge accettato. Utilizzare sempre Authorization Code con PKCE; il flusso implicit è sconsigliato.