SSO sotto Immersivo

• Tipo non definito

Configuration

Questa documentazione descrive come configurare RestFrontage SSO, collegare account Immersive e i percorsi SAML 2.0 e OpenID. È pensata per amministratori Immersive, gestori di federazione identità e integratori di applicazioni client.

1. Comprendere l'SSO nell'immersione

Il Accesso singolo, oppure SSO, consente a un utente di autenticarsi presso un fornitore di identità esterno e poi accedere a un'applicazione Immersive. Il provider di identità, chiamato IdP, gestisce l'accesso e può imporre propri requisiti, come l'autenticazione multifattore.

RestFrontage quindi trova un account Immersive dall'identità esterna, verifica lo stato di quell'account ed emette un token di autenticazione Immersive. I diritti utilizzati dall'applicazione rimangono quelli dell'account, dei suoi gruppi e dei suoi diritti in Immersive.

1.1 I tre elementi da distinguere

Elemento	Ruolo
Identità esterna	Identifica la persona con l'IDP. Deve poter essere riconciliata con un account Immersive.
Account Immersivo	Contiene lo stato dell'account e i suoi diritti sugli oggetti e le funzioni della piattaforma.
Token Immersivo	Viene restituito da RestFrontage dopo l'autenticazione ed è utilizzato per gli scambi successivi con l'API. La durata del Frontage dipende dalla configurazione dell'applicazione.

Il token di accesso IdP, la risposta SAML e il token Immersive sono elementi diversi. L'autenticazione riuscita nell'IdP non è sufficiente per concedere diritti in Immersive.

flowchart TD
    A["Authentification auprès du fournisseur d’identité"] --> B["Identité externe"]
    B --> C{"Compte Immersive correspondant ?"}
    C -->|"Non"| X["Connexion refusée"]
    C -->|"Oui"| D{"Compte activé, non expiré et non verrouillé ?"}
    D -->|"Non"| X
    D -->|"Oui"| E["Émission d’un jeton Immersive"]
    E --> F["Accès selon les droits du compte et de ses groupes"]

1.2 I due corsi disponibili

RestFrontage fornisce due percorsi di autenticazione esterni: SAML e OpenID. Entrambi permettono di trovare un account Immersive esistente, verificarne lo stato e rilasciare un token Immersive. I diritti rimangono dell'account e dei suoi gruppi.

Questi percorsi differiscono per come il cliente e RestFrontage interagiscono con il fornitore di identità:

Fase di connessione	Con SAML	Con OpenID
Avvia autenticazione esterna	Il client chiede a RestFrontage un URL SAML e poi apre la pagina di accesso del fornitore di identità.	Il client si autentica con il fornitore di identità per ottenere un token di accesso esterno.
Trasmetti il risultato a RestFrontage	Il browser passa una risposta XML SAML a RestFrontage.	Il client passa il token di accesso esterno a RestFrontage.
Identifica l'account esterno	RestFrontage legge l'attributo account nella risposta SAML.	RestFrontage chiama tokeninfo e poi userinfo e legge la proprietà di accesso.
Connessione Immersiva Completa	Il client scambia l'ID della richiesta SAML con un token Immersive, dopo la verifica dell'account.	RestFrontage emette un token Immersive dopo aver chiamato il fornitore di identità e verificato l'account.

Quando il provider di identità e l'applicazione client sono compatibili con i percorsi supportati, la connessione avviene configurando RestFrontage, il provider di identità e il client, e poi allegando gli account Immersive. Non è quindi necessario sviluppare una connessione specifica. Tuttavia, può essere necessario un adattamento se gli scambi previsti o i requisiti di sicurezza del deployment non sono coperti dall'implementazione.

1.2.1 Corrispondenza con l'account Immersive

RestFrontage utilizza il nome dell'account ricevuto dal fornitore di identità per cercare un utente Immersive. Questo valore deve corrispondere al Nome del conto esterno, chiamato AssociatedExternalUserAccountName nel modello.

Con SAML, il valore proviene da un attributo nella risposta XML inviato dal fornitore dell'identità. RestFrontage cerca innanzitutto l'attributo nominato cn. Se è assente, cerca l'attributo nominato http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name.

L'amministratore del provider di identità configura gli attributi passati per l'app Immersive. Il nome cn qui designa un attributo della risposta SML: RestFrontage non cercherà questo valore direttamente in una directory. Il campo SAML NameID non viene utilizzato per trovare l'account Immersive.

Con OpenID, il valore deriva dalla proprietà login del documento JSON restituito dal servizio userinfo del fornitore di identità.

Ad esempio, se l'account Immersive ha agent.demo come nome esterno dell'account domestico, l'attributo SAML conservato o la proprietà OpenID login deve contenere agent.demo.

1.2.2 Percorsi definiti in RestFrontage

I seguenti percorsi sono definiti nell'applicazione. Sono relativi all'indirizzo base con cui RestFrontage è pubblicato.

Funzione	Metodo e percorso relativo
Ottieni URL di accesso SAML	OTTIENI /api/Saml/GetSamlUrl
Ricevi risposta di accesso SAML	POSTAZIONE /api/Saml/Login
Ottieni il token Immersive dopo il ritorno SAML	POSTAZIONE /api/Saml/Authenticate
Ottieni URL di logout SAML	OTTIENI /api/Saml/GetSamlLogoutUrl
Ricevi un feedback per l'uscita di logout SAML	RICEVI o PUBBLICA /api/Saml/Logout
Verifica il token esterno con i servizi OpenID	OTTIENI /api/OpenID/CheckToken
Ottieni il Immersive Token dal Token Esterno	POSTAZIONE /api/OpenID/Authenticate

