Gestione dell'accesso singolo

2026-11-17

L'accesso singolo (SSO) consente agli utenti di accedere a DJI FlightHub 2 con i propri account aziendali. Il provider di identità aziendale (IdP) autentica gli utenti e FlightHub 2 utilizza le informazioni di identità restituite e le mappature dei ruoli per creare una sessione di accesso e concedere le autorizzazioni corrispondenti. Le password degli account aziendali sono gestite dal sistema di identità aziendale.

Questa funzionalità è disponibile per il pacchetto Enterprise del cloud pubblico e la versione on-premises. Questa guida è destinata agli amministratori dell'organizzazione e agli amministratori del sistema di identità aziendale. Descrive la configurazione delle fonti di identità, la gestione delle autorizzazioni, i test e l'attivazione e la gestione dell'accesso con account locali.



Panoramica

Fonti di identità e procedura di accesso

Un Realm è una configurazione indipendente di una fonte di identità SSO in FlightHub 2. Ogni Realm utilizza un protocollo e associa le richieste di accesso in base al dominio email. L'applicazione corrispondente nell'IdP aziendale e il Realm di FlightHub 2 devono utilizzare protocolli, credenziali dell'applicazione, URL di callback e impostazioni di restituzione dei ruoli coerenti tra loro.

Quando un utente avvia l'accesso SSO da FlightHub 2, il sistema seleziona una fonte di identità attivata in base al dominio dell'indirizzo email inserito e reindirizza l'utente all'IdP aziendale per l'autenticazione. FlightHub 2 convalida quindi le informazioni di identità restituite e determina il ruolo di gestione corrispondente dell'utente. Gli utenti devono autenticarsi nuovamente se la sessione di accesso aziendale è scaduta o se l'IdP richiede una nuova autenticazione.

Il dominio email viene utilizzato solo per selezionare una fonte di identità. Non è un identificatore univoco dell'utente e non concede direttamente autorizzazioni. Le autorizzazioni di accesso ai progetti devono essere configurate separatamente dopo l'accesso SSO.


Scelta del protocollo

FlightHub 2 supporta OIDC, SAML 2.0 e OAuth2.

ConfrontoOIDCSAML 2.0OAuth2
Fonte delle informazioni di identitàID TokenSAML AssertionJSON delle informazioni utente restituito da User URL
Metodo di configurazioneDiscovery URLIdP Metadata URL o file Metadata XMLConfigurazione manuale degli endpoint di autorizzazione, Token e informazioni utente
Impostazione di recupero dei ruoliRole PathRole AttributeRole Path (UserInfo)
Identificatore univoco dell'utenteissuer + subIdP Entity ID + persistent NameIDRealm + value identified by USER_ID_KEY
Casi d'uso adattiSistemi di identità aziendali che supportano OpenID ConnectSistemi di identità aziendali che utilizzano già SAMLSistemi che forniscono l'autorizzazione OAuth2 e un'API per le informazioni utente

Nota:

  • Si consiglia OIDC quando l'IdP aziendale supporta più protocolli. Se l'azienda utilizza già SAML per integrare altre applicazioni, può continuare a utilizzarlo.
  • OAuth2 è un protocollo di autorizzazione. Prima di selezionare OAuth2, verifica con l'amministratore dell'IdP quali campi dell'API per le informazioni utente forniscono l'ID utente stabile, il nome dell'account e le informazioni sui ruoli.
  • OIDC e OAuth2 utilizzano entrambi il flusso del codice di autorizzazione con convalida PKCE. Recuperano le informazioni di identità in modo diverso:
    • OIDC: verifica l'ID Token per stabilire l'identità dell'utente.
    • OAuth2: utilizza un Access Token per chiamare User URL e recuperare e analizzare le informazioni utente. Non utilizza i meccanismi di convalida dell'identità di OIDC basati su ID Token, Discovery o JWKS.
  • SAML 2.0 supporta solo l'accesso avviato da FlightHub 2 (SP-Initiated), non l'accesso avviato direttamente dal portale delle applicazioni dell'IdP aziendale.


Preparazione della configurazione

HTTPS deve essere attivato prima di poter utilizzare SSO nella versione on-premises. Configura HTTPS nell'ambiente di distribuzione e verifica che FlightHub 2 sia accessibile tramite HTTPS prima di configurare una fonte di identità SSO.

In qualità di amministratore dell'organizzazione, apri le Impostazioni di accesso SSO dell'organizzazione, fai clic su Crea Realm e seleziona un protocollo.

