Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Gestione programmatica dei provider SAML e OIDC

Questo documento mostra come utilizzare l'SDK Admin di Identity Platform per gestire le configurazioni del provider SAML (Security Assertion Markup Language) 2.0 e OpenID Connect (OIDC) in modo programmatico.

Con l'SDK Admin puoi configurare automaticamente i provider, eseguire operazioni CRUD di base, ruotare certificati e altro ancora. Questo è utile quando hai un numero elevato di provider che sarebbe difficoltoso da gestire manualmente utilizzando la console Google Cloud.

Prima di iniziare

Collaborare con provider SAML

Creazione della configurazione di un provider SAML

Quando crei una configurazione del provider SAML, devi fornire i seguenti parametri. Potrebbe essere necessario consultare la documentazione del provider di identità per i dettagli su come ottenere alcuni valori.

Nome visualizzato
Un nome visualizzato intuitivo per la configurazione. Questo nome è anche l'etichetta del provider nella console Google Cloud.
Abilitato
Indica se la configurazione attuale del provider è abilitata o meno. Gli utenti non possono accedere con i provider disattivati.
ID provider
L'identificatore univoco del fornitore, che inizia con saml..
ID entità del provider di identità
L'ID entità del provider.
URL SSO
L'URL del servizio SSO basato su SAML per il provider. L'URL deve essere valido.
Certificati X.509

Un elenco dei certificati X.509 del provider SAML, incluse le stringhe -----BEGIN CERTIFICATE----- e -----END CERTIFICATE----. che vengono utilizzati per la firma del token sul provider di identità.

Quando Identity Platform riceve una risposta SAML, ne verificherà la firma utilizzando un certificato registrato. Se la verifica ha esito negativo, la risposta verrà rifiutata. Dovrai aggiornare questi certificati man mano che le chiavi vengono ruotate. Valuta la possibilità di caricare più certificati per evitare interruzioni durante le rotazioni.

ID entità di inoltro
L'ID entità del partito di riferimento SAML (RP/SP). Si tratta in genere dell'URL dell'app. Nel provider di identità SAML viene denominato pubblico.
URL di callback

L'URL a cui tornare quando l'autenticazione è completa. I provider SAML lo chiamano comunemente l'URL ACS (Assertion Consumer Service). Dovrai registrare questo URL con il provider SAML. Dovrebbe essere simile a https://PROJECT-ID.firebaseapp.com/__/auth/handler, simile agli URL visualizzati nella console Google Cloud. Per saperne di più, consulta la pagina Accedere agli utenti con SAML.

L'utilizzo dell'URL di callback predefinito riduce la complessità della convalida delle risposte SAML. Tuttavia, puoi anche scegliere di mostrare un dominio personalizzato. In questo caso, assicurati che l'URL di callback di Identity Platform per il tuo progetto sia configurato correttamente con il tuo provider di identità SAML. In genere è simile a https://AUTH-DOMAIN/__/auth/handler.

L'esempio seguente mostra come creare una configurazione del provider SAML:

Node.js 

const newConfig = {
  displayName: 'SAML provider name',
  enabled: true,
  providerId: 'saml.myProvider',
  idpEntityId: 'IDP_ENTITY_ID',
  ssoURL: 'https://example.com/saml/sso/1234/'
  x509Certificates: [
    '-----BEGIN CERTIFICATE-----\nCERT1...\n-----END CERTIFICATE-----',
    '-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----',
  ],
  rpEntityId: 'RP_ENTITY_ID',
  // Using the default callback URL.
  callbackURL: 'https://project-id.firebaseapp.com/__/auth/handler',
};
admin.auth().createProviderConfig(newConfig).then(() => {
  // Successful creation.
}).catch((error) => {
  // Handle error.
});

Go 

newConfig := (&auth.SAMLProviderConfigToCreate{}).
	DisplayName("SAML provider name").
	Enabled(true).
	ID("saml.myProvider").
	IDPEntityID("IDP_ENTITY_ID").
	SSOURL("https://example.com/saml/sso/1234/").
	X509Certificates([]string{
		"-----BEGIN CERTIFICATE-----\nCERT1...\n-----END CERTIFICATE-----",
		"-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----",
	}).
	RPEntityID("RP_ENTITY_ID").
	CallbackURL("https://project-id.firebaseapp.com/__/auth/handler")