Il controller OpenID non definisce una via per aprire la connessione al fornitore di identità o per effettuare un logout federato. Queste operazioni dipendono dall'integrazione del client con il fornitore di identità.

Il ritorno di logout SAML non revoca esplicitamente i token Immersive nel metodo esaminato. La chiusura della sessione presso il provider di identità e la fine dell'accesso Immersive dovrebbero quindi essere controllate separatamente.

1.2.3 Sezioni di Configurazione del Server

Saml e OpenID sono sezioni della configurazione applicativa RestFrontage, posizionate alla radice del file di configurazione Rest Frontage appsettings.json. I loro valori possono anche essere forniti dalle variabili ambientali dell'hosting.

• La sezione Saml contiene gli indirizzi del provider di identità, l'ID del servizio Immersive e gli URL pubblici che ritornano a RestFrontage.
• La sezione OpenID contiene l'indirizzo base dei servizi tokeninfo e userinfo e l'identificatore dell'applicazione atteso da RestFrontage.

Impostazioni SAML LoginUrl e LogoutUrl indica gli URL pubblici che conducono alle rotte /api/Saml/Login e /api/Saml/Logout. Non creano nuove strade.

1.2.4 Viaggio SAML

Il provider di identità trasmette una risposta SAML attraverso il browser. Il client poi scambia l'identificatore di quella connessione con un token Immersive. Lo schema mostra il percorso quando tutti i passaggi hanno successo.

sequenceDiagram
    participant C as Client et navigateur
    participant R as RestFrontage
    participant I as Fournisseur d’identité

    C->>R: Demander l’URL de connexion SAML
    R-->>C: URL de connexion
    C->>I: Ouvrir la connexion et s’authentifier
    I-->>C: Réponse SAML
    C->>R: Transmettre la réponse SAML
    R->>R: Retrouver le compte externe et mémoriser la demande
    R-->>C: Retour de connexion
    C->>R: Envoyer l’identifiant de demande chiffré
    R->>R: Retrouver la demande et vérifier l’état du compte
    R-->>C: Jeton Immersive et utilisateur

1.2.5 Viaggio OpenID

Il client riceve prima un token di accesso esterno. RestFrontage poi interroga i servizi del fornitore di identità per trovare l'account Immersive. Il diagramma mostra il percorso specifico per questa versione, quando tutti i passaggi hanno successo.

sequenceDiagram
    participant C as Client Immersive
    participant R as RestFrontage
    participant I as Fournisseur d’identité

    C->>I: S’authentifier et obtenir un jeton d’accès
    I-->>C: Jeton d’accès externe
    C->>R: Envoyer le jeton externe chiffré
    R->>I: Appeler tokeninfo
    I-->>R: client_id, access_token et realm
    R->>R: Comparer client_id avec FidAppId
    R->>I: Appeler userinfo avec le jeton retourné
    I-->>R: Identité contenant login
    R->>R: Retrouver le compte Immersive à partir de login
    R->>R: Vérifier l’état du compte
    R-->>C: Jeton Immersive et utilisateur

2. Preparazione della connessione

2.1 Informazioni da raccogliere

Informazioni	Da ottenere da
URL pubblico HTTPS di RestFrontage, incluso qualsiasi prefisso di percorso	Team di Operatori Immersivi.
URL dell'applicazione client e percorso di accesso previsto	Team di Operatori Immersivi.
Ambiente target e accesso alla rete consentiti	Team operativi e di rete.
Identificatore esterno stabile dell'utente pilota	Squadra di identità.
URL e parametri SAML, o accordo sui servizi OpenID	Amministratore dell'IDP.
Driver di account immersivo, gruppi e diritti richiesti	Amministratore immersivo.

Per SAML, il browser deve essere in grado di unirsi all'IdP e poi passare la risposta all'URL pubblico di RestFrontage. Per OpenID, RestFrontage deve anche essere in grado di chiamare direttamente i servizi tokeninfo e userinfo dell'IDP.

Mantieni l'accesso amministrativo operativo durante l'accettazione. Usa un ambiente di validazione e un account pilota prima di generalizzare la connessione.

2.2 Posizione della configurazione

Le sezioni Saml e OpenID vengono caricate quando RestFrontage avvia. Possono essere popolate nei file di configurazione dell'ambiente o dalle variabili dell'ambiente di processo.

I servizi SAML e OpenID mantengono le opzioni ricevute al momento della loro creazione. Riavvia l'istanza di RestFrontage dopo aver cambiato queste opzioni, anche se il fornitore di configurazione sa come ricaricare un file.

Esempi di nomi di variabili ambientali:

Saml__FidUrl
Saml__FidSsoPath
Saml__FidSloPath
Saml__EntityId
Saml__LoginUrl
Saml__LogoutUrl
OpenID__FidUrl
OpenID__FidAppId
OpenID__FidAppSecret

Esempio appsettings.json su queste due sezioni:

  "Saml": {
    "FidUrl": "???",
    "EntityId": "???",
    "LoginUrl": "???/api/Saml/Login",
    "LogoutUrl": "???/api/Saml/Logout"
  },
  "OpenID": {
    "FidUrl": "???",
    "FidAppId": "???",
    "FidAppSecret": "???"
  }

