API externa de passwords

Use uma API externa de passwords quando precisar que o FoxIDs (a) delegue a validação da password a um repositório de passwords ou motor de políticas existente, (b) notifique um sistema externo sobre alterações de password efetuadas no FoxIDs, ou (c) trate ambos os cenários.

Implementa a API externa de passwords e configura o FoxIDs para a chamar.

• Validation API: valida uma password, por exemplo durante o login ou antes de aceitar uma alteração de password, e pode opcionalmente notificá-lo sobre uma alteração de password na mesma chamada.
• Notification API: notifica sobre uma alteração de password depois de a password passar todas as verificações de política. Só é invocada para eventos de nova password (state 200).

Se a política de passwords integrada rejeitar a password, a API externa de passwords não é chamada. O método de notificação da API externa de passwords só é chamado se a password tiver passado todas as verificações de política configuradas e apenas quando o estado da password é 200 (nova password).

Se precisar tanto de validação como de notificação de alteração, e ambos puderem ser tratados pelo mesmo sistema, implemente apenas a Validation API. Quando receber um pedido de validação em que a password é aceite, execute internamente a lógica de notificação. Implemente ambos os endpoints apenas se necessário, por exemplo se tiver de chamar dois sistemas backend diferentes.

A API externa de passwords pode ser configurada como password check para utilizadores internos.

Implementar API

Tem de implementar uma API simples que o FoxIDs chama para pedidos de validação / notificação (veja o sample).

A API tem um URL base; a funcionalidade é agrupada em pastas: a pasta validation (validar password) e a pasta notification (notificar alterações de password).

Se o URL base for https://somewhere.org/mystore,

• o endpoint de validação é: https://somewhere.org/mystore/validation
• e o endpoint de notificação é: https://somewhere.org/mystore/notification.

O FoxIDs Cloud chama a sua API a partir do IP 57.128.60.142.
Os IPs podem mudar ou ser expandidos.

O pedido e a resposta são os mesmos tanto para o método de validação como para o método de notificação. O método de validação tem um caso de erro adicional devolvido se a password não for aceite.

Pedido

Protegido com HTTP Basic authentication: username external_password, a password é o secret configurado.

A chamada é HTTP POST com um body JSON.

Campos:

• email / phone / username (opcionais - pelo menos um tem de estar presente)
• password (obrigatória)
• state (obrigatório) - ver estado da password

Este é um body JSON de pedido apenas com o email como identificador do utilizador (validação de uma password existente durante o login):

{
  "email": "user1@somewhere.org",
  "password": "testpass1",
  "state": 100
}

Este é um body JSON de pedido com os três identificadores do utilizador (validação de uma nova password a ser definida ou alterada):

{
  "email": "user1@somewhere.org",
  "phone": "+4011223344",
  "username": "user1",
  "password": "testpass1",
  "state": 200
}

Os identificadores do utilizador são opcionais, mas pelo menos um tem de estar presente. A password e o state são obrigatórios.

Estado da password

O estado da password permite aplicar lógica diferente consoante o contexto.

Valores:

• 100 é a password atual, enviada quando um utilizador introduz uma password existente durante o login.
• 200 é uma nova password, enviada quando um utilizador define ou altera para uma nova password (criação de utilizador, alteração de password ou reset).

Resposta

Sucesso
Em caso de sucesso, a API deve devolver código HTTP 200.

Erro
A API tem de devolver código HTTP 401 (Unauthorized) e um error (obrigatório) se a autenticação Basic for rejeitada. Opcionalmente adicione uma descrição do erro em ErrorMessage.

{
  "error": "invalid_api_id_secret",
  "ErrorMessage": "Invalid API ID or secret"
}

Erro - apenas para o método de validação
A API tem de devolver código HTTP 400 ou 403 e um error (obrigatório) se a password, considerando o respetivo estado, não for aceite. Opcionalmente adicione uma descrição do erro em ErrorMessage.

{
  "error": "password_not_accepted",
  "ErrorMessage": "Password not accepted."
}

Se ocorrerem outros erros, a API deve devolver código HTTP 500 ou outro código de erro apropriado.
Recomenda-se adicionar uma mensagem técnica de erro em ErrorMessage para diagnóstico (é apenas registada; nunca mostrada ao utilizador final).

Exemplo de API

O sample ExternalPasswordApiSample mostra como implementar a API em ASP.NET Core.

Use a coleção Postman external-password-api.postman_collection.json para chamar e testar a sua API com Postman.

Configurar

A API externa de passwords é configurada nas definições do ambiente no FoxIDs Control Client.

1. Selecione o separador Settings
2. E depois selecione o separador Environment
3. Encontre a secção External password API
4. Selecione Validate on password change para impor uma política externa de passwords antes de ser definida uma nova password para um utilizador.
5. Adicione o URL base da API sem as pastas validation e notification em API URL
6. Adicione o API secret
7. Clique em Update