Esta página foi traduzida pela API Cloud Translation.

Gerir fornecedores SAML e OIDC de forma programática

Este documento mostra como usar o SDK de administrador da Identity Platform para gerir configurações do fornecedor do Security Assertion Markup Language (SAML) 2.0 e do OpenID Connect (OIDC) de forma programática.

Com o SDK de administração, pode configurar automaticamente fornecedores, realizar operações CRUD básicas, rodar certificados e muito mais. Isto é útil quando tem um grande número de fornecedores que seria difícil gerir manualmente através da consola do Google Cloud .

Antes de começar

Trabalhar com fornecedores de SAML

Criar uma configuração do fornecedor SAML

Tem de fornecer os seguintes parâmetros quando criar uma configuração do fornecedor SAML. Pode ter de consultar a documentação do seu fornecedor de identidade para ver detalhes sobre como obter alguns dos valores.

Nome a apresentar

Um nome a apresentar intuitivo para a configuração. Este nome também é a etiqueta do fornecedor na Google Cloud consola.

Ativado

Se a configuração do fornecedor atual está ativada ou desativada. Os utilizadores não podem iniciar sessão com fornecedores desativados.

ID do fornecedor

O identificador exclusivo do fornecedor, que começa com saml..

ID da entidade do fornecedor de identidade

O ID da entidade do fornecedor.

URL do SSO

O URL de SSO de SAML para o fornecedor. O URL tem de ser válido.

Certificados X.509

Uma lista de certificados X.509 do fornecedor SAML, incluindo as strings -----BEGIN CERTIFICATE----- e -----END CERTIFICATE----. Estes são usados para a assinatura de tokens no fornecedor de identidade.

Quando o Identity Platform recebe uma resposta SAML, valida a respetiva assinatura através de um certificado registado. Se a validação falhar, a resposta é rejeitada. Tem de atualizar estes certificados à medida que as chaves são alternadas. Considere carregar vários certificados para evitar indisponibilidades durante as rotações.

ID da entidade do partido de retransmissão

O ID da entidade da parte fidedigna (RP/SP) SAML. Normalmente, é o URL da app. No fornecedor de identidade SAML, isto é denominado público-alvo.

URL de retorno

O URL para o qual regressar quando a autenticação estiver concluída. Os fornecedores de SAML referem-se normalmente a isto como o URL do serviço de consumo de declarações (ACS). Tem de registar este URL junto do fornecedor de SAML. Deve ter um aspeto semelhante a https://PROJECT-ID.firebaseapp.com/__/auth/handler, semelhante aos URLs apresentados na consola Google Cloud . Para saber mais, consulte o artigo Iniciar sessão com utilizadores com SAML.

A utilização do URL de retorno predefinido diminui a complexidade da validação das respostas SAML. No entanto, também pode optar por apresentar um domínio personalizado. Neste caso, certifique-se de que o URL de retorno do Identity Platform para o seu projeto está configurado corretamente com o seu fornecedor de identidade SAML. Normalmente, tem um aspeto semelhante a: https://AUTH-DOMAIN/__/auth/handler.

O exemplo seguinte demonstra como criar uma configuração do fornecedor 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.
});

Ir

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)auth.go

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)index.py

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());FirebaseAuthSnippets.java

Após a conclusão, o método devolve um objeto SAMLAuthProviderConfig para a configuração recém-criada.

Atualizar uma configuração do fornecedor de SAML

O exemplo seguinte demonstra como modificar uma configuração do fornecedor SAML. Pode atualizar qualquer campo, exceto o ID do fornecedor.

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

Ir

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)auth.go

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)index.py

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());FirebaseAuthSnippets.java

Após a conclusão, o método devolve um objeto SAMLAuthProviderConfig para a configuração atualizada.

Obter uma configuração do fornecedor SAML

A principal forma de identificar uma configuração SAML é através do respetivo ID do fornecedor. O exemplo seguinte mostra como obter uma configuração do fornecedor 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.
});

Ir

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)auth.go

Python

saml = auth.get_saml_provider_config('saml.myProvider')
print(saml.display_name, saml.enabled)index.py

Java

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

Se existir um fornecedor com o ID indicado, o método devolve um objeto SAMLAuthProviderConfig.

Eliminar uma configuração do fornecedor SAML

O exemplo seguinte mostra como eliminar uma configuração do fornecedor SAML:

Node.js

admin.auth().deleteProviderConfig('saml.myProvider').then(() => {
  // Successful deletion.
}).catch((error) => {
  // Handle error.
});

Ir

if err := client.DeleteSAMLProviderConfig(ctx, "saml.myProvider"); err != nil {
	log.Fatalf("error deleting SAML provider: %v\n", err)
}auth.go

Python

auth.delete_saml_provider_config('saml.myProvider')index.py

Java

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