3. Collega utenti esterni

3.1 Configura la scheda utente

1. Apri la scheda del conto in Gestione Utenti di RestFrontage Security.
2. Localizza il blocco Interoperabilità e aperto Gestire l'interoperabilità.
3. Chiedere ora Dominio esterno di origine per descrivere il dominio di origine dell'account.
4. Chiedere ora Nome del conto esterno con il valore esatto atteso dell'IdP.
5. Salva la carta, poi verifica che l'account sia abilitato e che i suoi gruppi e diritti siano corretti.

Campo	Proprietà	Utilizzo nei percorsi esaminati
Dominio esterno di origine	AssociatedExternalUserDomain	Campo disponibile nella carta; non viene utilizzato dalle ricerche di account SAML e OpenID esaminate.
Nome del conto esterno	AssociatedExternalUserAccountName	La chiave di riconciliazione usata per trovare l'utente Immersive.

Esempio di corrispondenza da preparare:

Dati	Esempio
Nome Account Immersivo	operator.driver
Dominio esterno popolato	AZIENDA
Nome account esterno inserito	agent.demo
Valore cn ricevuto in SAML	agent.demo
Valore di accesso ricevuto in OpenID	agent.demo

L'account locale e l'account esterno possono avere nomi diversi. Tuttavia, il valore ricevuto dall'IdP deve corrispondere al campo di allegato esterno. Impostazioni esatte di caso e caratteri: il codice non esegue la normalizzazione comune, e la sensibilità di alcune ricerche SAML dipende anche dal database.

3.2 Condizioni di accesso all'account immersivo

L'account deve già esistere. Non appare alcuna provisioning automatica di utenti o gruppi da attributi SAML o OpenID in questi percorsi.

Il token Immersive viene negato quando l'account viene disattivato, scaduto o bloccato. I controller controllano IsEnabled, ExpirationDate e LockoutUntilUtc, tra le altre cose. Un account scaduto viene disabilitato nel percorso di autenticazione.

I ruoli o i gruppi passati dall'IdP non vengono automaticamente trasformati in diritti Immersive da questi controller. Assegna i diritti all'account o ai suoi gruppi in Immersive e verificali dopo l'accesso.

4. Configura SAML

4.1 Parametri di RestFrontage

Parametro	Ruolo	Esempio immaginario
Saml:FidUrl	La base dell'URL del provider di identità.	https://idp.example.net
Saml:FidSsoPath	Percorso aggiunto a FidUrl per la connessione.	/saml/sso
Saml:FidSloPath	Percorso aggiunto a FidUrl per il logout federato.	/saml/slo
Saml:EntityId	L'identificatore del servizio Immersive è dichiarato all'IdP e inserito in Emittente.	urn:esempio:immersivo:ricetta
Saml:LoginUrl	L'URL pubblico per ricevere la risposta di connessione, o ACS.	https://rest.example.net/api/Saml/Login
Saml:LogoutUrl	Torna URL pubblico.	https://rest.example.net/api/Saml/Logout

Il servizio costruisce le destinazioni tramite la concatenazione diretta di FidUrl e del percorso. Con l'esempio sopra, la destinazione della connessione è https://idp.example.net/saml/sso. Evitare doppie slash, slash mancanti e percorsi che già portano una stringa di query: il servizio si aggiunge da solo? SAMLRequest=.

FidSloPath e LogoutUrl sono per il percorso di logout. Per una connessione che include questo percorso, compilali e testali separatamente dalla connessione.

{
  "Saml": {
    "FidUrl": "https://idp.example.net",
    "FidSsoPath": "/saml/sso",
    "FidSloPath": "/saml/slo",
    "EntityId": "urn:example:immersive:recette",
    "LoginUrl": "https://rest.example.net/api/Saml/Login",
    "LogoutUrl": "https://rest.example.net/api/Saml/Logout"
  }
}

I percorsi /saml/sso e /saml/slo sono espositivi. Sostituiscili con gli indirizzi forniti dall'amministratore IdP. Segnala qualsiasi prefisso pubblico per RestFrontage in LoginUrl e LogoutUrl.

Vedi la presentazione del file di configurazione Rest Frontage

4.2 Dichiarare il servizio all'IDP

1. Dichiarare l'applicazione o il fornitore di servizi Immersive corrispondente nell'ambiente target.
2. Segnala il valore EntityId esattamente come l'identificatore del fornitore di servizi.
3. Dichiara LoginUrl come l'URL ACS che riceve la risposta tramite HTTP POST.
4. Per il logout federato, dichiara il ritorno LogoutUrl e controlla il comportamento previsto dall'IDP.
5. Configura gli attributi necessari per riconciliare l'account e fornisci a un utente pilota il permesso di accedere a questa applicazione.
6. Verifica i requisiti di firma e validazione descritti nel capitolo sui limiti prima di aprire in produzione.

Il servizio emette una AuthnRequest SAML 2.0, compressa con Deflate e poi codificata in Base64 e nell'URL. Specifica un ritorno HTTP POST e una politica NameID in formato transitorio. Quando forceAuthentication è vero, aggiunge ForceAuthn alla richiesta.

Queste caratteristiche devono essere accettate dall'IdP. Il codice in esame non fornisce URL di metadati SAML né un'opzione di certificato di firma in SamlOptions. Pertanto, non basta inventare un parametro MetadataUrl o Certificate per abilitarli.