Impostazioni di accesso SSO e pulsante Crea Realm

Prima della configurazione, prepara le seguenti informazioni con l'amministratore dell'IdP aziendale:

  • Il protocollo e il Client ID, il Client Secret o i Metadata dell'applicazione corrispondente.
  • Il dominio email utilizzato per selezionare la fonte di identità e un account aziendale per il test di accesso.
  • Il campo dei ruoli e i relativi valori nelle informazioni di identità aziendali e i ruoli di gestione di FlightHub 2 da assegnare.
  • Gli endpoint HTTPS dell'IdP e i certificati validi. Assicurati che il backend di FlightHub 2 possa accedere agli endpoint e convalidarne i certificati.

Regole di configurazione:

  • In un'organizzazione possono essere attivati contemporaneamente al massimo 8 Realm. Le configurazioni non attivate possono essere salvate come bozze o conservate in stato disattivato.
  • I nomi dei Realm devono essere univoci all'interno dell'organizzazione. I nomi visualizzati identificano i Realm nell'interfaccia di amministrazione.
  • Quando si crea un Realm, Login routing email può contenere un indirizzo email completo e valido oppure solo un dominio, ad esempio user@example.com. Il sistema memorizza il dominio per l'instradamento dell'accesso. Lo stesso dominio non può essere assegnato a Realm diversi all'interno di un'organizzazione.
  • Gli URL di accesso a FlightHub 2 e gli endpoint SSO devono utilizzare HTTPS. Registra nell'IdP le informazioni di callback generate dal sistema esattamente come fornite. Non utilizzare l'URL della pagina di configurazione al posto di un URL di callback.


Configurazione delle fonti di identità

Ogni pagina di configurazione del Realm contiene quattro schede: Configurazione di base, Gestione delle autorizzazioni, Test e attivazione e Configurazione avanzata. Completa prima la configurazione di base e salva una bozza, quindi configura le mappature dei ruoli, esegui i test e attiva il Realm.

OIDC

Configurazione di base

CampoIstruzioni di configurazione
Realm name / Realm display nameInserisci un nome per identificare la fonte di identità, ad esempio Enterprise_OIDC
Login routing emailInserisci un indirizzo email completo. Il relativo dominio viene utilizzato per selezionare la fonte di identità
Discovery URLInserisci il Discovery URL HTTPS completo fornito dall'IdP
Client IDInserisci l'identificatore dell'applicazione registrata nell'IdP
Client SecretInserisci il segreto dell'applicazione corrispondente. Il valore in chiaro non viene visualizzato dopo il salvataggio
Callback URLGenerato dopo il salvataggio della bozza. Registralo nell'IdP esattamente come fornito, come URI di reindirizzamento valido
Web Origin URLGenerato dal sistema. Registralo in Web Origins secondo i requisiti dell'IdP

Dopo aver salvato la bozza, copia le informazioni di callback effettive per la distribuzione e completa la configurazione dell'applicazione nell'IdP. Gli URL segnaposto nel modulo di creazione non possono essere utilizzati per l'integrazione. L'accesso normale e il Test di accesso possono utilizzare URL di callback diversi. Registra ogni URL in base alla distribuzione.

In Gestione delle autorizzazioni, imposta Role Path in base all'array di ruoli restituito dall'IdP, ad esempio roles o claims.roles. Per le regole di mappatura dei ruoli, consulta la sezione Gestione delle autorizzazioni di seguito.

Configurazione avanzata

  • Identificatore univoco dell'identità: fissato a issuer + sub. Non può essere sostituito da un indirizzo email.
  • Claim del nome visualizzato dell'utente: il valore predefinito è name. Utilizzato solo per la visualizzazione e la ricerca, non per la corrispondenza dell'identità o l'assegnazione delle autorizzazioni.
  • Aggiornamento di Discovery: l'aggiornamento automatico è disattivato per impostazione predefinita dopo il recupero iniziale. Utilizza Aggiorna ora per recuperare nuovamente la configurazione. Se l'aggiornamento non riesce, viene mantenuta la configurazione valida più recente. Le impostazioni di aggiornamento automatico e dell'intervallo dipendono dalle opzioni disponibili nella distribuzione.
  • Opzioni avanzate del protocollo: configura Scope, che deve includere almeno openid. Authorization Endpoint, Token Endpoint e JWKS URI possono essere sostituiti manualmente.
  • Sostituzioni manuali: i campi sostituiti non vengono sovrascritti dagli aggiornamenti di Discovery. Fai clic su Ripristina valori automatici per ripristinare i valori rilevati. Le sostituzioni manuali non sostituiscono il recupero e la convalida di Discovery durante il salvataggio della configurazione.