Listagem das configurações do fornecedor de SAML

O exemplo seguinte mostra como listar as configurações do fornecedor 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.
});

Ir

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)
}auth.go

Python

for saml in auth.list_saml_provider_configs('nextPageToken').iterate_all():
    print(saml.provider_id)index.py

Java

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

Cada lote de resultados contém uma lista de configurações de fornecedores e um token de página seguinte usado para obter o lote seguinte. Quando todos os fornecedores tiverem sido listados, não é devolvido nenhum token.

Por predefinição, são devolvidos 100 fornecedores com cada lote. Este é também o número máximo de fornecedores por lote.

Trabalhar com fornecedores de OIDC

Criar uma configuração do fornecedor OIDC

Tem de fornecer os seguintes parâmetros quando criar uma configuração do fornecedor de OIDC. Pode ter de consultar a documentação do seu fornecedor de identidade para ver detalhes sobre como obter alguns dos valores.

Nome a apresentar: Um nome a apresentar intuitivo para a configuração. Este nome também é a etiqueta do fornecedor na Google Cloud consola.
Ativado: Se a configuração do fornecedor atual está ativada ou desativada. Os utilizadores não podem iniciar sessão com fornecedores desativados.
ID do fornecedor: O identificador exclusivo do fornecedor, que começa com oidc..
ID do cliente: O ID usado para confirmar o público-alvo de um fornecedor OIDC token de ID.
Segredo do cliente: O segredo do cliente necessário para ativar o fluxo de código OIDC.
Emissor: O Issuer do fornecedor. Deve ter um aspeto semelhante a https://example.com. A Identity Platform usa este URL para localizar o documento de descoberta do OIDC (normalmente encontrado em /.well-known/openid-configuration), que especifica os endpoints OAuth e as chaves públicas do fornecedor. A Identity Platform valida os tokens de ID de acordo com a especificação do OpenID Connect. Se o seu fornecedor não agir em conformidade com a especificação OIDC para deteção, não funciona com a Identity Platform.
Tipo de resposta: O tipo de resposta do fornecedor para o fluxo de autorização OAuth. Pode definir um dos seguintes valores: {idToken, code} para true, mas não ambos. Se o fluxo de código estiver ativado, tem de fornecer um segredo do cliente.

O exemplo seguinte demonstra como criar uma configuração do fornecedor de OIDC que usa o fluxo de autorização 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.
});

Ir

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)auth.go

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)index.py

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());FirebaseAuthSnippets.java

Após a conclusão, o método devolve um objeto OIDCAuthProviderConfig para a configuração recém-criada.

Atualizar uma configuração do fornecedor OIDC

O exemplo seguinte demonstra como modificar uma configuração do fornecedor OIDC. Pode atualizar qualquer campo, exceto o ID do fornecedor.

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

Ir

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)auth.go

Python

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

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

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());FirebaseAuthSnippets.java

Após a conclusão, o método devolve um objeto OIDCAuthProviderConfig para a configuração atualizada.

Obter uma configuração do fornecedor OIDC

A principal forma de identificar uma configuração do OIDC é através do respetivo ID do fornecedor. O exemplo seguinte mostra como obter uma configuração do fornecedor 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.
});

Ir

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)auth.go

Python

oidc = auth.get_oidc_provider_config('oidc.myProvider')

print(oidc.display_name, oidc.enabled)index.py

Java

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

Se existir um fornecedor com o ID indicado, o método devolve um objeto OIDCAuthProviderConfig.

Eliminar uma configuração do fornecedor OIDC

O exemplo seguinte demonstra como eliminar uma configuração de fornecedor OIDC:

Node.js

admin.auth().deleteProviderConfig('oidc.myProvider').then(() => {
  // Successful deletion.
}).catch((error) => {
  // Handle error.
});

Ir

if err := client.DeleteOIDCProviderConfig(ctx, "oidc.myProvider"); err != nil {
	log.Fatalf("error deleting OIDC provider: %v\n", err)
}auth.go

Python

auth.delete_oidc_provider_config('oidc.myProvider')index.py

Java

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

Listagem das configurações do fornecedor do OIDC

O exemplo seguinte mostra como listar as configurações do fornecedor 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.
});

Ir

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)
}auth.go

Python

for oidc in auth.list_oidc_provider_configs('nextPageToken').iterate_all():
    print(oidc.provider_id)index.py

Java

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

Cada lote de resultados contém uma lista de configurações de fornecedores e um token de página seguinte usado para obter o lote seguinte. Quando todos os fornecedores são apresentados, não é devolvido nenhum token.

Por predefinição, são devolvidos 100 fornecedores com cada lote. Este é também o número máximo de fornecedores por lote.

O que se segue?

Migre utilizadores de uma app existente.
Inicie sessão com utilizadores com SAML e OIDC.