saml, err := client.CreateSAMLProviderConfig(ctx, newConfig)
if err != nil {
	log.Fatalf("error creating SAML provider: %v\n", err)
}

log.Printf("Created new SAML provider: %s", saml.ID)
auth.go

Python 

saml = auth.create_saml_provider_config(
    display_name='SAML provider name',
    enabled=True,
    provider_id='saml.myProvider',
    idp_entity_id='IDP_ENTITY_ID',
    sso_url='https://example.com/saml/sso/1234/',
    x509_certificates=[
        '-----BEGIN CERTIFICATE-----\nCERT1...\n-----END CERTIFICATE-----',
        '-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----',
    ],
    rp_entity_id='P_ENTITY_ID',
    callback_url='https://project-id.firebaseapp.com/__/auth/handler')

print('Created new SAML provider:', saml.provider_id)
index.py

Java 

SamlProviderConfig.CreateRequest request = new SamlProviderConfig.CreateRequest()
    .setDisplayName("SAML provider name")
    .setEnabled(true)
    .setProviderId("saml.myProvider")
    .setIdpEntityId("IDP_ENTITY_ID")
    .setSsoUrl("https://example.com/saml/sso/1234/")
    .addX509Certificate("-----BEGIN CERTIFICATE-----\nCERT1...\n-----END CERTIFICATE-----")
    .addX509Certificate("-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----")
    .setRpEntityId("RP_ENTITY_ID")
    .setCallbackUrl("https://project-id.firebaseapp.com/__/auth/handler");
SamlProviderConfig saml = FirebaseAuth.getInstance().createSamlProviderConfig(request);
System.out.println("Created new SAML provider: " + saml.getProviderId());
FirebaseAuthSnippets.java

Al termine, il metodo restituisce un oggetto SAMLAuthProviderConfig per la configurazione appena creata.

Aggiornamento della configurazione di un provider SAML

L'esempio seguente mostra come modificare la configurazione di un provider SAML. Puoi aggiornare qualsiasi campo, ad eccezione dell'ID provider.

Node.js 

const updatedConfig = {
  x509Certificates: [
    '-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----',
    '-----BEGIN CERTIFICATE-----\nCERT3...\n-----END CERTIFICATE-----',
  ],
};
admin.auth().updateProviderConfig('saml.myProvider', updatedConfig).then(() => {
  // Successful update.
}).catch((error) => {
  // Handle error.
});

Go 

updatedConfig := (&auth.SAMLProviderConfigToUpdate{}).
	X509Certificates([]string{
		"-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----",
		"-----BEGIN CERTIFICATE-----\nCERT3...\n-----END CERTIFICATE-----",
	})
saml, err := client.UpdateSAMLProviderConfig(ctx, "saml.myProvider", updatedConfig)
if err != nil {
	log.Fatalf("error updating SAML provider: %v\n", err)
}

log.Printf("Updated SAML provider: %s", saml.ID)
auth.go

Python 

saml = auth.update_saml_provider_config(
    'saml.myProvider',
    x509_certificates=[
        '-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----',
        '-----BEGIN CERTIFICATE-----\nCERT3...\n-----END CERTIFICATE-----',
    ])

print('Updated SAML provider:', saml.provider_id)
index.py

Java 

SamlProviderConfig.UpdateRequest request =
    new SamlProviderConfig.UpdateRequest("saml.myProvider")
      .addX509Certificate("-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----")
      .addX509Certificate("-----BEGIN CERTIFICATE-----\nCERT3...\n-----END CERTIFICATE-----");
SamlProviderConfig saml = FirebaseAuth.getInstance().updateSamlProviderConfig(request);
System.out.println("Updated SAML provider: " + saml.getProviderId());
FirebaseAuthSnippets.java

Al termine, il metodo restituisce un oggetto SAMLAuthProviderConfig per la configurazione aggiornata.

Recupero della configurazione di un provider SAML

Il modo principale per identificare una configurazione SAML è tramite l'ID provider. L'esempio seguente mostra come ottenere la configurazione di un provider SAML:

Node.js 