4.3 Dati attesi in risposta

Dati	Utilizzo
InResponseTo su risposta SAML	Utilizzato come identificatore di richiesta, per trovare il percorso avviato dal cliente.
SessionIndex in AuthnStatement	Necessario per il riconoscimento della risposta alla connessione; mantenuto per l'uscita di connessione.
Attributo CN	Il primo attributo cercava il nome dell'account esterno.
Attributo http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name	Alternativa utilizzata se il CN è assente.

L'abbinamento account si basa su un attributo SAML. La semplice presenza di un NameID, indirizzo email o sottoattributo non sovrascrive cn o l'attributo nome atteso. Se cn è presente, ha la precedenza sull'attributo alternativo.

Configura un valore semplice e unico per questo attributo. Il parser mantiene il primo AttributeValue di ogni attributo; gruppi multipli e attributi non sono un meccanismo per assegnare diritti.

4.4 Percorso di connessione

Un cliente come il Beholder seguirò i seguenti passaggi per stabilire una connessione tramite SSO SAML.

Il client prepara automaticamente due valori per avviare la connessione. requestId è un identificatore generato a ogni tentativo: viene utilizzato per collegare la richiesta SAML al ritorno del fornitore di identità.

Immersivo Beholder genera un GUID e costruisce un identificatore che contiene anche l'indirizzo di ritorno. forceAuthentication è una scelta del cliente: false permette al fornitore di identità di riutilizzare una sessione esistente, secondo la sua politica, mentre true richiede la riautenticazione, anche se una sessione esiste già. Il Beholder usa false di default. Entrambi i valori sono gestiti dal cliente: l'amministratore non è obbligato a recuperare o inserire nulla.

I passaggi sono i seguenti:

1. Il client crea un ID richiesta specifico per il tentativo e chiama GET /api/Saml/GetSamlUrl con requestId e forceAuthentication.
2. RestFrontage restituisce una stringa JSON contenente l'URL di login SAML; questa chiamata non reindirizza direttamente il browser.
3. Il client apre questo URL e l'utente si autentica all'IDP.
4. Dopo l'autenticazione, il fornitore di identità inoltra la risposta SAML dal navigatore, in HTTP POST, all'URL in Saml:LoginUrl. Nel nostro esempio precedente, questo valore è https://rest.example.net/api/Saml/Login : Questo è il punto di ricevimento fornito da RestFrontage per gestire automaticamente l'elaborazione della dichiarazione SAML.
5. RestFrontage recupera i dati attesi e tenta di salvare la richiesta e l'indice della sessione sull'account esterno corrispondente.
6. Il client cripta l'ID della richiesta con il contesto di sicurezza Immersive e lo invia a POST /api/Saml/Authenticate.
7. RestFrontage recupera l'account, ne verifica lo stato e restituisce un AuthenticationToken contenente il token e l'utente Immersive.

Per i client che usano un redirect, il codice sa come interpretare un identificatore contenente una _redirect= destinazione, possibilmente codificata in esadecimale. I launcher in RestFrontage costruiscono questo formato. Usa il client previsto per questa integrazione invece di fabbricare un URL di ritorno arbitrario.

4.5 SAML Logout

Un utente Immersive autenticato può richiedere GET /api/Saml/GetSamlLogoutUrl con un requestId. Il servizio costruisce la richiesta di logout dall'account esterno e dal SessionIndex conservato. L'IdP restituisce quindi la sua risposta a /api/Saml/Logout, che accetta OTTIENI e POSTAZIONE.

L'uscita di logout all'IDP, la cancellazione dei dati client e l'invalidazione dell'accesso Immersive sono operazioni separate. Il ritorno Logout esaminato mostra una pagina o reindirizza; non revoca esplicitamente i token Immersive in questo metodo. Verifica il comportamento completo del client prima di considerare l'uscita di logout efficace su tutti gli accessi.

4.6 Esempio di connessione con Microsoft Entra ID

Questo esempio descrive come preparare un hook SAML 2.0 dai metadati trasmessi dal client. Le credenziali tenant e applicazioni Entra, nome del client, nome host e account utente sono stati sostituiti con segnaposto. Non vengono riprodotti certificati SAML o risposte effettive.

La lettura dei metadati conferma i servizi pubblicati dall'IdP. Non costituisce una validazione della connessione completa da parte di un lettore Immersive.

4.6.1 Leggi i metadati del provider di identità

L'amministratore di Entra fornisce un URL simile:

https://login.microsoftonline.com/11111111-2222-3333-4444-555555555555/federationmetadata/2007-06/federationmetadata.xml?appid=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Il primo identificatore indica il tenant Entra. Il parametro appid indica l'applicazione Entra in questione; non sostituisce l'EntityId SAML scelto per Immersive.

Questo file può contenere più descrizioni di protocollo. Per SAML 2.0, leggi la sezione IDPSSODescriptor, inclusi gli elementi SingleSignOnService, SingleLogoutService e KeyDescriptor utilizzati per la firma.