SAML 2.0

Configurazione di base

  1. Inserisci il nome del Realm, il nome visualizzato e l'email di instradamento dell'accesso.
  2. Seleziona IdP Metadata URL o Carica XML per importare i Metadata dell'IdP aziendale. Il sistema analizza IdP Entity ID, SSO URL, il certificato di firma e Binding.
  3. Salva la bozza per ottenere SP Metadata URL e ACS URL generati oppure scarica SP Metadata XML.
  4. Fornisci i Metadata SP di FlightHub 2 all'amministratore dell'IdP per configurare l'applicazione SAML corrispondente. Leggi SP Entity ID dai Metadata SP effettivamente generati; non presumere che coincida con Metadata URL.
  5. In Gestione delle autorizzazioni, inserisci il nome dell'attributo dei ruoli e configura le mappature dei ruoli di gestione.

Per l'importazione tramite URL, il backend di FlightHub 2 deve poter accedere a Metadata URL tramite HTTPS. Per il caricamento di un file, utilizza i Metadata XML effettivamente esportati dall'IdP aziendale.

Imposta Role Attribute sul nome esatto presente in <Attribute Name="..."> nella SAML Assertion. Il valore predefinito è roles e il nome distingue tra maiuscole e minuscole. Più ruoli devono essere restituiti come elementi AttributeValue separati, anziché combinati in un'unica stringa. Ad esempio:

<Attribute Name="roles">
  <AttributeValue>fh2-member-org</AttributeValue>
</Attribute>

Configurazione avanzata

  • Identificatore univoco dell'identità: fissato a IdP Entity ID + persistent NameID. Configura l'IdP per utilizzare un NameID persistente.
  • Attributo del nome visualizzato dell'utente: il valore predefinito è displayName. L'IdP deve restituire questo attributo.
  • Aggiornamenti dei Metadata: l'aggiornamento automatico è disattivato per impostazione predefinita dopo il recupero iniziale. Per l'importazione tramite URL, utilizza l'opzione di aggiornamento disponibile nella pagina. Per il caricamento XML, carica nuovamente il file aggiornato. Le impostazioni di aggiornamento automatico e dell'intervallo dipendono dalle opzioni disponibili nella distribuzione.
  • Opzioni avanzate del protocollo: sostituisci manualmente IdP Entity ID, SSO URL, Binding e il certificato di firma oppure ripristina i valori automatici. Gli aggiornamenti dei Metadata non sovrascrivono i campi sostituiti manualmente.
  • Gestione dei certificati: importa e aggiorna i certificati di firma tramite Metadata quando possibile. L'impronta di un certificato viene utilizzata per verificarlo e non può sostituire il contenuto del certificato X.509.

OAuth2

Configurazione di base

OAuth2 non utilizza Discovery. Configura gli endpoint e i percorsi dei campi delle informazioni utente secondo la documentazione dell'API dell'IdP.

CampoIstruzioni di configurazione
Realm name / Realm display nameInserisci un nome per la fonte di identità, ad esempio Enterprise_OAuth2
Login routing emailInserisci un indirizzo email completo. Il relativo dominio viene utilizzato per selezionare la fonte di identità
Authorization URLL'URL di autorizzazione dell'utente fornito dall'IdP
Token URLL'URL per lo scambio del codice di autorizzazione fornito dall'IdP
User URLL'URL dell'API per recuperare il JSON dell'identità e dei ruoli dell'utente tramite un Access Token
Client ID / Client SecretL'identificatore e il segreto dell'applicazione IdP corrispondente
USER_ID_KEYIl percorso del campo dell'ID utente stabile nella risposta delle informazioni utente, ad esempio id o data.id
USER_ACCOUNT_KEYIl percorso del campo del nome dell'account nella risposta delle informazioni utente, ad esempio username o data.username
ScopesConfigura in base ai requisiti di autorizzazione dell'API per le informazioni utente dell'IdP
Callback URLGenerato dopo il salvataggio della bozza. Registralo nell'IdP esattamente come fornito