admin.auth().getProviderConfig('saml.myProvider').then((config) => {
  // Get display name and whether it is enabled.
  console.log(config.displayName, config.enabled);
}).catch((error) => {
  // Handle error. Common error is that config is not found.
});

Go 

saml, err := client.SAMLProviderConfig(ctx, "saml.myProvider")
if err != nil {
	log.Fatalf("error retrieving SAML provider: %v\n", err)
}

log.Printf("%s %t", saml.DisplayName, saml.Enabled)
auth.go

Python 

saml = auth.get_saml_provider_config('saml.myProvider')
print(saml.display_name, saml.enabled)
index.py

Java 

SamlProviderConfig saml = FirebaseAuth.getInstance().getSamlProviderConfig("saml.myProvider");
System.out.println(saml.getDisplayName() + ": " + saml.isEnabled());
FirebaseAuthSnippets.java

Se esiste un provider con l'ID specificato, il metodo restituisce un oggetto SAMLAuthProviderConfig.

Eliminazione della configurazione di un provider SAML

L'esempio seguente mostra come eliminare la configurazione di un provider SAML:

Node.js 

admin.auth().deleteProviderConfig('saml.myProvider').then(() => {
  // Successful deletion.
}).catch((error) => {
  // Handle error.
});

Go 

if err := client.DeleteSAMLProviderConfig(ctx, "saml.myProvider"); err != nil {
	log.Fatalf("error deleting SAML provider: %v\n", err)
}
auth.go

Python 

auth.delete_saml_provider_config('saml.myProvider')
index.py

Java 

FirebaseAuth.getInstance().deleteSamlProviderConfig("saml.myProvider");
FirebaseAuthSnippets.java

Elenco delle configurazioni del provider SAML

L'esempio seguente mostra come elencare le configurazioni dei provider SAML esistenti:

Node.js 

// Returns 10 SAML provider configs starting from the specified nextPageToken offset.
admin.auth().listProviderConfigs({type: 'saml', maxResults: 10, pageToken: 'nextPageToken'}).then((results) => {
  results.providerConfigs.forEach((config) => {
    console.log(config.providerId);
  });
  // To list the next 10:
  // return admin.auth().listProviderConfigs(
  //     {type: 'saml', maxResults: 10, pageToken: results.pageToken});
}).catch((error) => {
  // Handle error.
});

Go 

iter := client.SAMLProviderConfigs(ctx, "nextPageToken")
for {
	saml, err := iter.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		log.Fatalf("error retrieving SAML providers: %v\n", err)
	}

	log.Printf("%s\n", saml.ID)
}
auth.go

Python 

for saml in auth.list_saml_provider_configs('nextPageToken').iterate_all():
    print(saml.provider_id)
index.py

Java 

ListProviderConfigsPage<SamlProviderConfig> page = FirebaseAuth.getInstance()
    .listSamlProviderConfigs("nextPageToken");
for (SamlProviderConfig config : page.iterateAll()) {
  System.out.println(config.getProviderId());
}
FirebaseAuthSnippets.java

Ogni batch di risultati contiene un elenco di configurazioni di provider e un token della pagina successiva utilizzato per recuperare il batch successivo. Quando sono elencati tutti i provider, non viene restituito alcun token.

Per impostazione predefinita, vengono restituiti 100 provider per gruppo. Corrisponde anche al numero massimo di provider per batch.

Collaborare con i fornitori OIDC

Creazione della configurazione di un provider OIDC

Quando crei una configurazione del provider OIDC, dovrai fornire i seguenti parametri. Potrebbe essere necessario consultare la documentazione del provider di identità per i dettagli su come ottenere alcuni valori.

Nome visualizzato
Un nome visualizzato intuitivo per la configurazione. Questo nome è anche l'etichetta del provider nella console Google Cloud.
Abilitato
Indica se la configurazione attuale del provider è abilitata o meno. Gli utenti non possono accedere con i provider disattivati.
ID provider
L'identificatore univoco del fornitore, che inizia con oidc..
ID client
L'ID utilizzato per confermare il pubblico del token ID di un provider OIDC.
Client secret
Il client secret richiesto per abilitare il flusso del codice OIDC.
Emittente
Issuer del fornitore. Dovrebbe essere simile a https://example.com. Identity Platform utilizza questo URL per individuare il documento di rilevamento OIDC (in genere disponibile all'indirizzo /.well-known/openid-configuration), che specifica gli endpoint OAuth e le chiavi pubbliche del provider. Identity Platform convalida i token ID in base alla specifica di OpenID Connect. Se il tuo provider non è conforme alla specifica OIDC per il rilevamento, non funzionerà con Identity Platform.
Tipo di risposta
Il tipo di risposta del provider per il flusso di autorizzazione OAuth. Puoi impostare uno dei seguenti valori: {idToken, code} su true, non entrambi. Se il flusso del codice è abilitato, devi fornire un client secret.