Dati estratti	Esempio di valore fittizio	Utilizzo
entityID dell'IdP	https://sts.windows.net/11111111-2222-3333-4444-555555555555/	Identifica l'emittente affidabile quando convalidi le asserzioni. Questo valore non dovrebbe sovrascrivere a Saml:EntityId.
SingleSignOnService, HTTP-Redirect	https://login.microsoftonline.com/11111111-2222-3333-4444-555555555555/saml2	La destinazione della richiesta di connessione.
SingleLogoutService, HTTP-Redirect	https://login.microsoftonline.com/11111111-2222-3333-4444-555555555555/saml2	La destinazione della richiesta di logout federata.
Certificato di firma	Certificato pubblico presente in KeyDescriptor	Verifica le firme SAML; programma anche il suo rinnovo.

L'URL dei metadati viene utilizzato per descrivere il fornitore di identità. Non deve essere usato come destinazione di accesso. In questa versione, RestFrontage non carica automaticamente questo file e SamlOptions non espone alcun metadata, certificato o impostazione di emittente affidabile.

4.6.2 Prepara la configurazione RestFrontage

In questo esempio, l'indirizzo del RestFrontage è https://rest.example.net:44348 e l'identificatore SAML concordato per Immersive è urn:example:immersive:client-example:production.

Segnala i valori appropriati nella sezione Saml della configurazione effettivamente caricata dall'ambiente, e poi riavvia RestFrontage dopo aver applicato la configurazione:

{
  "Saml": {
    "FidUrl": "https://login.microsoftonline.com/11111111-2222-3333-4444-555555555555",
    "FidSsoPath": "/saml2",
    "FidSloPath": "/saml2",
    "EntityId": "urn:example:immersive:client-exemple:production",
    "LoginUrl": "https://rest.example.net:44348/api/Saml/Login",
    "LogoutUrl": "https://rest.example.net:44348/api/Saml/Logout"
  }
}

RestFrontage costruisce gli indirizzi dell'IdP concatenando FidUrl con FidSsoPath o FidSloPath. Non aggiungere una barra diagonale finale a FidUrl in questo esempio.

LoginUrl utilizza la route di ritorno integrata di RestFrontage per permettere di elaborare automaticamente la risposta di connessione. LogoutUrl indica il suo ritorno di disconnessione. Tieni lo schema HTTPS, il nome host, la porta e qualsiasi prefisso di distribuzione negli indirizzi completi.

4.6.3 Fai confermare la dichiarazione della domanda su Entra

L'amministratore del cliente deve verificare i seguenti valori nell'applicazione aziendale pertinente:

Parametro Entra	Valore fittizio da registrare
Identificatore / Identificatore (ID Entità)	urn:esempio:immersivo:cliente-esempio:produzione
URL di risposta (ACS)	https://rest.example.net:44348/api/Saml/Login
URL de déconnexion / Logout URL	https://rest.example.net:44348/api/Saml/Logout

L'URL URN e ACS deve corrispondere esattamente alla configurazione di RestFrontage. La pubblicazione dei metadati IdP non dimostra che questi valori siano stati salvati. Il logout deve essere validato separatamente, specialmente per le richieste avviate da Entra.

4.6.4 Imposta l'attributo dell'account e prepara un utente pilota

Per questo esempio, accetta di passare l'accesso Entra, o UPN, dell'utente nel seguente attributo SML:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

Negli attributi e nelle rivendicazioni di Entra, controlla il nome del nome, il http://schemas.xmlsoap.org/ws/2005/05/identity/claims namespace e la sorgente useruserprincipalname. La mappatura effettiva deve essere confermata con il client; non può essere dedotta solo dai metadati.

Nella scheda account driver Immersive, popola AssociatedExternalUserAccountName con lo stesso valore, ad esempio utilisateur@example.net. Se viene inoltre emesso un attributo cn, esso ha la precedenza nell'elaborazione corrente: deve essere assente o contenere il valore atteso per l'account Immersive.

L'account Immersive deve già esistere, essere attivo e avere i diritti necessari. Assegna anche l'utente pilota all'app Entra. L'attuale percorso SAML non crea automaticamente l'account né sincronizza i suoi diritti.

4.6.5 Completa la validazione SAML prima di testare con account live

Configurare gli indirizzi non è sufficiente per mettere in sicurezza la connessione. Nella versione in esame, l'elaborazione estrae attributi XML senza validare crittograficamente la firma, l'emittente affidabile, l'audience, il destinatario, lo stato SAML e le condizioni temporali.

Un adattamento deve supportare questi controlli, il certificato pubblicato dall'IdP e il suo rinnovo. Deve essere verificata anche la correlazione con una richiesta effettivamente aperta e la protezione contro la riproduzione. Non aggiungere parametri di certificato o metadati senza una corrispondente implementazione.

4.6.6 Prova l'intero percorso del client Immersive

Dopo questo adattamento, avvia la connessione SAML dal player o dal launcher Immersive fornito per l'integrazione. Questo prepara requestId e forceAuthentication; l'amministratore non deve costruire questi valori o chiamare manualmente le vie di connessione.

• Controlla l'arrivo nell'autenticazione del correttono Entra e il possibile MFA.
• Controlla il ritorno HTTP POST all'URL di login dichiarato.
• Conferma che l'attributo ricevuto corrisponda all'account driver Immersive.
• Conferma il successo dello scambio finale con /api/Saml/Authenticate e accesso alle funzioni consentite.
• Controlla il rifiuto di un account Immersive sconosciuto o disabilitato.
• Testa separatamente la disconnessione e il destino delle sessioni Immersive e dei token.