In Gestione delle autorizzazioni, Role Path (UserInfo) deve puntare all'array di stringhe dei ruoli nella risposta di User URL, ad esempio roles o data.roles. FlightHub 2 non recupera i ruoli OAuth2 da un Access Token JWT o da un'API separata per le autorizzazioni.

Ad esempio, se User URL restituisce la seguente struttura, imposta USER_ID_KEY su id, USER_ACCOUNT_KEY su username e Role Path su roles:

{
  "id": "user-001",
  "username": "sso-user",
  "roles": ["fh2-member-org"]
}

Questi campi sono solo esempi. I percorsi effettivi dei campi devono corrispondere alla risposta dell'IdP. Scopes non determina i ruoli e non esiste un requisito universale di includere openid; segui i requisiti dell'API dell'IdP. Anche se USER_ID_KEY è sub o Scopes include openid, questo Realm continua ad analizzare l'identità e i ruoli tramite l'API OAuth2 per le informazioni utente.

Configurazione avanzata

Configurazione avanzata mostra la regola di identità stabile associata a USER_ID_KEY e il percorso del campo del nome visualizzato dell'utente. Le informazioni visualizzate utilizzano USER_ACCOUNT_KEY; non è necessario un secondo percorso del campo.

OAuth2 non fornisce l'importazione o l'aggiornamento di Discovery o Metadata. Aggiorna manualmente gli endpoint quando cambiano. I nuovi Realm non forniscono le opzioni di compatibilità legacy USE_REDIRECT_URL o SUPER_ACCOUNT. Il comportamento di compatibilità delle autorizzazioni per le configurazioni migrate non si applica ai nuovi Realm.



Gestione delle autorizzazioni

Recupero dei ruoli e mappatura dei ruoli di gestione

In Gestione delle autorizzazioni, configura la posizione da cui recuperare i ruoli e associa i valori Role esterni restituiti dall'IdP ai ruoli di gestione di FlightHub 2.

Impostazioni di recupero dei ruoli e mappature dei ruoli di gestione

ProtocolloImpostazioneRequisiti
OIDCRole PathPunta all'array di stringhe dei ruoli nelle informazioni di identità, ad esempio roles
SAML 2.0Role AttributeCorrisponde ad Attribute Name nell'Assertion, ad esempio roles. Utilizza elementi AttributeValue separati per più ruoli
OAuth2Role Path (UserInfo)Punta all'array di stringhe dei ruoli nella risposta di User URL, ad esempio data.roles

Di seguito sono elencati i ruoli di gestione e le relative mappature predefinite. Configura un valore Role esterno per ogni ruolo di gestione.

Ruolo di gestione di FlightHub 2Valore Role esterno predefinitoPriorità
Amministratore dell'organizzazionefh2-admin-org1 (massima)
Manutentore del dispositivofh2-admin-device2
Membrofh2-member-org3
  • Gli utenti devono corrispondere ad almeno un ruolo di gestione per accedere tramite un Realm SSO appena creato.
  • Se corrispondono più ruoli di gestione, viene utilizzato quello con la priorità più alta. I valori Role non riconosciuti vengono ignorati.
  • Gli utenti SSO esterni non possono essere associati al ruolo di super amministratore.
  • L'autorizzazione si basa attualmente su Roles, non direttamente su Groups, Security Groups o altri attributi. Se l'azienda gestisce gli utenti tramite gruppi, configura l'IdP per convertire l'appartenenza ai gruppi nell'elenco di ruoli concordato.

Autorizzazioni dei progetti

I ruoli di gestione SSO e le autorizzazioni dei progetti sono indipendenti. Dopo l'accesso riuscito, un amministratore deve comunque aggiungere gli utenti SSO nella gestione dei membri del progetto, assegnare i ruoli del progetto e associare gli utenti tramite l'identificatore univoco stabile del Realm corrispondente. Per la configurazione dei ruoli del progetto, consulta Gestione ruoli utente del progetto.



Test e attivazione

Procedura di test

  1. Completa Configurazione di base e Gestione delle autorizzazioni, quindi fai clic su Salva bozza.
  2. Apri Test e attivazione ed esegui il Test di connettività per verificare i campi obbligatori, HTTPS, gli endpoint del protocollo e la configurazione applicabile di Discovery, Metadata o certificati.
  3. Esegui il Test di accesso, autenticati con un account di test nella pagina dell'IdP che si apre e torna alla pagina di configurazione originale.
  4. Verifica l'identificatore stabile, il nome visualizzato, l'email, l'elenco Role e il ruolo di gestione restituiti. Conferma che il recupero e la mappatura dei ruoli funzionino come previsto.
  5. Dopo il superamento dei test, fai clic su Salva e applica e verifica che la fonte di identità sia attivata.
