Registrazione di applicazioni OpenID Connect
Una registrazione di applicazione OpenID Connect in FoxIDs consente a un’applicazione web, single-page o nativa di autenticare gli utenti tramite FoxIDs e ricevere ID token e access token. L’applicazione è il Relying Party (RP) e FoxIDs è l’OpenID Provider (OP).
Le principali funzionalità OpenID Connect includono discovery, Authorization Code Flow, PKCE, secret e chiavi client, l’endpoint UserInfo, il logout avviato dall’RP e il front-channel logout.
Configurazione
In FoxIDs Control:
- Seleziona l’ambiente in cui registrare l’applicazione.
- Apri Applications e fai clic su Add application.
- Scegli Web Application, Single Page Application o Native Application. Queste tre opzioni OpenID Connect sono visibili senza attivare Show all options.
- Inserisci un nome e un URI di reindirizzamento, verifica le informazioni generate e fai clic su Create.
- Copia l’eventuale secret generato prima di chiudere il risultato della creazione. Un secret generato viene mostrato solo durante la creazione.
Dopo la creazione, fai clic su Change application per verificare o modificare tutte le impostazioni dell’applicazione. La scheda del tipo di applicazione fornisce una configurazione iniziale adeguata; il client OpenID Connect risultante può essere successivamente personalizzato.
Applicazione web (client riservato)
Scegli Web Application per un’applicazione eseguita su un server, ad esempio un’applicazione ASP.NET Core, Node.js, Java o PHP. Viene creata come client riservato con:
- Authorization Code Flow con response type
code. - Un client secret generato.
- PKCE disattivato per impostazione predefinita. Dopo la creazione, attiva Require PKCE quando l’applicazione supporta PKCE. È consigliato come protezione aggiuntiva del codice di autorizzazione.
Inserisci l’URL di base o di callback dell’applicazione come Redirect URI. Durante la creazione attiva Show advanced solo se devi scegliere il client ID o configurare la corrispondenza esatta dell’URL di reindirizzamento.
Applicazione single-page (client pubblico)
Scegli Single Page Application per un’applicazione eseguita nel browser, ad esempio React, Angular, Vue o Blazor WebAssembly. Viene creata come client pubblico con:
- Authorization Code Flow con response type
code. - PKCE attivato per impostazione predefinita.
- Nessun client secret.
- L’origine dell’URL di reindirizzamento aggiunta come origine CORS consentita.
Applicazione nativa (client pubblico)
Scegli Native Application per un’applicazione mobile o desktop installata, ad esempio iOS, Android, React Native, .NET MAUI o Ionic. Viene creata come client pubblico con Authorization Code Flow, PKCE attivato per impostazione predefinita e nessun client secret.
L’URI di reindirizzamento può usare uno schema specifico dell’applicazione, come myapp://callback, oppure un URI HTTPS supportato dall’applicazione.
URI di reindirizzamento e valori assoluti
Per impostazione predefinita, Absolute URIs è disattivato per le applicazioni web e single-page. L’URL di reindirizzamento configurato viene quindi considerato un valore di base e vengono accettati gli URL di reindirizzamento che iniziano con tale valore.
Attiva Show advanced e Absolute URIs se conosci l’URL esatto dell’applicazione a cui reindirizzare l’utente dopo il login. Inserisci tale URL esatto come Redirect URI. La stessa impostazione supporta URI esatti specifici per le applicazioni native.
Dopo la creazione, gli URI di reindirizzamento, l’URI di reindirizzamento post-logout e le origini CORS consentite possono essere modificati nella scheda OpenID Connect Client. Mantieni Show advanced disattivato a meno che l’impostazione necessaria non sia avanzata.
Implicit Flow
Implicit Flow viene mantenuto per compatibilità, ma non è consigliato per le nuove applicazioni. Preferisci Authorization Code Flow con PKCE.
Per configurare un client pubblico esistente per Implicit Flow, fai clic su Change application, attiva Show advanced, modifica Response types in token id_token o facoltativamente solo token e disattiva Require PKCE. I response types possono essere modificati nelle stesse impostazioni avanzate del client quando è necessaria un’altra combinazione supportata.
Endpoint dell’applicazione e sicurezza del client
Le informazioni dell’applicazione in FoxIDs Control includono authority, client ID, endpoint discovery, endpoint authorize ed endpoint token. Un documento discovery OpenID Connect ha questa forma:
https://foxids.com/tenant-x/environment-y/application-client1(*)/.well-known/openid-configuration
Un’applicazione può consentire il login tramite più metodi di autenticazione. Se un metodo di autenticazione definisce profili, il metodo di base e ogni profilo possono essere selezionati in modo indipendente. Per selezionare un metodo di autenticazione nell’URL dell’authority, aggiungine il nome al segmento dell’applicazione:
https://foxids.com/tenant-x/environment-y/application-client1(login)/.well-known/openid-configuration
Durante il logout avviato dall’RP, il nome del metodo di autenticazione può essere omesso quando l’ID token è incluso nella richiesta.
Issuer specifico dell’applicazione
Per impostazione predefinita, i token emessi per l’applicazione usano l’issuer dell’ambiente:
https://foxids.com/tenant-x/environment-y/
Per fare in modo che l’issuer corrisponda all’authority dell’applicazione, fai clic su Change application, attiva Show advanced e abilita Use matching issuer and authority with application specific issuer. L’issuer diventa:
https://foxids.com/tenant-x/environment-y/application-client1(*)
L’issuer specifico dell’applicazione cambia quando cambiano i metodi di autenticazione selezionati nell’URL dell’authority. Per le API, l’issuer dipende quindi dall’applicazione chiamante. Token exchange è possibile solo tra configurazioni con metodi di autenticazione corrispondenti.
Sicurezza del client
I client pubblici, incluse le applicazioni single-page e native, non possono conservare in modo sicuro le credenziali client. Configurali senza client secret e usa Authorization Code Flow con PKCE.
I client riservati si autenticano presso l’endpoint token. Il metodo di autenticazione client predefinito è client secret post. Attiva Show advanced per modificarlo in client secret basic o private key JWT. PKCE è consigliato anche quando il client riservato lo supporta. Se sono configurati sia PKCE sia un client secret o una chiave, FoxIDs li convalida entrambi.
Il metodo di autenticazione client none è supportato con PKCE. È possibile configurare fino a 10 secret e 4 chiavi per un client. Conserva in modo sicuro i client secret e le chiavi private e ruotali quando necessario.
FoxIDs stabilisce una sessione quando l’utente si autentica e include il relativo ID sessione nell’ID token. La sessione viene invalidata al logout. In base alla configurazione del client e alla presenza di un ID token nella richiesta di logout, FoxIDs può mostrare una finestra di conferma del logout.
Client e API
Una registrazione di applicazione OpenID Connect può contenere sia il client sia la relativa risorsa OAuth 2.0. Il client ID è quindi anche il nome della risorsa API.
L’esempio seguente configura oidc-web-app sia come client OpenID Connect sia come API:
- Fai clic su Change application e attiva Show advanced.
- Modifica il tipo di registrazione in OpenID Connect Client and OAuth 2.0 Resource.
- Nella scheda OpenID Connect Client, mantieni selezionato Default resource 'oidc-web-app' for the application itself.
- Aggiungi gli scope
readewritesotto la risorsa predefinita.
Nella scheda OAuth 2.0 Resource, definisci gli stessi scope read e write esposti dall’API.
Risorsa e scope
Un’API può invece essere registrata separatamente come risorsa OAuth 2.0. In questo esempio, il client oidc-web-app chiama una Orders API separata con nome risorsa orders-api.
Nella scheda OpenID Connect Client del client:
- Deseleziona Default resource 'oidc-web-app' for the application itself, perché questo client non agisce come propria API.
- Aggiungi la risorsa
orders-api. - Aggiungi gli scope
readewritesotto tale risorsa.
I valori completi degli scope richiesti dal client sono orders-api:read e orders-api:write.
Nella registrazione della Orders API, definisci read e write nella scheda OAuth 2.0 Resource.
Gli scope richiesti da un client vengono convalidati rispetto agli scope configurati nell’API. Se il client e l’API si trovano nella stessa registrazione, gli scope aggiunti sotto la risorsa predefinita del client vengono aggiunti automaticamente alla risorsa.
Per impostazione predefinita, il client ID è l’audience sia dell’ID token sia dell’access token. Gli scope di risorsa configurati aggiungono le audience API all’access token e un access token può essere destinato a più risorse API.
Scope e claim
Gli scope OpenID Connect vengono configurati nella scheda OpenID Connect Client. Gli scope predefiniti offline_access, profile, email, address e phone possono essere modificati o rimossi. Per ogni scope, Voluntary claims controlla quali claim vengono emessi quando il client richiede tale scope.
Attiva Show advanced per configurare Issue claims. Aggiungi un claim specifico oppure * per emettere tutti i claim disponibili nell’access token. Mantieni Include in ID token disattivato per *; altrimenti ogni claim disponibile viene copiato nell’ID token, rendendolo potenzialmente troppo grande e causando problemi nei flow in cui l’ID token viene inviato durante il logout.
In alternativa, aggiungi un claim a Voluntary claims di uno scope e richiedi tale scope dall’applicazione. I singoli claim possono essere inclusi nell’ID token quando l’applicazione ne ha bisogno. I claim possono inoltre essere modificati con trasformazioni e attività sui claim.
Durata dei token
Fai clic su Change application e attiva Show advanced per configurare la durata del codice di autorizzazione, dell’ID token, dell’access token e del refresh token.
In questo esempio, ogni refresh token è valido per 36.000 secondi. L’applicazione può continuare ad aggiornare la sessione fino al raggiungimento della durata assoluta del refresh token di 86.400 secondi.
Richiedere l’autenticazione multifattore (MFA)
Un client OpenID Connect può richiedere MFA includendo urn:foxids:mfa nel parametro acr_values. Può essere combinato con valori più specifici, come urn:foxids:link. Vedi richiedere MFA dalle applicazioni.
Il parametro acr_values può essere impostato nell’evento OnRedirectToIdentityProvider in Startup.cs:
options.Events.OnRedirectToIdentityProvider = (context) =>
{
context.ProtocolMessage.AcrValues = "urn:foxids:mfa";
return Task.FromResult(string.Empty);
};
Vedi AspNetCoreOidcAuthorizationCodeSample e la relativa configurazione Startup.cs.
Guide pratiche
- Connettere Tailscale