Una pagina di ritorno o un redirect LlogedIn=ok non dimostrano il successo dell'intero percorso. Nei launcher Reader e Beholder esaminati, il cookie di tracciamento SSOToken scade dopo 30 secondi: questo ritardo deve essere rivisto per consentire l'autenticazione interattiva, specialmente con MFA.

La sincronizzazione degli account attivi, disattivati o cancellati rimane una necessità separata da specificare con il cliente. Ricevere metadati e abilitare SSO non consente di attivare il provisioning SCIM.

5. Configura il percorso OpenID

5.1 Differenza rispetto a una connessione OIDC standard

OpenID Connect è uno strato di identità costruito su OAuth 2.0. Lo standard definisce l'ID Token e l'endpoint UserInfo, tra le altre cose. Vedi Specifica OpenID Connect Core.

Il controller OpenID di RestFrontage utilizza un percorso particolare: il client ha già ottenuto un token di accesso esterno e RestFrontage interroga i servizi tokeninfo e userinfo. In questo percorso non configura una configurazione .well-known/openid, uno scambio di codici di autorizzazione, una validazione dell'ID del token o un rinnovo del token.

Pertanto, Authority, MetadataAddress, CallbackPath o un URL /signin-oidc non sono parametri della sezione OpenID esaminata. Gli URL di reindirizzamento, gli ambiti e i metodi per ottenere il token devono essere definiti nell'integrazione tra l'applicazione client e l'IdP.

5.2 Parametri di RestFrontage

Parametro	Ruolo efficace
OpenID:FidUrl	L'URL base usato da RestFrontage per chiamare tokeninfo e userinfo. Pianifica un ultimo slash se i servizi sono sotto un path.
OpenID:FidAppId	Identificatore confrontato con il client_id restituito da tokeninfo. Da compilare per l'applicazione autorizzata.
OpenID:FidAppSecret	Un'opzione che esiste nel template, ma non viene utilizzata dalle chiamate del controller esaminato. Non abilita l'autenticazione del client su tokeninfo.

Esempio minimo dei parametri effettivamente utilizzati dal controllore:

{
  "OpenID": {
    "FidUrl": "https://idp.example.net/oauth2/",
    "FidAppId": "immersive-recette"
  }
}

Con questa base, le chiamate sono rivolte a https://idp.example.net/oauth2/tokeninfo e https://idp.example.net/oauth2/userinfo. Senza la barra finale dopo oauth2, risolvere un URL relativo può rimuovere quel segmento e puntare a un'altra posizione.

Se un'altra parte della tua integrazione richiede un segreto, forniscile il meccanismo di hosting secrets. In questo controller, la popolazione di FidAppSecret non cambia il comportamento delle chiamate in uscita. Un requisito per l'autenticazione di base o client_secret su tokeninfo richiede un adattamento dell'integrazione.

5.3 Contratto a token atteso

RestFrontage effettua una chiamata GET relativa a FidUrl:

tokeninfo?access_token=JETON_ACCES_EXTERNE

Il controller non aggiunge un'intestazione di autenticazione a questa chiamata. Si aspetta una risposta JSON con i seguenti campi utilizzati:

{
  "access_token": "JETON_ACCES_RETOURNE_PAR_IDP",
  "client_id": "immersive-recette",
  "realm": "/environnement-exemple"
}

Il valore client_id deve essere FidAppId; questo confronto ignora la casualità. Il token access_token restituito viene quindi usato per chiamare le informazioni utente. Il campo realm funge da parametro per questa seconda query.

Questi campi descrivono il contratto specifico consumato dal codice. Una risposta introspezionale che contiene solo attivo, sub o scope non è sufficiente a popolare questo percorso. Il controller non verifica esplicitamente un booleano attivo o una durata expires_in.

5.4 Contratto atteso da userinfo

RestFrontage effettua quindi questa chiamata, con il realm codificato nell'URL:

GET /oauth2/userinfo?realm=%2Fenvironnement-exemple HTTP/1.1
Host: idp.example.net
Authorization: Bearer JETON_ACCES_RETOURNE_PAR_IDP

La risposta JSON deve fornire il campo di accesso utilizzato per trovare l'account Immersive:

{
  "sub": "identifiant-externe-stable",
  "login": "agent.demo"
}

In questo percorso, l'abbinamento avviene al momento dell'accesso. Il controller non riconcilia l'account dal sub, dall'indirizzo email o da un gruppo. Il campo di accesso è un requisito di questa integrazione; non è un attributo garantito da tutti i provider OIDC.

Lo standard prevede la verifica della coerenza del sub tra UserInfo e l'ID del Token. Questo controllo non viene eseguito nel percorso esaminato, che non valida l'ID del Token. Vedi UserInfo in OpenID Connect Core.

5.5 Percorso di connessione

1. L'applicazione client ottiene un token di accesso esterno dall'IdP secondo il proprio percorso di accesso.
2. Può chiamare GET /api/OpenID/CheckToken con il token come parametro per verificare gli scambi di tokeninfo e userinfo.
3. Recupera il contesto di sicurezza Immersive, cripta il token esterno e lo invia a POST /api/OpenID/Authenticate.
4. RestFrontage chiama tokeninfo, confronta client_id e poi chiama userinfo.
5. RestFrontage avvicina l'accesso all'account Immersive, ne verifica lo stato e restituisce un AuthenticationToken.