Test di connettività e Test di accesso entrambi superati

Il test di connettività convalida solo la configurazione e gli endpoint. Non sostituisce un test di accesso effettivo dell'utente. OIDC richiede il superamento del test di connettività prima dell'attivazione. Se il Test di accesso non è stato superato, l'attivazione del Realm dopo aver riconosciuto i rischi come richiesto nella pagina non significa che la convalida dell'accesso sia stata superata. Si consiglia di completare entrambi i test prima dell'attivazione. SAML 2.0 dovrebbe essere attivato dopo il superamento di entrambi i test. I Realm OAuth2 appena creati richiedono il superamento di entrambi i test; la disponibilità di un pulsante o un messaggio di conferma generico non indica che i test siano stati superati.

Se il recupero di Discovery, l'importazione dei Metadata o lo scambio del Token non riesce, verifica la rete del backend di FlightHub 2, l'attendibilità del certificato TLS, le credenziali dell'applicazione, gli URL di callback e i parametri del protocollo. Correggi la configurazione, quindi salva ed esegui nuovamente i test.


Manutenzione delle fonti di identità

L'elenco consente di modificare o proseguire la configurazione, eseguire test, attivare, disattivare ed eliminare le fonti di identità. Gestisci ogni stato come segue:

StatoAzione
BozzaCompleta la configurazione, salva ed esegui i test
Nuovo test richiestoVerifica le modifiche alle impostazioni principali ed esegui nuovamente i test
Test non riuscitoEsamina i risultati dell'errore, correggi la configurazione dell'IdP o di FlightHub 2 e ripeti i test
Pronto per l'attivazioneConferma i risultati dei test e attiva il Realm secondo le condizioni indicate nella pagina
AttivatoDisponibile per l'accesso. Ripeti i test come richiesto dopo le modifiche alle impostazioni principali
DisattivatoLa configurazione viene conservata ma non è disponibile per l'accesso normale

Dopo aver aggiornato gli endpoint dell'IdP, i certificati o le impostazioni di restituzione dei ruoli, aggiorna il Realm di conseguenza e ripeti i test. I campi sostituiti manualmente non vengono aggiornati con i valori recuperati automaticamente e devono essere verificati separatamente.



Gestione dell'accesso con account locali

L'interruttore Consenti accesso con password per account locali nella pagina Impostazioni di accesso SSO controlla se gli account locali ordinari possono accedere con una password. Quando è disattivato, gli account locali ordinari non possono utilizzare l'accesso con password e i membri devono accedere tramite una fonte di identità SSO attivata che abbia superato i test.

Per disattivare l'accesso con password per gli account locali:

  1. Configura, testa e attiva almeno un Realm e verifica che gli account aziendali possano accedere correttamente.
  2. Verifica che l'account del super amministratore di emergenza e la relativa password locale funzionino.
  3. Disattiva Consenti accesso con password per account locali e seleziona Designa super amministratore di emergenza nella finestra di dialogo.
  4. Esamina le conseguenze, seleziona la casella di conferma e fai clic su Conferma disattivazione.
Designazione di un super amministratore di emergenza durante la disattivazione dell'accesso con account locali

Se l'IdP aziendale non è disponibile o la configurazione SSO è errata, il super amministratore di emergenza designato può accedere al sistema con una password locale per riattivare l'accesso con account locali o correggere la configurazione SSO. Un normale amministratore dell'organizzazione non è un super amministratore di emergenza e il solo nome dell'account non determina la disponibilità dell'accesso di emergenza.



Esempio di integrazione con Keycloak

Gli esempi seguenti descrivono come configurare ciascun protocollo con Keycloak. Sostituisci i domini, i nomi dei Realm, i Client ID e i percorsi dei campi di esempio con i valori della distribuzione. Utilizza gli URL di callback e le informazioni dei Metadata SP generate da FlightHub 2. Le posizioni dei menu possono variare tra le versioni di Keycloak.

Le schermate illustrano le posizioni delle impostazioni e le opzioni principali. I nomi dei Realm, dei Client e degli utenti di test mostrati nelle schermate sono esempi. Per la configurazione effettiva, utilizza la fonte di identità, l'applicazione e le informazioni utente della tua azienda.


