Accesso degli utenti con SAML

Questo documento mostra come utilizzare Identity Platform per accedere agli utenti con un provider SAML (Security Assertion Markup Language) 2.0.

Prima di iniziare

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

  6. Attiva Identity Platform e aggiungi l'SDK client alla tua app. Per scoprire come fare, consulta la guida rapida.

    7. Configurazione del provider

    1. Vai alla pagina Provider di identità nella console Google Cloud .
      Vai alla pagina Provider di identità

    2. Fai clic su Aggiungi un provider e seleziona SAML dall'elenco.

    3. Inserisci i seguenti dettagli:

      1. Il nome del fornitore. Può essere uguale all'ID fornitore o un nome personalizzato. Se inserisci un nome personalizzato, fai clic su Modifica accanto a ID fornitore per specificare l'ID (che deve iniziare con saml.).

      2. L'ID entità del fornitore.

      3. L'URL SSO SAML del fornitore.

      4. Il certificato utilizzato per la firma dei token sul provider. Assicurati di includere le stringhe di inizio e di fine. Ad esempio:

        -----BEGIN CERTIFICATE-----
MIICajCCAdOgAwIBAgIBADANBgkqhkiG9w0BAQ0FADBSMQswCQYDVQQGEwJ1czEL
...
LEzc1JwEGQQVDYQCwsQMSBDAF0QAB0w9GikhqkgBNADABIgABIwAgOdACCjaCIIM
-----END CERTIFICATE-----

    4. In Fornitore di servizi, inserisci l'ID entità della tua app. In genere si tratta dell'URL dell'app. Nel tuo provider di identità SAML, questo valore è denominato pubblico.

    5. Aggiungi la tua app all'elenco dei domini autorizzati. Ad esempio, se l'URL di accesso della tua app è https://example.com/login, aggiungi example.com.

    6. Se necessario, personalizza l'URL di callback per la tua app. Questo URL è comunemente chiamato URL Assertion Consumer Service (ACS) dai provider di identità SAML.

      L'utilizzo dell'URL di callback predefinito riduce la complessità della convalida della risposta SAML. Se personalizzi questo flusso, assicurati che l'URL di callback di Identity Platform per il tuo progetto sia configurato nel provider di identità SAML. In genere, ha un aspetto simile a questo: https://[PROJECT-ID].firebaseapp.com/__/auth/handler. Per saperne di più, consulta Personalizzazione di un gestore autenticazione.

    7. Fai clic su Salva.

    Elementi obbligatori per il provider

    Identity Platform prevede gli elementi <saml:Subject> e <saml:NameID> nelle risposte del fornitore. Se non definisci i valori per questi elementi durante la configurazione del provider, l'asserzione SAML non va a buon fine.

    Richieste di firma

    Puoi aumentare la sicurezza delle tue richieste di autenticazione firmandole.

    Per firmare le richieste, attiva innanzitutto le richieste firmate per il tuo provider di identità chiamando inboundSamlConfigs.patch() e impostando idp_config.sign_request su true:

    REST

    Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

    • project-id: l'ID del Google Cloud progetto
    • provider-id: l'ID provider SAML

    Metodo HTTP e URL: 

    PATCH https://identitytoolkit.googleapis.com/admin/v2/projects/project-id/inboundSamlConfigs/provider-id?updateMask=idpConfig.signRequest

    Corpo JSON della richiesta: 

    {
  "idp_config": {
    "sign_request": true
  }
}

    Per inviare la richiesta, espandi una di queste opzioni:

     

    Devi utilizzare l'API REST per abilitare le richieste firmate; l'utilizzo della consoleGoogle Cloud o di Google Cloud CLI non è supportato.

    La risposta è un oggetto InboundSamlConfig, che include un array di SpCertificate. Configura il valore del certificato X509 con il tuo provider di identità SAML in modo che possa convalidare la firma delle tue richieste.

    Accesso degli utenti

    Quando esegui l'accesso di un utente, l'SDK client gestisce l'handshake di autenticazione, quindi restituisce token ID contenenti gli attributi SAML nei relativi payload. Per accedere a un utente e ottenere gli attributi dal fornitore SAML:

    1. Crea un'istanza SAMLAuthProvider con l'ID fornitore configurato nella sezione precedente. L'ID fornitore deve iniziare con saml..

      Versione web 9

      import { SAMLAuthProvider } from "firebase/auth";

const provider = new SAMLAuthProvider("saml.myProvider");
      auth_saml_provider_create.js

      Versione web 8

      const provider = new firebase.auth.SAMLAuthProvider('saml.myProvider');
      saml.js

    2. Avvia il flusso di accesso. Puoi scegliere di utilizzare un popup o un reindirizzamento.

      Versione web 9

      import { getAuth, signInWithPopup, SAMLAuthProvider } from "firebase/auth";