Entrambe le rotte OpenID richiedono che l'intestazione Authorization possa essere analizzata. Tuttavia, i valori in questa intestazione non vengono sfruttati dal metodo privato CheckToken: il token effettivamente elaborato proviene dal parametro o dal corpo del token decriptato, a seconda della route. L'intestazione ricevuta quindi non autentica l'applicazione client in questo percorso da sola.

6. Configurare l'applicazione client e accedere

6.1 Favorire il giusto percorso lato cliente

Le opzioni server non selezionano automaticamente la modalità di connessione in tutte le applicazioni client. Il launcher o client deve essere configurato per il protocollo atteso e per l'URL RestFrontage.

Il valore di Login.Modes nel UserInfos.txt di chi osserva deve contenere almeno il SAML per abilitare la connessione tramite SAML e/o OIDC per OpenId.

Esempio: il seguente valore permette a un Beholder di consentire l'accesso predefinito in login/password tramite account Immersive ma anche in SAML e OIDC :

"Login.Modes" : "SAML|OIDC|DEFAULT"

Gli script Reader e Beholder esaminati conservano l'ID SSO in un cookie SSOToken per 30 secondi. Una connessione lenta o un passaggio multifattore può superare questo tempo: se il ritorno SAML ha successo ma il launcher riavvia la connessione, controlla questo punto nella versione client distribuita.

6.2 Usa il contesto di sicurezza immersivo

GET /api/Security/Context fornisce un SecurityToken contenente la chiave di crittografia pubblica. Le rotte Authenticate poi attendono un Stringa JSON criptata con il meccanismo RSA compatibile con Immersive.

Strada	Dati da quantificare
POST /api/Saml/Authenticate	L'ID della richiesta è riconosciuto dopo il ritorno SAML.
POST /api/OpenID/Authenticate	Token di accesso esterno ottenuto dall'IdP.

La forma del corpo HTTP è una stringa JSON, come in questo esempio di struttura non eseguibile:

"DONNEE_CHIFFREE_PAR_LE_CLIENT_IMMERSIVE"

Questo corpo non è un oggetto contenente encryptedData, un identificatore in chiaro o XML SAML. Utilizzare l'implementazione di crittografia compatibile fornita al client. La chiave pubblica non sovrascrive HTTPS.

6.3 Controlla i diritti dopo l'accesso

Dopo aver emesso il token, verifica che l'identità Immersive sia effettivamente restituita, i gruppi dell'account e i suoi diritti sulle funzioni e gli oggetti necessari. Testa anche una funzione che deve rimanere vietata all'account pilota.

I controller SAML e OpenID non costituiscono un diritto globale. SSO stabilisce l'identità; le regole di autorizzazione della piattaforma determinano quindi l'accesso.

7. Riferimento del percorso

Metodo e percorso	Utilizzo	Contesto previsto
GET /api/Security/Context	Fornisce la chiave pubblica Immersive.	Accessibili prima dell'autenticazione.
GET /api/Saml/GetSamlUrl	Restituisce l'URL IdP come stringa JSON.	requestId e forceAuthentication; accessibili prima dell'autenticazione.
POST /api/Saml/Login	Riceve il ritorno SAML della connessione.	Risposta SAML trasmessa dal browser dall'IdP.
POST /api/Saml/Authenticate	Scambia la richiesta SAML con un token Immersive.	Un identificatore criptato in una stringa JSON.
GET /api/Saml/GetSamlLogoutUrl	Restituisce l'URL di logout dell'IDP.	Utente Immersivo Autenticato e requestId.
GET o POST /api/Saml/Logout	Riceve un ritorno di logout SAML.	SAMLResponi nel formato previsto dal controller.
GET /api/OpenID/CheckToken	Esegue le chiamate di verifica esterne.	token come parametro di query e intestazione di autorizzazione analizzabile.
POST /api/OpenID/Authenticate	Sostituisce il token esterno con un token Immersive.	Un token esterno criptato in una stringa JSON e un'intestazione di autorizzazione analizzabile.

Il controllo diretto del token OpenID lo colloca nell'URL, proprio come la chiamata in uscita a tokeninfo. Evita di salvare questi URL con i loro parametri nei log di accesso o in una cartella di supporto non redattata.

8. Test della connessione

8.1 Audit comuni

• Gli URL corrispondono all'ambiente di destinazione e sono accessibili tramite i componenti rilevanti.
• La configurazione effettiva tiene conto di eventuali costi generali; RestFrontage è stato riavviato.
• L'account pilota esiste, ha un nome esterno unico, è attivato, non scaduto e non bloccato.
• Un login completo restituisce l'utente corretto e un token Immersive.
• L'account accede a una funzione autorizzata e non può accedere a una funzione vietata.
• Un utente esterno senza un account Immersive corrispondente non riceve un token Immersive.
• Un account Immersive disattivato, scaduto o bloccato non riceve un token.
• Disconnessione, chiusura del client e riconnessione venivano controllate separatamente.

8.2 Controlli SAML

• L'URL generato è per la destinazione corretta e la richiesta contiene l'EntityId e l'ACS corretti.
• Il ritorno raggiunge /api/Saml/Login con InResponseTo, SessionIndex e l'attributo account atteso.
• La connessione arriva fino a /api/Saml/Authenticate; la sola pagina di ritorno non viene usata come prova.
• Un retry utilizza un nuovo identificatore di richiesta; il comportamento di prevenzione delle riproduzioni è controllato.
• Un percorso con autenticazione multifattore o login lento finisce anche nel client distribuito.
• Le garanzie di validazione delle affermazioni presentate nel capitolo successivo sono effettivamente presenti prima che la produzione venga messa in produzione.