Creazione di una fonte di identità aziendale, dei ruoli e degli utenti di test

  1. Accedi alla console di amministrazione di Keycloak e crea o seleziona un Realm aziendale in Manage realms, ad esempio Enterprise.

    Creazione di un Realm Keycloak, inserimento del nome e attivazione
  2. In Realm roles, crea fh2-admin-org, fh2-admin-device e fh2-member-org oppure crea valori dei ruoli che corrispondano alle mappature di FlightHub 2.

    Elenco dei ruoli del Realm Keycloak e pulsante Create role
  3. In Users, crea e attiva un utente di test. Imposta una password in Credentials e completa tutte le azioni richieste per l'account.

  4. Assegna un ruolo di test nella scheda Role mapping dell'utente. Per il primo test, assegna un solo ruolo di gestione, ad esempio fh2-member-org, per rendere più semplice la verifica dei risultati.

    Assegnazione del ruolo Membro a un utente di test in Keycloak

Un Realm aziendale in Keycloak e un Realm in FlightHub 2 sono unità di configurazione diverse e non devono necessariamente avere lo stesso nome. Quando integri più protocolli, configura un Client separato per ciascun protocollo e utilizza domini di instradamento dell'accesso diversi.


Integrazione OIDC

  1. Crea un Client OpenID Connect in Keycloak, ad esempio Enterprise_OIDC.

  2. Attiva Client authentication e Standard flow e disattiva Implicit flow. Direct access grants non è necessario per SSO tramite browser. Attiva Require PKCE e imposta PKCE Method su S256. Cerca queste impostazioni in Settings → Capability config.

    Impostazioni del flusso di autenticazione del Client Keycloak e di PKCE S256
  3. Crea un Realm OIDC in FlightHub 2 e inserisci l'email di instradamento dell'accesso, Client ID, Client Secret e Discovery URL. Il Discovery URL di Keycloak ha il seguente formato:

    https://idp.example.com/realms/Enterprise/.well-known/openid-configuration
    
  4. Salva la bozza di FlightHub 2 per ottenere le informazioni di callback effettive. Registra gli URL di callback per l'accesso normale e di test in Valid redirect URIs nel Client Keycloak e configura Web origins utilizzando le informazioni generate da FlightHub 2. Recupera il Client Secret dalla scheda Credentials del Client.

  5. Aggiungi un User Realm Role Mapper in Client scopes → scope dedicato del Client → Mappers:

    Apri Client scopes, seleziona lo scope dedicato del Client corrente e apri la configurazione del mapper.

    Voce dello scope dedicato in Client scopes di Keycloak
    ImpostazioneValore di esempio
    Namesikong-roles
    Token Claim Nameroles
    Claim JSON TypeString
    MultivaluedAttivato
    Add to ID token / Add to access token / Add to userinfoAttivato
    User Realm Role Mapper di Keycloak che restituisce ruoli multivalore nei token e nelle informazioni utente
  6. In FlightHub 2, imposta Role Path su roles, configura le mappature dei ruoli di gestione ed esegui il Test di connettività e il Test di accesso. Verifica i ruoli, quindi salva e applica la configurazione.


Integrazione SAML 2.0

  1. Recupera i Metadata dell'IdP da Keycloak utilizzando un URL nel seguente formato. I Metadata XML restituiti da questo URL possono essere utilizzati anche per il caricamento di un file.

    https://idp.example.com/realms/Enterprise/protocol/saml/descriptor
    
  2. Crea un Realm SAML 2.0 in FlightHub 2, importa i Metadata dell'IdP, salva la bozza e scarica i Metadata SP XML generati.

  3. In Keycloak, importa i Metadata SP in Clients → Import client oppure crea manualmente un Client SAML e verifica i seguenti campi:

    ImpostazioneValore di esempio
    Client IDEntity ID dai Metadata SP di FlightHub 2
    NameUn nome per identificare l'applicazione, ad esempio Enterprise_SAML
    Valid redirect URIsACS URL di FlightHub 2
    Name ID formatpersistent
    Force name ID formatAttivato
    Force POST bindingAttivato, per restituire la risposta SAML tramite POST
    Sign documents / Sign assertionsAttivato
    Signature algorithmRSA_SHA256
    Client signature requiredAttivato. Importa il certificato di firma SP dai Metadata SP di FlightHub 2
    IDP-Initiated SSO URL nameLascia vuoto. Avvia l'accesso da FlightHub 2

    La schermata seguente mostra dove configurare il NameID persistente e POST Binding. Verifica le impostazioni di firma e dei certificati rispetto alla tabella precedente.

    Impostazioni SAML di Keycloak per NameID persistente e POST Binding
  4. Configura i Mappers dei ruoli e delle informazioni utente nello scope dedicato del Client SAML:

    Tipo di mapperImpostazioni principali
    Role listName e Role attribute name: roles; NameFormat: Basic; Single Role Attribute: Attivato
    User PropertyUser property: username; Attribute name: displayName
    User PropertyUser property: email; Attribute name: email
    Mapper SAML Role list di Keycloak con l'attributo roles e Single Role Attribute attivato
  5. Verifica lo scope predefinito role_list del Client e il Mapper dei ruoli personalizzato per evitare la restituzione di ruoli duplicati o in conflitto. Quando utilizzi il Mapper personalizzato roles descritto sopra, rimuovi da questo Client qualsiasi assegnazione di scope predefinito in conflitto.

  6. In FlightHub 2, imposta Role Attribute su roles e l'attributo del nome visualizzato dell'utente su displayName, quindi configura le mappature dei ruoli di gestione. Salva e applica la configurazione dopo il superamento di entrambi i test.

