External Password API

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

Implementa a API de palavra-passe externa e configura o FoxIDs para a chamar.

API de validação: valida uma palavra-passe (por exemplo, durante o início de sessão ou antes de aceitar uma alteração de palavra-passe) e pode, opcionalmente, notificá-lo de uma alteração de palavra-passe na mesma chamada.
API de notificação: notifica sobre uma alteração de palavra-passe depois de esta ter passado todas as verificações de política. Só é invocada para eventos de nova palavra-passe (estado 200).

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

Se necessitar tanto de validação como de notificação de alterações, e ambas puderem ser tratadas pelo mesmo sistema, implemente apenas a API de validação. Quando receber um pedido de validação em que a palavra-passe seja aceite, execute a sua lógica de notificação internamente. Implemente ambos os pontos finais apenas se necessário, por exemplo, se tiver de contactar dois sistemas de backend diferentes.

A API de palavra-passe externa pode ser configurada como verificação de palavra-passe 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.

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