Gérer les fournisseurs SAML et OIDC par programmation

Ce document explique comment utiliser le SDK Admin Identity Platform pour gérer les configurations de fournisseur SAML (Security Assertion Markup Language) 2.0 et OIDC (OpenID Connect) par programmation.

À l'aide du SDK Admin, vous pouvez configurer automatiquement des fournisseurs, effectuer des opérations CRUD de base, alterner des certificats, etc. Cela s'avère utile lorsque vous avez un grand nombre de fournisseurs qu'il peut être fastidieux de gérer manuellement à l'aide de la console Google Cloud.

Avant de commencer

Travailler avec des fournisseurs SAML

Créer une configuration de fournisseur SAML

Vous devez fournir les paramètres suivants lors de la création d'une configuration de fournisseur SAML. Consultez la documentation de votre fournisseur d'identité pour savoir comment obtenir certaines valeurs.

Nom à afficher
Nom à afficher convivial pour la configuration. Ce nom est également le libellé du fournisseur dans la console Google Cloud.
Activé
Indique si la configuration actuelle du fournisseur est activée ou désactivée. Les utilisateurs ne peuvent pas se connecter avec des fournisseurs désactivés.
ID du fournisseur
Identifiant unique du fournisseur, commençant par saml..
ID d'entité du fournisseur d'identité
ID d'entité du fournisseur.
URL d'authentification unique
URL SSO SAML pour le fournisseur. L'URL doit être valide.
Certificats X.509

Liste des certificats X.509 du fournisseur SAML, y compris les chaînes -----BEGIN CERTIFICATE----- et -----END CERTIFICATE----. Celles-ci sont utilisées pour la signature des jetons sur le fournisseur d'identité.

Lorsque Identity Platform reçoit une réponse SAML, il vérifie sa signature à l'aide d'un certificat enregistré. Si la validation échoue, la réponse sera rejetée. Vous devrez mettre à jour ces certificats à mesure que les clés sont alternées. Pensez à importer plusieurs certificats pour éviter les interruptions lors des rotations.

Relayer l'ID d'entité de groupe
ID d'entité du tiers de confiance SAML (RP/SP). Il s'agit généralement de l'URL de l'application. Dans le fournisseur d'identité SAML, on parle alors d'audience.
URL de rappel

URL à renvoyer une fois l'authentification terminée. Les fournisseurs SAML font généralement référence à cette URL sous forme d'URL du service ACS (Assertion Consumer Service). Vous devez enregistrer cette URL auprès du fournisseur SAML. L'URL doit ressembler à https://PROJECT-ID.firebaseapp.com/__/auth/handler, comme les URL affichées dans la console Google Cloud. Pour en savoir plus, consultez la section Procéder à la connexion des utilisateurs avec SAML.

L'utilisation de l'URL de rappel par défaut réduit la complexité de validation des réponses SAML. Toutefois, vous pouvez également choisir d'afficher un domaine personnalisé. Dans ce cas, assurez-vous que l'URL de rappel d'Identity Platform pour votre projet est correctement configurée avec votre fournisseur d'identité SAML. Elle ressemble généralement à ceci : https://AUTH-DOMAIN/__/auth/handler.

L'exemple suivant montre comment créer une configuration de fournisseur 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)

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());

Une fois l'opération terminée, la méthode renvoie un objet SAMLAuthProviderConfig pour la nouvelle configuration.

Mettre à jour une configuration de fournisseur SAML

L'exemple suivant montre comment modifier la configuration d'un fournisseur SAML. Vous pouvez mettre à jour n'importe quel champ, à l'exception de l'ID du fournisseur.

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)

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());

Une fois l'opération terminée, la méthode renvoie un objet SAMLAuthProviderConfig pour la configuration mise à jour.

Obtenir une configuration de fournisseur SAML

Le principal moyen d'identifier une configuration SAML consiste à utiliser son ID de fournisseur. L'exemple suivant montre comment obtenir une configuration de fournisseur 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)

Java

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

S'il existe un fournisseur possédant l'ID spécifié, la méthode renvoie un objet SAMLAuthProviderConfig.