Client ID deve utilizzare l'SP Entity ID effettivo, non il nome visualizzato dell'applicazione. L'AuthnRequest di FlightHub 2 può utilizzare Redirect Binding mentre la risposta dell'IdP utilizza POST Binding; questi binding hanno scopi diversi. Dopo aver ricreato un Realm SAML in FlightHub 2, recupera i nuovi Metadata SP e verifica e aggiorna le impostazioni di Entity ID, ACS e certificati nell'IdP.


Integrazione OAuth2

Keycloak fornisce gli endpoint OAuth2 tramite un Client OpenID Connect. Seleziona il protocollo OAuth2 in FlightHub 2.

  1. Crea un Client separato in Keycloak, ad esempio Enterprise_OAuth2. Segui l'esempio OIDC precedente per configurare Client authentication, Standard flow, PKCE e gli URL di callback per l'accesso normale e di test e recupera il Secret specifico di questo Client.

  2. Aggiungi un User Realm Role Mapper nello scope dedicato del Client. Imposta Token Claim Name su roles e attiva Multivalued; assicurati inoltre che Add to userinfo sia attivato.

  3. Crea un Realm OAuth2 in FlightHub 2 e inserisci le credenziali dell'applicazione corrispondente, l'email di instradamento dell'accesso e le seguenti impostazioni:

    Campo di FlightHub 2Esempio Keycloak
    Authorization URLhttps://idp.example.com/realms/Enterprise/protocol/openid-connect/auth
    Token URLhttps://idp.example.com/realms/Enterprise/protocol/openid-connect/token
    User URLhttps://idp.example.com/realms/Enterprise/protocol/openid-connect/userinfo
    USER_ID_KEYsub
    USER_ACCOUNT_KEYpreferred_username
    Scopesopenid profile email, per l'API di Keycloak per le informazioni utente in questo esempio
    Role Path (UserInfo)roles
  4. Salva la bozza e configura le mappature dei ruoli di gestione. Salva e applica la configurazione solo dopo che il Test di connettività e il Test di accesso sono stati entrambi superati e che le informazioni utente e il ruolo di gestione corrispondono ai risultati previsti.

Gli Scopes e i campi utente di esempio si applicano alla configurazione Keycloak descritta sopra. Adattali in base alla documentazione dell'API quando integri un altro IdP.



Domande frequenti

Perché gli utenti non riescono ad accedere anche se il test di connettività è stato superato?

Il test di connettività verifica la configurazione e gli endpoint. Il Test di accesso verifica le informazioni di identità effettive, il recupero dei ruoli e le mappature dei ruoli di gestione. Esegui il Test di accesso e verifica l'ID utente stabile, i campi dei ruoli, i risultati delle mappature, gli URL di callback e i risultati della convalida della firma.

Come si risolve una mancata corrispondenza dell'URL di callback?

Confronta il redirect_uri nella richiesta effettiva con l'URL di callback registrato per l'applicazione IdP corrispondente. Devono coincidere esattamente, inclusi protocollo, dominio, porta e percorso. Registra i callback per l'accesso normale e di test in base alla distribuzione. Non utilizzare l'URL della pagina di configurazione del frontend o i valori segnaposto di un modulo non salvato.