const auth = getAuth();
signInWithPopup(auth, provider)
  .then((result) => {
    // User is signed in.
    // Provider data available from the result.user.getIdToken()
    // or from result.user.providerData
  }).catch((error) => {
    // Handle Errors here.
    const errorCode = error.code;
    const errorMessage = error.message;
    // The email of the user's account used.
    const email = error.customData.email;
    // The AuthCredential type that was used.
    const credential = SAMLAuthProvider.credentialFromError(error);
    // Handle / display error.
    // ...
  });
      auth_saml_signin_popup.js

      Versione web 8

      firebase.auth().signInWithPopup(provider)
  .then((result) => {
    // User is signed in.
    // Identity provider data available in result.additionalUserInfo.profile,
    // or from the user's ID token obtained from result.user.getIdToken()
    // as an object in the firebase.sign_in_attributes custom claim
    // This is also available from result.user.getIdTokenResult()
    // idTokenResult.claims.firebase.sign_in_attributes.
  })
  .catch((error) => {
    // Handle / display error.
    // ...
  });
      saml.js

      Reindirizzamento

      Per reindirizzare a una pagina di accesso, chiama il numero signInWithRedirect():

      Versione web 9

      import { getAuth, signInWithRedirect } from "firebase/auth";

const auth = getAuth();
signInWithRedirect(auth, provider);
      auth_saml_signin_redirect.js

      Versione web 8

      firebase.auth().signInWithRedirect(provider);
      saml.js

      Poi chiama getRedirectResult() per ottenere i risultati quando l'utente torna alla tua app:

      Versione web 9

      import { getAuth, getRedirectResult, SAMLAuthProvider } from "firebase/auth";

const auth = getAuth();
getRedirectResult(auth)
  .then((result) => {
    // User is signed in.
    // Provider data available from the result.user.getIdToken()
    // or from result.user.providerData
  })
  .catch((error) => {
    // Handle Errors here.
    const errorCode = error.code;
    const errorMessage = error.message;
    // The email of the user's account used.
    const email = error.customData.email;
    // The AuthCredential type that was used.
    const credential = SAMLAuthProvider.credentialFromError(error);
    // Handle / display error.
    // ...
  });
      auth_saml_signin_redirect_result.js

      Versione web 8

      firebase.auth().getRedirectResult()
  .then((result) => {
    // User is signed in.
    // Provider data available in result.additionalUserInfo.profile,
    // or from the user's ID token obtained from result.user.getIdToken()
    // as an object in the firebase.sign_in_attributes custom claim
    // This is also available from result.user.getIdTokenResult()
    // idTokenResult.claims.firebase.sign_in_attributes.
  }).catch((error) => {
    // Handle / display error.
    // ...
  });
      saml.js

    3. Recupera gli attributi utente associati al provider SAML dal token ID utilizzando l'attestazione firebase.sign_in_attributes. Assicurati di verificare il token ID utilizzando l'SDK Admin quando lo invii al server.

      Il token ID include l'indirizzo email dell'utente solo se fornito nell'attributo NameID dell'asserzione SAML del provider di identità:

      <Subject>
  <NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">test@email.com</NameID>
</Subject>

      Questo valore viene inserito nel token ID emesso da Firebase e nell'oggetto UserInfo.

    Al momento, sono supportati solo i flussi SAML avviati dal fornitore di servizi dall'SDK client.

    Collegamento degli account utente

    Se un utente ha già eseguito l'accesso alla tua app utilizzando un metodo diverso (ad esempio email/password), puoi collegare il suo account esistente al provider SAML utilizzando linkWithPopup() o linkWithRedirect(): Ad esempio, possiamo collegare un Account Google:

    Versione web 9

    import { getAuth, linkWithPopup, GoogleAuthProvider } from "firebase/auth";
const provider = new GoogleAuthProvider();

const auth = getAuth();
linkWithPopup(auth.currentUser, provider).then((result) => {
  // Accounts successfully linked.
  const credential = GoogleAuthProvider.credentialFromResult(result);
  const user = result.user;
  // ...
}).catch((error) => {
  // Handle Errors here.
  // ...
});
    auth_link_with_popup.js

    Versione web 8

    auth.currentUser.linkWithPopup(provider).then((result) => {
  // Accounts successfully linked.
  var credential = result.credential;
  var user = result.user;
  // ...
}).catch((error) => {
  // Handle Errors here.
  // ...
});
    link-multiple-accounts.js

    Passaggi successivi