Administra 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ían difíciles de administrar de forma manual con Cloud Console.

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 del proveedor en Cloud Console.
Habilitado
Determina si la configuración del proveedor actual está habilitada o inhabilitada. Los usuarios no pueden acceder con proveedores inhabilitados.
ID del proveedor
El identificador único del proveedor, que comienza con saml..
ID de entidad del proveedor de identidad
El ID de entidad para el 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 del grupo 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 ser similar a https://PROJECT-ID.firebaseapp.com/__/auth/handler, similar a las URL que se muestran en Cloud Console. 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)

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)

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)

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')

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)

Cada lote de resultados contiene una lista de configuraciones de proveedores y un token de página siguiente 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 del proveedor en Cloud Console.
Habilitado
Determina si la configuración del proveedor actual está habilitada o inhabilitada. Los usuarios no pueden acceder con proveedores inhabilitados.
ID del proveedor
El identificador único del proveedor, que comienza con oidc..
ID de cliente
El ID usado para confirmar el público de un token de ID de un proveedor de OIDC.
Emisor
El *emisor* 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 suele encontrarse 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 no cumple con la especificación de OIDC para la detección, no funcionará con Identity Platform.

En el siguiente ejemplo, se muestra cómo crear una configuración de proveedor de OIDC:

Node.js

const newConfig = {
  displayName: 'OIDC provider name',
  enabled: true,
  clientId: 'CLIENT_ID2',
  issuer: 'https://oidc.com/CLIENT_ID2',
  providerId: 'oidc.provider2'
};
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)

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',
  issuer: 'https://oidc.com/',
};
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)

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)

Si existe un proveedor con el ID dado, 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')

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)

Cada lote de resultados contiene una lista de configuraciones de proveedores y un token de página siguiente 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?