Supprimer une configuration de fournisseur SAML

L'exemple suivant montre comment supprimer une configuration de fournisseur 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')

Java

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

Répertorier les configurations de fournisseur SAML

L'exemple suivant montre comment répertorier les configurations de fournisseur SAML existantes :

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)

Java

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

Chaque lot de résultats contient une liste de configurations de fournisseur, ainsi qu'un jeton de page suivante permettant de récupérer le lot suivant. Lorsque tous les fournisseurs sont répertoriés, aucun jeton n'est renvoyé.

Par défaut, 100 fournisseurs sont renvoyés avec chaque lot. Il s'agit également du nombre maximal de fournisseurs par lot.

Travailler avec des fournisseurs OIDC

Créer une configuration de fournisseur OIDC

Vous devez fournir les paramètres suivants lors de la création d'une configuration de fournisseur OIDC. Consultez la documentation de votre fournisseur d'identité pour savoir comment obtenir certaines valeurs.

Nom à afficher
Nom à afficher convivial pour la configuration. Ce nom est également le libellé du fournisseur dans la console Google Cloud.
Activé
Indique si la configuration actuelle du fournisseur est activée ou désactivée. Les utilisateurs ne peuvent pas se connecter avec des fournisseurs désactivés.
ID du fournisseur
Identifiant unique du fournisseur, commençant par oidc..
ID client
ID utilisé pour confirmer l'audience du jeton d'ID d'un fournisseur OIDC.
Code secret du client
Code secret du client, requis pour activer le flux de code OIDC.
Émetteur
Issuer du fournisseur. L'URL ressemble généralement à ceci : https://example.com. Identity Platform utilise cette URL pour localiser le document de découverte OIDC (généralement situé dans /.well-known/openid-configuration), qui spécifie les points de terminaison OAuth et les clés publiques du fournisseur. Identity Platform valide les jetons d'identification conformément à la spécification OpenID Connect. Si votre fournisseur ne respecte pas la spécification OIDC pour la découverte, il ne fonctionnera pas avec Identity Platform.
Type de réponse
Type de réponse du fournisseur pour le flux d'autorisation OAuth. Vous pouvez définir l'une des valeurs {idToken, code} sur true, mais pas les deux. Si le flux de code est activé, vous devez fournir un "code secret du client".

L'exemple suivant montre comment créer une configuration de fournisseur OIDC utilisant le flux d'autorisation implicite :

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)

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)

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());

Une fois l'opération terminée, la méthode renvoie un objet OIDCAuthProviderConfig pour la nouvelle configuration.

Mettre à jour une configuration de fournisseur OIDC

L'exemple suivant montre comment modifier une configuration de fournisseur OIDC. Vous pouvez mettre à jour n'importe quel champ, à l'exception de l'ID du fournisseur.

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)

Python

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

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

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());

Une fois l'opération terminée, la méthode renvoie un objet OIDCAuthProviderConfig pour la configuration mise à jour.

Obtenir la configuration de fournisseur OIDC

Le principal moyen d'identifier une configuration OIDC consiste à utiliser son ID de fournisseur. L'exemple suivant montre comment obtenir une configuration de fournisseur 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)

Java

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

S'il existe un fournisseur ayant l'ID spécifié, la méthode renvoie un objet OIDCAuthProviderConfig.

Supprimer une configuration de fournisseur OIDC

L'exemple suivant montre comment supprimer une configuration de fournisseur 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')

Java

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

Répertorier les configurations de fournisseur OIDC

L'exemple suivant montre comment répertorier les configurations de fournisseur OIDC existantes :

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)

Java

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

Chaque lot de résultats contient une liste de configurations de fournisseur, ainsi qu'un jeton de page suivante permettant de récupérer le lot suivant. Lorsque tous les fournisseurs sont répertoriés, aucun jeton n'est renvoyé.

Par défaut, 100 fournisseurs sont renvoyés avec chaque lot. Il s'agit également du nombre maximal de fournisseurs par lot.

Étapes suivantes