Gestione programmatica dei provider SAML e OIDC
Questo documento mostra come utilizzare l'SDK Admin Platform di Identity Platform per gestire le configurazioni del provider SAML (Security Assertion Markup Language) 2.0 e OpenID Connect (OIDC) in modo programmatico.
Utilizzando l'SDK Admin, puoi configurare automaticamente i provider, eseguire operazioni CRUD di base, ruotare i certificati e altro ancora. Questa soluzione è utile se hai un numero elevato di provider che potrebbero gestire manualmente manualmente la console.
Prima di iniziare
Collaborare con provider SAML
Creazione di una configurazione del provider SAML
Quando crei una configurazione di un provider SAML, devi fornire i seguenti parametri. Potrebbe essere necessario consultare la documentazione del provider di identità per ulteriori dettagli su come ottenere alcuni valori.
- Nome visualizzato
- Un nome visualizzato facile da usare per la configurazione. Questo nome è anche l'etichetta del provider nella console.
- Abilitato
- Indica se la configurazione del fornitore attuale è abilitata o disabilitata. Gli utenti non possono accedere con fornitori disattivati.
- ID provider
-
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 fornitore. L'URL deve essere valido.
- Certificati X.509
-
Un elenco di certificati X.509 del provider SAML, incluse le stringhe
-----BEGIN CERTIFICATE-----
e-----END CERTIFICATE----
. che vengono utilizzati per la firma del token nel provider di identità.Quando Identity Platform riceve una risposta SAML, verifica la propria firma utilizzando un certificato registrato. Se la verifica non va a buon fine, 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à della parte che si basa su SAML (RP/SP). Questo è in genere l'URL dell'app. Nel provider di identità SAML, si parla in questo caso di pubblico.
- URL di callback
-
L'URL a cui tornare una volta completata l'autenticazione. I provider SAML in genere fanno riferimento a questo URL come all'URL ACS (Assertion Consumer Service). Dovrai registrare questo URL presso il provider SAML. Dovrebbe avere un aspetto simile a
https://PROJECT-ID.firebaseapp.com/__/auth/handler
, simile a quello degli URL visualizzati nella console. Per saperne di più, vedi Accesso degli 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 progetto sia configurato correttamente con il tuo provider di identità SAML. In genere, 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)
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)
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, tranne l'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)
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)
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 suo 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)
Python
saml = auth.get_saml_provider_config('saml.myProvider') print(saml.display_name, saml.enabled)
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 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) }
Python
auth.delete_saml_provider_config('saml.myProvider')
Elenco delle configurazioni del provider SAML
L'esempio seguente mostra come elencare le configurazioni del 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) }
Python
for saml in auth.list_saml_provider_configs('nextPageToken').iterate_all(): print(saml.provider_id)
Ogni batch di risultati contiene un elenco di configurazioni del provider e un token di pagina successivo utilizzato per recuperare il batch successivo. Quando tutti i provider sono elencati, non viene restituito alcun token.
Per impostazione predefinita, vengono restituiti 100 provider per ogni batch. Corrisponde anche al numero massimo di provider per batch.
Collaborare con i provider OIDC
Creazione di una configurazione del provider OIDC
Quando crei una configurazione del provider OIDC, devi fornire i seguenti parametri. Potrebbe essere necessario consultare la documentazione del provider di identità per ulteriori dettagli su come ottenere alcuni valori.
- Nome visualizzato
- Un nome visualizzato facile da usare per la configurazione. Questo nome è anche l'etichetta del provider nella console.
- Abilitato
- Indica se la configurazione del fornitore attuale è abilitata o disabilitata. Gli utenti non possono accedere con fornitori disattivati.
- ID provider
-
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 di codice OIDC.
- Emittente
-
Issuer
del provider. Dovrebbe avere un formato simile ahttps://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 dei valori di {
idToken
,code
} sutrue
, non su 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.
});
Java
OidcProviderConfig.CreateRequest request
= new OidcProviderConfig.CreateRequest()
.setDisplayName("OIDC provider name")
.setEnabled(true)
.setProviderId("oidc.provider2")
.setClientId("CLIENT_ID2")
.setIssuer("https://oidc.com/CLIENT_ID2")
.setIdTokenResponseType(true)
.setCodeResponseType(false);
OidcProviderConfig oidc
= FirebaseAuth.getInstance().createOidcProviderConfig(request);
System.out.println("Created new OIDC provider: " + oidc.getProviderId());
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)
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)
Al termine, il metodo restituisce un oggetto
OIDCAuthProviderConfig
per la configurazione appena creata.
Aggiornamento di una configurazione del provider OIDC
L'esempio seguente mostra come modificare la configurazione di un provider OIDC. Puoi aggiornare qualsiasi campo, tranne l'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.
});
Java
OidcProviderConfig.UpdateRequest request
= new OidcProviderConfig.UpdateRequest("oidc.myProvider")
.setDisplayName("OIDC provider name")
.setEnabled(true)
.setClientId("CLIENT_ID")
.setClientSecret("CLIENT_SECRET")
.setIssuer("https://oidc.com/")
.setCodeResponseType(true);
OidcProviderConfig oidc
= FirebaseAuth.getInstance().updateOidcProviderConfig(request);
System.out.println("Updated OIDC provider: " + oidc.getProviderId());
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)
Python
oidc = auth.update_oidc_provider_config( 'oidc.myProvider', client_id='CLIENT_ID', issuer='https://oidc.com') print('Updated OIDC provider:', oidc.provider_id)
Al termine, il metodo restituisce un oggetto
OIDCAuthProviderConfig
per la configurazione aggiornata.
Recupero di una configurazione del provider OIDC
Il modo principale per identificare una configurazione OIDC è utilizzare il suo 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)
Python
oidc = auth.get_oidc_provider_config('oidc.myProvider') print(oidc.display_name, oidc.enabled)
Se esiste un provider con l'ID specificato, il metodo restituisce un oggetto
OIDCAuthProviderConfig
.
Eliminazione di una configurazione del 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) }
Python
auth.delete_oidc_provider_config('oidc.myProvider')
Elenco delle configurazioni del provider OIDC
L'esempio seguente mostra come elencare le configurazioni del 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) }
Python
for oidc in auth.list_oidc_provider_configs('nextPageToken').iterate_all(): print(oidc.provider_id)
Ogni batch di risultati contiene un elenco di configurazioni del provider e un token di pagina successivo utilizzato per recuperare il batch successivo. Quando tutti i provider sono elencati, non viene restituito alcun token.
Per impostazione predefinita, vengono restituiti 100 provider per ogni batch. Corrisponde anche al numero massimo di provider per batch.
Passaggi successivi
- Eseguire la migrazione degli utenti da un'app esistente.
- Consenti l'accesso agli utenti con SAML e OIDC.