Administrar proveedores SAML y OIDC de manera programática

En este documento, se muestra cómo usar el SDK de Admin de Identity Platform para administrar de forma programática las opciones de configuración del proveedor de lenguaje de marcado para confirmaciones de seguridad (SAML) 2.0 y OpenID Connect (OIDC).

Con el SDK de Admin, puedes configurar proveedores automáticamente, realizar operaciones CRUD básicas, rotar certificados y mucho más. Esto es útil cuando tienes una gran cantidad de proveedores que sería complicado administrar de forma manual con la consola de Google Cloud.

Antes de comenzar

Trabaja con proveedores de SAML

Crea una configuración de proveedor de SAML

Deberás proporcionar los siguientes parámetros cuando crees una configuración del proveedor de SAML. Es posible que debas consultar la documentación de tu proveedor de identidad para obtener detalles sobre cómo obtener algunos de los valores.

Nombre visible
Un nombre visible fácil de usar para la configuración. Este nombre también es la etiqueta de proveedor en la consola de Google Cloud.
Habilitado
Determina si la configuración del proveedor actual está habilitada o inhabilitada. Los usuarios no pueden acceder con proveedores inhabilitados.
ID del proveedor
Es el identificador único del proveedor, que comienza con saml..
ID de entidad del proveedor de identidad
Es el ID de entidad del proveedor.
URL de SSO
La URL de SSO de SAML del proveedor. La URL debe ser válida.
Certificados X.509

Una lista de certificados X.509 de SAML, incluidas las strings -----BEGIN CERTIFICATE----- y -----END CERTIFICATE---- Se usan para la firma de tokens en el proveedor de identidad.

Cuando Identity Platform recibe una respuesta SAML, verificará su firma con un certificado registrado. Si la verificación falla, se rechazará la respuesta. Deberás actualizar estos certificados a medida que se rotan las claves. Considera subir varios certificados para evitar interrupciones durante las rotaciones.

ID de entidad del grupo de retransmisión
ID de entidad de confianza de la parte de SAML (RP/SP). Esta suele ser la URL de la app. En el proveedor de identidad de SAML, se denomina público.
URL de devolución de llamada

La URL a la que se debe regresar cuando se complete la autenticación. Los proveedores de SAML suelen hacer referencia a esto como la URL de servicio de consumidor de aserciones (ACS). Deberá registrar esta URL con el proveedor de SAML. Debería verse como https://PROJECT-ID.firebaseapp.com/__/auth/handler, similar a las URLs que se muestran en la consola de Google Cloud. Para obtener más información, consulta Cómo acceder a usuarios con SAML.

Usar la URL de devolución de llamada predeterminada disminuirá la complejidad de validar respuestas de SAML. Sin embargo, también puedes elegir mostrar un dominio personalizado. En este caso, asegúrate de que la URL de devolución de llamada de Identity Platform para tu proyecto esté configurada correctamente con tu proveedor de identidad de SAML. Por lo general, se parece a 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 finaliza, el método muestra un objeto SAMLAuthProviderConfig para la configuración recién creada.

Actualiza una configuración de 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());

Al finalizar, el método muestra un objeto SAMLAuthProviderConfig para la configuración actualizada.

Obtén una configuración de proveedor de SAML

El método principal para identificar una configuración SAML es usar 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 determinado, el método muestra un objeto SAMLAuthProviderConfig.

Borra una configuración de proveedor de SAML

En el siguiente ejemplo, se muestra cómo borrar 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");

Cómo mostrar una lista de las opciones de configuración del proveedor de SAML

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

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 opciones de configuración del usuario y un token de página siguiente que se usa para recuperar el siguiente lote. Cuando se enumeran todos los proveedores, no se muestra ningún token.

De forma predeterminada, se muestran 100 proveedores con cada lote. Esta es también la cantidad máxima de proveedores por lote.

Trabaja con proveedores de OIDC

Crea una configuración de proveedor de OIDC

Deberás proporcionar los siguientes parámetros cuando crees una configuración de proveedor de OIDC. Es posible que debas consultar la documentación de tu proveedor de identidad para obtener detalles sobre cómo obtener algunos de los valores.

Nombre visible
Un nombre visible fácil de usar para la configuración. Este nombre también es la etiqueta de proveedor en la consola de Google Cloud.
Habilitado
Determina si la configuración del proveedor actual está habilitada o inhabilitada. Los usuarios no pueden acceder con proveedores inhabilitados.
ID del proveedor
Es el identificador único del proveedor, que comienza con oidc..
ID de cliente
Es el ID que se usa para confirmar el público del token de ID de un proveedor de OIDC.
Secreto del cliente
El secreto de cliente necesario para habilitar el flujo de código de OIDC.
Emisor
El Issuer del proveedor. Se verá de la siguiente manera: https://example.com. Identity Platform usa esta URL para ubicar el documento de descubrimiento de OIDC (que se suele encontrar en /.well-known/openid-configuration), que especifica los extremos 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 de OIDC no cumple con la especificación de OIDC para el descubrimiento, no funcionará con Identity Platform.
Tipo de respuesta
El tipo de respuesta del proveedor para el flujo de autorización de OAuth. Puedes configurar una de {idToken, code} como true, no ambas. Si el flujo de código está habilitado, debes proporcionar un secreto del 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 finaliza, el método muestra un objeto OIDCAuthProviderConfig para la configuración recién creada.

Actualiza la configuración de un proveedor de OIDC

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

Al finalizar, el método muestra un objeto OIDCAuthProviderConfig para la configuración actualizada.

Obtén una configuración de proveedor de OIDC

El método principal para identificar una configuración de OIDC usa su ID de proveedor. En el siguiente ejemplo, se muestra cómo obtener una configuración de 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 determinado, el método muestra un objeto OIDCAuthProviderConfig.

Borra una configuración de proveedor de OIDC

En el siguiente ejemplo, se muestra cómo borrar 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");

Enumera configuraciones de proveedores de OIDC

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

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 opciones de configuración del usuario y un token de página siguiente que se usa para recuperar el siguiente lote. Cuando se enumeran todos los proveedores, no se muestra ningún token.

De forma predeterminada, se muestran 100 proveedores con cada lote. Esta es también la cantidad máxima de proveedores por lote.

¿Qué sigue?