L'esempio seguente mostra come creare una configurazione del provider OIDC che utilizza il flusso di autorizzazione implicita:

Node.js 

const newConfig = {
  displayName: 'OIDC provider name',
  enabled: true,
  clientId: 'CLIENT_ID2',
  issuer: 'https://oidc.com/CLIENT_ID2',
  providerId: 'oidc.provider2',
  responseType: {
    idToken: true,
    code: false,
  },
};
admin.auth().createProviderConfig(newConfig).then(() => {
  // Successful creation.
}).catch((error) => {
  // Handle error.
});

Go 

newConfig := (&auth.OIDCProviderConfigToCreate{}).
	DisplayName("OIDC provider name").
	Enabled(true).
	ID("oidc.myProvider").
	ClientID("CLIENT_ID2").
	Issuer("https://oidc.com/CLIENT_ID2")
oidc, err := client.CreateOIDCProviderConfig(ctx, newConfig)
if err != nil {
	log.Fatalf("error creating OIDC provider: %v\n", err)
}

log.Printf("Created new OIDC provider: %s", oidc.ID)
auth.go

Python 

oidc = auth.create_oidc_provider_config(
    display_name='OIDC provider name',
    enabled=True,
    provider_id='oidc.myProvider',
    client_id='CLIENT_ID2',
    issuer='https://oidc.com/CLIENT_ID2')

print('Created new OIDC provider:', oidc.provider_id)
index.py

Java 

OidcProviderConfig.CreateRequest request = new OidcProviderConfig.CreateRequest()
    .setDisplayName("OIDC provider name")
    .setEnabled(true)
    .setProviderId("oidc.myProvider")
    .setClientId("CLIENT_ID2")
    .setIssuer("https://oidc.com/CLIENT_ID2");
OidcProviderConfig oidc = FirebaseAuth.getInstance().createOidcProviderConfig(request);
System.out.println("Created new OIDC provider: " + oidc.getProviderId());
FirebaseAuthSnippets.java

Al termine, il metodo restituisce un oggetto OIDCAuthProviderConfig per la configurazione appena creata.

Aggiornamento della configurazione di un provider OIDC

L'esempio seguente mostra come modificare la configurazione di un provider OIDC. Puoi aggiornare qualsiasi campo, ad eccezione dell'ID provider.

Node.js 

const updatedConfig = {
  displayName: 'OIDC provider name',
  enabled: true,
  clientId: 'CLIENT_ID',
  clientSecret: 'CLIENT_SECRET'
  issuer: 'https://oidc.com/',
  responseType: {
    code: true,
    idToken: false,
  },
};
admin.auth().updateProviderConfig('oidc.myProvider', updatedConfig).then(() => {
  // Successful update.
}).catch((error) => {
  // Handle error.
});

Go 

updatedConfig := (&auth.OIDCProviderConfigToUpdate{}).
	DisplayName("OIDC provider name").
	Enabled(true).
	ClientID("CLIENT_ID").
	Issuer("https://oidc.com")
oidc, err := client.UpdateOIDCProviderConfig(ctx, "oidc.myProvider", updatedConfig)
if err != nil {
	log.Fatalf("error updating OIDC provider: %v\n", err)
}

log.Printf("Updated OIDC provider: %s", oidc.ID)
auth.go

Python 

oidc = auth.update_oidc_provider_config(
    'oidc.myProvider',
    client_id='CLIENT_ID',
    issuer='https://oidc.com')

print('Updated OIDC provider:', oidc.provider_id)
index.py

Java 

OidcProviderConfig.UpdateRequest request =
    new OidcProviderConfig.UpdateRequest("oidc.myProvider")
        .setDisplayName("OIDC provider name")
        .setEnabled(true)
        .setClientId("CLIENT_ID")
        .setIssuer("https://oidc.com");
OidcProviderConfig oidc = FirebaseAuth.getInstance().updateOidcProviderConfig(request);
System.out.println("Updated OIDC provider: " + oidc.getProviderId());
FirebaseAuthSnippets.java

Al termine, il metodo restituisce un oggetto OIDCAuthProviderConfig per la configurazione aggiornata.

Recupero della configurazione di un provider OIDC

Il modo principale per identificare una configurazione OIDC è utilizzare il suo ID provider. L'esempio seguente mostra come ottenere la configurazione di un provider OIDC:

Node.js 

admin.auth().getProviderConfig('oidc.myProvider').then((config) => {
  // Get display name and whether it is enabled.
  console.log(config.displayName, config.enabled);
}).catch((error) => {
  // Handle error. Common error is that config is not found.
});

Go 

oidc, err := client.OIDCProviderConfig(ctx, "oidc.myProvider")
if err != nil {
	log.Fatalf("error retrieving OIDC provider: %v\n", err)
}

log.Printf("%s %t", oidc.DisplayName, oidc.Enabled)
auth.go

Python 

oidc = auth.get_oidc_provider_config('oidc.myProvider')

print(oidc.display_name, oidc.enabled)
index.py

Java 

OidcProviderConfig oidc = FirebaseAuth.getInstance().getOidcProviderConfig("oidc.myProvider");
System.out.println(oidc.getDisplayName() + ": " + oidc.isEnabled());
FirebaseAuthSnippets.java

Se esiste un provider con l'ID specificato, il metodo restituisce un oggetto OIDCAuthProviderConfig.

Eliminazione della configurazione di un provider OIDC

L'esempio seguente mostra come eliminare la configurazione di un provider OIDC:

Node.js 

admin.auth().deleteProviderConfig('oidc.myProvider').then(() => {
  // Successful deletion.
}).catch((error) => {
  // Handle error.
});

Go 

if err := client.DeleteOIDCProviderConfig(ctx, "oidc.myProvider"); err != nil {
	log.Fatalf("error deleting OIDC provider: %v\n", err)
}
auth.go

Python 

auth.delete_oidc_provider_config('oidc.myProvider')
index.py

Java 

FirebaseAuth.getInstance().deleteOidcProviderConfig("oidc.myProvider");
FirebaseAuthSnippets.java

Elenco delle configurazioni del provider OIDC

L'esempio seguente mostra come elencare le configurazioni di provider OIDC esistenti:

Node.js 

// Returns 10 OIDC provider configs starting from the specified nextPageToken offset.
admin.auth().listProviderConfigs({type: 'oidc', maxResults: 10, pageToken: 'nextPageToken'}).then((results) => {
  results.providerConfigs.forEach((config) => {
    console.log(config.providerId);
  });
  // To list the next 10:
  // return admin.auth().listProviderConfigs(
  //     {type: 'oidc', maxResults: 10, pageToken: results.pageToken});
}).catch((error) => {
  // Handle error.
});

Go 

iter := client.OIDCProviderConfigs(ctx, "nextPageToken")
for {
	oidc, err := iter.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		log.Fatalf("error retrieving OIDC providers: %v\n", err)
	}

	log.Printf("%s\n", oidc.ID)
}
auth.go

Python 

for oidc in auth.list_oidc_provider_configs('nextPageToken').iterate_all():
    print(oidc.provider_id)
index.py

Java 

ListProviderConfigsPage<OidcProviderConfig> page = FirebaseAuth.getInstance()
    .listOidcProviderConfigs("nextPageToken");
for (OidcProviderConfig oidc : page.iterateAll()) {
  System.out.println(oidc.getProviderId());
}
FirebaseAuthSnippets.java

Ogni batch di risultati contiene un elenco di configurazioni di provider e un token della pagina successiva utilizzato per recuperare il batch successivo. Quando sono elencati tutti i provider, non viene restituito alcun token.

Per impostazione predefinita, vengono restituiti 100 provider per gruppo. Corrisponde anche al numero massimo di provider per batch.

Passaggi successivi