# 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)](https://dts-identity.com/it/docs/quickstarts/oidc-authorization-code.md) | Il protocollo in sé, con HTTP puro e curl. Va letta per prima; le altre si basano su di essa. |
| [Backend Node / Express](https://dts-identity.com/it/docs/quickstarts/node-express.md) | Un'applicazione web renderizzata dal server o basata su API, in Node.js. |
| [Backend Python / Flask](https://dts-identity.com/it/docs/quickstarts/python-flask.md) | Un'applicazione web renderizzata dal server, in Python. |
| [Applicazione single-page React](https://dts-identity.com/it/docs/quickstarts/react-spa.md) | Un'applicazione browser priva di backend proprio. |
| [Client Financial-grade API (FAPI 2.0)](https://dts-identity.com/it/docs/quickstarts/fapi-2.md) | Un'applicazione con profilo di sicurezza FAPI 2.0: private key JWT, pushed authorization request, DPoP. |
| [Proteggere un'API](https://dts-identity.com/it/docs/quickstarts/protect-an-api.md) | 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](https://dts-identity.com/it/docs/integrations/apis.md#call-the-management-api-machine-to-machine-quickstart).

## Prima di iniziare [#before-you-start]

1. **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](https://dts-identity.com/it/docs/integrations/applications.md#choosing-an-oidc-type-by-deployment-shape).
2. **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.
3. **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.
4. **Conoscere i propri endpoint.** Tutto ciò che segue è reperibile nel documento di configurazione OpenID della propria istanza:

   ```
   https://<your-domain>/.well-known/openid-configuration
   ```

   Sostituire `<your-domain>` con il dominio di accesso della propria istanza (il proprio [dominio personalizzato](https://dts-identity.com/it/docs/branding/custom-domains.md), se presente, altrimenti l'host della piattaforma). Questo documento elenca `authorization_endpoint`, `token_endpoint`, `userinfo_endpoint`, `jwks_uri` e `end_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.