L'email di instradamento dell'accesso deve corrispondere all'email dell'utente nell'IdP?

L'email di instradamento dell'accesso seleziona la fonte di identità, mentre l'email dell'utente nell'IdP fa parte del profilo dell'utente. Hanno scopi diversi. Segui i requisiti di configurazione dell'IdP per gli account e gli indirizzi email. Il dominio di instradamento dell'accesso deve rispettare i requisiti del formato email e non deve contenere caratteri di sottolineatura. Inserisci un indirizzo email completo quando crei il Realm.

Perché FlightHub 2 non riesce a recuperare i ruoli restituiti dall'IdP?

Per OIDC, verifica Role Path rispetto alla struttura dell'array nelle informazioni di identità. Per OAuth2, verifica l'array di ruoli restituito da User URL. Per SAML, verifica le maiuscole e le minuscole di Attribute Name e assicurati che più ruoli utilizzino elementi AttributeValue separati. Verifica anche eventuali conflitti tra i Mappers predefiniti e personalizzati dell'IdP e conferma che i valori Role restituiti corrispondano alle mappature dei ruoli di gestione.

Perché non sono visibili progetti dopo un accesso riuscito?

I ruoli di gestione SSO non concedono automaticamente autorizzazioni dei progetti. Un amministratore deve aggiungere l'utente nella gestione dei membri del progetto, assegnare un ruolo del progetto e associare l'utente tramite l'identificatore univoco stabile del suo Realm.

È possibile utilizzare un indirizzo email come identificatore univoco dell'utente?

No. Gli indirizzi email possono cambiare o essere riutilizzati. OIDC utilizza issuer + sub, SAML utilizza IdP Entity ID + persistent NameID e OAuth2 utilizza Realm + stable user ID. Anche i nomi visualizzati e i nomi degli account non sostituiscono l'identificatore univoco stabile.

Come si risolvono gli errori di recupero di Discovery o Metadata?

Verifica che l'URL sia corretto, che il backend di FlightHub 2 possa accedervi tramite HTTPS e che consideri attendibile il certificato dell'IdP. L'accesso dal browser o l'accettazione di un certificato nel browser non significa che il backend di FlightHub 2 possa accedere all'URL o considerare attendibile il certificato. Per SAML, è anche possibile caricare i Metadata XML effettivamente esportati dall'IdP. Dopo aver risolto il problema, salva ed esegui nuovamente i test.

Come si risolve un errore nello scambio del token dopo l'autenticazione nell'IdP?

Verifica la connessione di rete e l'attendibilità del certificato TLS tra il backend di FlightHub 2 e Token URL. Verifica il Client ID e il Client Secret corrispondenti, l'URL di callback effettivo e i parametri PKCE. Ripeti i test dopo aver risolto il problema e conferma che le informazioni utente e i ruoli di gestione vengano recuperati correttamente.

Come si aggiornano i certificati o gli endpoint?

Per OIDC, aggiorna Discovery. Per l'importazione SAML tramite URL, aggiorna i Metadata; per il caricamento XML, carica nuovamente il file aggiornato. Verifica i campi sostituiti manualmente e aggiornali oppure ripristina i valori automatici secondo necessità. Per OAuth2, aggiorna manualmente gli endpoint. Esegui nuovamente i test dopo aver apportato le modifiche.

La disconnessione da FlightHub 2 disconnette l'utente anche dall'IdP aziendale?

La disconnessione termina solo la sessione di FlightHub 2. Non disconnette l'utente dall'IdP aziendale. La sessione aziendale potrebbe essere ancora attiva all'accesso successivo e il Test di accesso potrebbe richiedere una nuova autenticazione.

Come si ripristina l'accesso se l'IdP non funziona dopo la disattivazione dell'accesso con password locale?

Il super amministratore di emergenza designato durante la disattivazione dell'accesso con account locali può utilizzare una password locale per accedere al sistema, riattivare l'accesso con account locali o correggere la configurazione SSO. Verifica che questo account e la relativa password funzionino prima di disattivare l'accesso con account locali.

Cosa occorre verificare se non è possibile attivare una fonte di identità?

Verifica se la bozza è stata salvata, se i campi obbligatori sono validi, se è richiesto un nuovo test o se è stato raggiunto il limite di 8 Realm attivati. Per un Realm OAuth2 appena creato, verifica anche che entrambi i test siano stati superati.

Last Updated: