Questa pagina è stata tradotta dall'API Cloud Translation.

Gestione programmatica dei provider SAML e OIDC

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

Con l'SDK Admin, puoi configurare automaticamente i provider, eseguire operazioni CRUD di base, ruotare i certificati e altro ancora. È utile quando avere un gran numero di provider che sarebbe difficile gestire manualmente utilizzando la console Google Cloud.

Prima di iniziare

Lavorare con i provider SAML

Creazione di una configurazione del provider SAML

Quando crei una configurazione del provider SAML, devi fornire i seguenti parametri. Potresti dover consultare la documentazione del tuo provider di identità per informazioni dettagliate su come ottenere alcuni valori.

Nome visualizzato

Un nome visualizzato semplice per la configurazione. Questo nome è anche l'etichetta del provider nella console Google Cloud.

Abilitato

Se la configurazione del fornitore attuale è abilitata o disattivata. Gli utenti non possono accedere con provider disabilitati.

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 SSO SAML del provider. L'URL deve essere valido.

Certificati X.509

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

Quando Identity Platform riceve una risposta SAML, ne verifica 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 di servizio durante le rotazioni.

ID entità della parte di inoltro

L'ID entità della terza parte attendibile (RP/SP) SAML. Di solito è l'URL dell'app. Nel provider di identità SAML, viene chiamato pubblico.

URL di callback

L'URL da tornare al completamento dell'autenticazione. I fornitori SAML solitamente fanno riferimento a questo come all'URL Assertion Consumer Service (ACS). Dovrai registrare questo URL con il provider SAML. Dovrebbe avere un aspetto simile a questo: https://PROJECT-ID.firebaseapp.com/__/auth/handler, simile agli URL visualizzati nella console Google Cloud. Per apprendere Per saperne di più, consulta la sezione Come eseguire l'accesso con SAML.

L'utilizzo dell'URL di callback predefinito riduce la complessità della convalida delle risposte SAML. Tuttavia, puoi anche scegliere di mostrare dominio personalizzato. In questo caso, assicurati che l'URL di callback di Identity Platform per il progetto sia configurato correttamente con la tua identità SAML o il provider di servizi di terze parti. In genere, ha un aspetto simile a questo: 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 di una configurazione del provider SAML

Il modo principale per identificare una configurazione SAML è utilizzare il relativo ID provider. L'esempio seguente mostra come ottenere una configurazione del 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 SAMLAuthProviderConfig .

Eliminazione di una configurazione del provider SAML

L'esempio seguente mostra come eliminare una configurazione del 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 del provider e di pagina usato per recuperare il batch successivo. Quando sono stati elencati tutti i fornitori, non viene restituito alcun token.

Per impostazione predefinita, con ogni batch vengono restituiti 100 fornitori. Questo è anche il numero massimo di provider per batch.

Utilizzo dei provider OIDC

Creazione di una configurazione del provider OIDC

Quando crei una configurazione del provider OIDC, devi fornire i seguenti parametri. Potresti dover consultare la documentazione del tuo provider di identità per informazioni dettagliate su come ottenere alcuni valori.

Nome visualizzato: Un nome visualizzato semplice per la configurazione. Questo nome è anche l'etichetta del provider nella console Google Cloud.
Abilitato: Se la configurazione del fornitore attuale è abilitata o disattivata. Gli utenti non possono accedere con provider disabilitati.
ID provider: L'identificatore univoco del fornitore, che inizia con oidc..
ID client: L'ID utilizzato per confermare il pubblico di un provider OIDC token ID.
Client secret: Il client secret necessario per attivare il flusso di codice OIDC.
Emittente: Issuerdel fornitore. Dovrebbe avere un aspetto simile a questo: 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 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 tra {idToken, code} e true, non entrambi. Se il flusso di 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 completamento, il metodo restituisce un OIDCAuthProviderConfig per la configurazione appena creata.

Aggiornamento di una configurazione del provider OIDC

L'esempio seguente mostra come modificare una configurazione del 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.

Ottenere una configurazione del provider OIDC

Il modo principale per identificare una configurazione OIDC è utilizzare l'ID provider. L'esempio seguente mostra come ottenere una configurazione del 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 fornitore con l'ID specificato, il metodo restituisce un oggetto OIDCAuthProviderConfig.

Eliminazione di una configurazione del provider OIDC

L'esempio seguente mostra come eliminare una configurazione del 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 dei provider OIDC

L'esempio seguente mostra come elencare le configurazioni dei 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 del provider e un token di pagina successiva utilizzato per recuperare il batch successivo. Se tutti i fornitori sono stati elencati, viene restituito.

Per impostazione predefinita, a ogni batch vengono restituiti 100 provider. Questo è anche il numero massimo di provider per batch.

Passaggi successivi

Eseguire la migrazione degli utenti da un'app esistente.
Accesso degli utenti con SAML e OIDC.