8.3 Verifiche OpenID

• Da RestFrontage, FidUrl risolve correttamente tokeninfo e userinfo.
• tokeninfo fornisce i campi richiesti e client_id corrisponde a FidAppId.
• UserInfo fornisce un accesso non vuoto per l'account pilota.
• Un token scaduto, revocato o emesso per un'altra applicazione viene negato su tutto il percorso.
• I requisiti di autenticazione dei servizi IdP sono compatibili con le chiamate effettivamente effettuate.
• La compatibilità tra l'applicazione client, l'IdP e questa versione di RestFrontage è stabilita oltre un singolo ritorno 204.

Questi punti sono un piano di test da eseguire. Non descrivono test già eseguiti su un server o su un IdP.

9. Diagnosi delle difficoltà comuni

Sintomo	Verifica della priorità
L'URL di accesso SAML è invalido	Controlla la concatenazione FidUrl + FidSsoPath e la configurazione effettivamente caricata.
IdP nega la richiesta SAML	Confronta EntityId, ACS, binding, policy NameID e requisiti di firma con la dichiarazione IdP.
Il ritorno di connessione mostra un errore o rimane senza risultato utile	Controlla il formato del ritorno, InResponseTo, SessionIndex, cn o l'attributo nome alternativo. Un semplice codice HTTP riuscito non è una prova completa della connessione.
La pagina di ritorno appare, ma Authenticate fallisce	Verifica l'account esterno, l'ID della richiesta trasmessa, il suo possibile consumo e la crittografia del corpo.
Il lanciatore si cicla dopo il ritorno del SAML	Controlla i cookie, la destinazione di ritorno e la durata di 30 secondi di SSOToken nei launcher interessati.
Richiesta non valida per un utente specifico en OpenID	Controlla entrambe le chiamate IDP, la client_id, il login e la connessione all'account Immersive.
CheckToken riesce, ma Authenticate fallisce	Verifica l'esistenza e lo stato dell'account Immersive, così come la crittografia del token esterno.
tokeninfo o userinfo restituisce 404	Controlla FidUrl, la sua ultima slash e i percorsi reali dell'IDP.
L'IdP richiede un segreto nonostante FidAppSecret sia popolata	Il controllore non usa questa segretezza per le sue chiamate; si adatta la connessione.
L'account viene segnalato come bloccato o disattivato	Controlla IsEnabled, ExpirationDate e LockoutUntilUtc nell'account Immersive.
La connessione ha successo, ma l'accesso aziendale viene negato	Verifica le autorizzazioni Immersive; l'autenticazione esterna non concede diritti di business.
IdP logout non blocca tutti gli accessi	Verifica i dati della sessione del client e il ciclo di vita del token Immersive.

I log possono includere "Richiedi login SSO per CN esterno", "Login SSO per CN esterno", "Accesso SSO fallito per richiesta" o un evento account disabilitato o bloccato. Correlazione tra ora, account autista e fase del viaggio. Oscurare token, risposte SAML e dati personali prima di trasmettere tracce.

10. Limitazioni della versione in esame

10.1 Validazione SAML da elaborare prima di un'esposizione in produzione

Il percorso esaminato decodifica la risposta SAML ed estrae i suoi attributi. Non mostra la verifica crittografica della firma, della catena di fiducia IdP, dell'audience, del destinatario, dello stato SAML o delle condizioni temporali dell'asserzione. Nessuna opzione di certificato IdP o metadati viene esposta da SamlOptions.

Pertanto, la presenza di questi dati in una risposta non ne dimostra l'autenticità. I requisiti per la validazione del profilo SSO sono descritti nel Profili OASIS SAML 2.0, sezione 4.1.

Il codice mantiene l'indice della richiesta e della sessione nel campo Codice dell'utente. Tenta di cancellare l'ID della richiesta quando viene scambiato con un token. Questo consumo non è un controllo della firma e non è sufficiente a dimostrare una protezione completa contro la riproduzione; il risultato del metodo di cancellazione non viene imposto come condizione di successo dal chiamante.

L'analizzatore legge anche il corpo del ritorno SAML come una stringa e rimuove il prefisso SAMLResponse= (SAMLResponse=). Non tratta questo corpo come un insieme completo di campi di modulo. Riformula le risposte effettive dell'IdP, specialmente quando hanno RelayState o altri campi.

10.2 Compatibilità OpenID da confermare

Il codice controlla client_id e poi sfrutta l'accesso. Non implementa la validazione generica dei token OIDC, né implementa una corrispondenza stabile basata sulla coppia emittente e soggetto. Non verifica esplicitamente attivo, scope o scadenza in tokeninfo. Il rifiuto di un token revocato o scaduto deve quindi essere confermato nel comportamento effettivo dei servizi IdP e nella ricetta completa.

Il segreto configurato non viene utilizzato in questo percorso. Le intestazioni di autorizzazione ricevute non vengono utilizzate come prova di identità per il client chiamante. Questi punti limitano i contratti IdP compatibili e dovrebbero essere considerati se è richiesta l'autenticazione del cliente.

Non pubblicizzare compatibilità validata con Microsoft Entra ID, Keycloak, AD FS o altri fornitori solo sulla presenza di route SAML e OpenID. Ogni fornitore e versione richiede la verifica contrattuale e completa del percorso.