Gestionar proveedores de SAML y OIDC de forma programática

En este documento se explica cómo usar el SDK de administrador de Identity Platform para gestionar de forma programática las configuraciones de proveedores de lenguaje de marcado para confirmaciones de seguridad (SAML) 2.0 y OpenID Connect (OIDC).

Con el SDK de administrador, puedes configurar proveedores, llevar a cabo operaciones CRUD básicas y rotar certificados de forma automática, entre otras tareas. Esto resulta útil cuando tienes un gran número de proveedores que sería engorroso gestionar manualmente con la consola de Google Cloud .

Antes de empezar

Trabajar con proveedores de SAML

Crear una configuración de proveedor de SAML

Deberá proporcionar los siguientes parámetros al crear una configuración de proveedor de SAML. Puede que tengas que consultar la documentación de tu proveedor de identidades para obtener información sobre cómo obtener algunos de los valores.

Nombre visible
Nombre visible de la configuración fácil de usar. Este nombre también es la etiqueta del proveedor en la Google Cloud consola.
Habilitado
Indica si la configuración del proveedor actual está habilitada o inhabilitada. Los usuarios no pueden iniciar sesión con proveedores inhabilitados.
ID de proveedor
Identificador único del proveedor, que empieza por saml..
ID de entidad del proveedor de identidades
ID de entidad del proveedor.
URL de inicio de sesión único
La URL de inicio de sesión único (SSO) basado en SAML del proveedor. La URL debe ser válida.
Certificados X.509

Una lista de certificados X.509 de proveedores de SAML, incluidas las cadenas -----BEGIN CERTIFICATE----- y -----END CERTIFICATE----. Se usan para firmar tokens en el proveedor de identidades.

Cuando Identity Platform recibe una respuesta SAML, verifica su firma mediante un certificado registrado. Si no se puede verificar, la respuesta se rechazará. Tendrás que actualizar estos certificados a medida que se roten las claves. Te recomendamos que subas varios certificados para evitar interrupciones durante las rotaciones.

ID de entidad de la parte que transfiere
El ID de entidad de la parte de confianza (RP/SP) de SAML. Normalmente, se trata de la URL de la aplicación. En el proveedor de identidades SAML, se denomina "audiencia".
URL de retrollamada

La URL a la que se debe volver cuando se complete la autenticación. Los proveedores de SAML suelen referirse a esta URL como URL del servicio de consumidor de aserciones (ACS). Deberás registrar esta URL con el proveedor de SAML. Debería ser similar a https://PROJECT-ID.firebaseapp.com/__/auth/handler, como las URLs que se muestran en la consola Google Cloud . Para obtener más información, consulta el artículo Inicio de sesión de usuarios con SAML.

Si usas la URL de retrollamada predeterminada, se reducirá la complejidad de validar las respuestas SAML. Sin embargo, también puedes mostrar un dominio personalizado. En este caso, asegúrate de que la URL de retrollamada de Identity Platform de tu proyecto esté configurada correctamente con tu proveedor de identidades SAML. Normalmente, tiene un aspecto similar a este: https://AUTH-DOMAIN/__/auth/handler.

En el siguiente ejemplo se muestra cómo crear una configuración de proveedor de 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());

Cuando se completa, el método devuelve un objeto SAMLAuthProviderConfig para la configuración recién creada.

Actualizar la configuración de un proveedor de SAML

En el siguiente ejemplo se muestra cómo modificar la configuración de un proveedor de SAML. Puedes actualizar cualquier campo, excepto el ID de proveedor.

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

Una vez completado, el método devuelve un objeto SAMLAuthProviderConfig para la configuración actualizada.

Obtener la configuración de un proveedor de SAML

La forma principal de identificar una configuración de SAML es mediante su ID de proveedor. En el siguiente ejemplo se muestra cómo obtener una configuración de proveedor de 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());

Si existe un proveedor con el ID indicado, el método devuelve un objeto SAMLAuthProviderConfig.

Eliminar una configuración de proveedor de SAML

En el siguiente ejemplo se muestra cómo eliminar una configuración de proveedor de 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");

Mostrar las configuraciones de proveedores de SAML

En el siguiente ejemplo se muestra cómo enumerar las configuraciones de proveedores de SAML:

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

Cada lote de resultados contiene una lista de configuraciones de proveedores y un token de página siguiente que se usa para obtener el siguiente lote. Cuando se hayan enumerado todos los proveedores, no se devolverá ningún token.

De forma predeterminada, se devuelven 100 proveedores en cada lote. Este es también el número máximo de proveedores por lote.

Trabajar con proveedores de OIDC

Crear una configuración de proveedor de OIDC

Deberá proporcionar los siguientes parámetros al crear una configuración de proveedor de OIDC. Puede que tengas que consultar la documentación de tu proveedor de identidades para obtener información sobre cómo obtener algunos de los valores.

Nombre visible
Nombre visible de la configuración fácil de usar. Este nombre también es la etiqueta del proveedor en la Google Cloud consola.
Habilitado
Indica si la configuración del proveedor actual está habilitada o inhabilitada. Los usuarios no pueden iniciar sesión con proveedores inhabilitados.
ID de proveedor
Identificador único del proveedor, que empieza por oidc..
ID de cliente
ID usado para confirmar la audiencia del token de ID de un proveedor de OIDC.
Secreto de cliente
El secreto de cliente necesario para habilitar el flujo de código OIDC.
Emisor
El Issuer del proveedor. Debería ser algo parecido a esto: https://example.com. Identity Platform usa esta URL para localizar el documento de Discovery de OIDC (que suele encontrarse en /.well-known/openid-configuration), que especifica los endpoints de OAuth y las claves públicas del proveedor. Identity Platform valida los tokens de ID de acuerdo con la especificación de OpenID Connect. Si tu proveedor no cumple la especificación de OIDC para el descubrimiento, no funcionará con Identity Platform.
Tipo de respuesta
Tipo de respuesta del proveedor para el flujo de autorización de OAuth. Puedes asignar el valor true a uno de los elementos {idToken, code}, pero no a ambos. Si el flujo de código está habilitado, debes proporcionar un secreto de cliente.

En el siguiente ejemplo se muestra cómo crear una configuración de proveedor de OIDC que use el flujo de autorización implícito:

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

Cuando se completa, el método devuelve un objeto OIDCAuthProviderConfig de la configuración recién creada.

Actualizar la configuración de un proveedor de OIDC

En el siguiente ejemplo se muestra cómo modificar la configuración de un proveedor de OIDC. Puedes actualizar cualquier campo, excepto el ID de proveedor.

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

Cuando se completa, el método devuelve un objeto OIDCAuthProviderConfig para la configuración actualizada.

Obtener la configuración de un proveedor de OIDC

La forma principal de identificar una configuración de OIDC es mediante su ID de proveedor. En el siguiente ejemplo se muestra cómo obtener la configuración de un proveedor de 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());

Si existe un proveedor con el ID indicado, el método devuelve un objeto OIDCAuthProviderConfig.

Eliminar la configuración de un proveedor de OIDC

En el siguiente ejemplo se muestra cómo eliminar una configuración de proveedor de 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");

Mostrar las configuraciones de proveedores de OIDC

En el siguiente ejemplo se muestra cómo enumerar las configuraciones de proveedores de OIDC:

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

Cada lote de resultados contiene una lista de configuraciones de proveedores y un token de página siguiente que se usa para obtener el siguiente lote. Cuando se hayan enumerado todos los proveedores, no se devolverá ningún token.

De forma predeterminada, se devuelven 100 proveedores en cada lote. Este es también el número máximo de proveedores por lote.

Siguientes pasos