Como configurar o Vonage Protection Suite para o PingOne

Introdução

O Vonage Protection Suite para PingOne é um conector de autoatendimento, que não requer programação, desenvolvido com base no Vonage Cloud Runtime (VCR). Ele se integra diretamente ao seu ambiente PingOne como um provedor de notificações personalizado e utiliza o Vonage Verify para enviar senhas de uso único (OTPs) por SMS e voz.

Antes de enviar uma senha de uso único (OTP), o conector pode realizar verificações de segurança opcionais por meio do Identity Insights, incluindo validação de números e consultas às operadoras. Durante o envio da OTP, o Vonage Fraud Defender oferece uma camada adicional de proteção por meio da detecção de envio em massa de SMS, permissões geográficas e controles de velocidade.

O conector está disponível no Marketplace do Vonage Cloud Runtime (VCR), onde você pode implantá-lo e configurar a integração com seu ambiente PingOne sem a intervenção operacional da Vonage.

O uso do Vonage Protection Suite para o PingOne está sujeito aos termos da Vonage Termos de Uso e Termos Complementares do Conector.

A quem se destina este guia

Este guia está organizado em torno das seguintes funções:

• Administradores e profissionais de TI: Implemente e configure o conector, configure a integração com o PingOne, gerencie os tokens de autenticação e monitore o envio de OTP. Continue para Guia de Instalação e Configuração (Usuário Administrador).
• Usuários finais: Receba OTPs por SMS ou mensagem de voz durante a autenticação no PingOne. Não é necessária nenhuma configuração. Para obter uma visão geral do fluxo de autenticação, consulte Experiência de envio da OTP.

Modelo de segurança de duas camadas

O Vonage Protection Suite para PingOne utiliza um modelo de segurança de duas camadas:

Fluxo do conector

O diagrama a seguir mostra como o conector lida com o envio da OTP entre o PingOne e o Vonage Verify. O PingOne continua sendo responsável por gerar e validar a OTP, enquanto o conector a envia por SMS ou mensagem de voz.

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte:

• Um ambiente PingOne ativo com os serviços PingOne SSO e PingOne MFA incluídos na lista de materiais (BOM) do ambiente. Para verificar os serviços incluídos, acesse Meio Ambiente > Propriedades.
• Acesso de administrador ao console de administração do PingOne, com permissões para configurar remetentes, políticas de notificação, políticas de autenticação multifatorial (MFA), políticas de autenticação e webhooks.
• Um account da API da Vonage (você pode se cadastrar gratuitamente) juntamente com uma chave de API, que você pode encontrar em seu Configurações da API no Painel da Vonage.
• Acesso ao Painel do Vonage e o Vonage Cloud Runtime com uma assinatura avançada.

Instalar e configurar o conector (usuário administrador)

Como administrador, siga as etapas deste guia para implantar o conector no Vonage Cloud Runtime, configurar a integração no PingOne e Verify se ela funciona.

Implantar o Conector no Vonage Cloud Runtime

Para implantar uma nova instância do Vonage Protection Suite para o PingOne:

1. Faça login no Marketplace do Vonage Cloud Runtime e clique no Pacote de Proteção da Vonage para o Ping One azulejo.

2. No menu à direita, selecione o Chave da API no qual você deseja implantar o conector. Se sua conta tiver apenas uma chave de API, esta etapa será ignorada automaticamente.
3. Clique Implantar uma nova instância.

4. Selecione uma região para a instância e insira um nome exclusivo e conciso para ela.

5. Selecionar Padrão como tipo de configuração.
6. Clique Continuar.

7. Configure as seguintes opções:

   • Número da Vonage (opcional): Se configurado, esse número é usado como identificação do remetente em mensagens SMS. Digite o número no formato E.164, sem o + caractere. Se você não inserir um número, o conector usa o valor configurado Marca. Essa configuração não se aplica a chamadas de voz — o número do chamador é selecionado aleatoriamente pelo Vonage Verify.
   • Nome da marca (obrigatório): Digite o nome da marca para incluí-lo no corpo da mensagem SMS. Essa configuração não se aplica a chamadas de voz.
   • Reserva para chamadas de voz (obrigatório): Ative esta opção para tentar novamente a entrega por meio de uma chamada de voz caso a entrega do SMS falhe.

8. Clique Continuar para implantar a instância.

Configurar o conector

Após implantar o conector, inicie seu aplicativo de administração para configurar políticas de segurança e gerar tokens de autenticação.

Inicie o aplicativo de administração

1. Acesse o Implantar código aba e inicie a instância existente.

2. Faça a autenticação com as credenciais da Vonage clicando no Verificar identidade com a Vonage botão.

Guia “Painel”

O Painel de controle A guia oferece visibilidade em tempo real sobre a entrega de OTP e as atividades de autenticação.

Contadores

O Contadores A seção exibe as seguintes métricas:

• Total de SMS: Número total de tentativas de envio de SMS, incluindo as tentativas bem-sucedidas e as que falharam.
• Sucesso do SMS: Número de mensagens SMS entregues com sucesso.
• SMS bloqueado: Número de mensagens SMS bloqueadas pelo Identity Insights ou pelo Fraud Defender.
• Total de vozes: Número total de tentativas de entrega de mensagens de voz, incluindo as tentativas bem-sucedidas e as que falharam.
• Sucesso na voz: Número de transmissões de voz bem-sucedidas.
• Voz bloqueada: Número de chamadas de voz bloqueadas.

Atividades recentes do OTP

O Atividades recentes do OTP Esta seção exibe os 10 eventos mais recentes de envio de OTP em todos os tokens:

• Data e hora: Hora em que foi tentada a entrega.
• Destino: Número de telefone do destinatário oculto.
• Canal: Canal de entrega, seja SMS ou VOICE.
• Status: Status da entrega, como SUCCESS, FAILED, ou FLAGGED.
• Descrição: Motivo completo de uma falha ou sinalização. Clique no olho ícone para ver a descrição.
• Latência: Tempo necessário para concluir a entrega, em milissegundos.
• Nome do token: Nome atribuído ao token no momento de sua criação.

Eventos recentes relacionados à autenticação

O Eventos recentes relacionados à autenticação Esta seção exibe os 20 eventos de verificação bem-sucedidos mais recentes recebidos do PingOne por meio do webhook configurado (consulte o Configurar um webhook do PingOne para eventos de verificação) seção.

O conector registra apenas OTP Check Success eventos. Eventos com falha e eventos não relacionados não são armazenados.

Esta seção exibe as seguintes informações:

• Data e hora: Hora em que a PingOne publicou o evento.
• Nome do token: Nome atribuído ao token no momento de sua criação.
• Evento: Tipo de evento PingOne, exibido como OTP Check Success.
• Resultado: Resultado da verificação. O conector registra apenas eventos com um SUCCESS resultado.
• Usuário: Identificador de usuário do PingOne.
• Correlação: Referência utilizada para associar o evento de verificação ao envio original da OTP.

Guia “Tokens”

O Fichas A aba exibe todos os tokens gerados com seu status atual:

Um token pode apresentar um dos seguintes status:

• Ativo: O token é válido e pode ser utilizado.
• Período de carência: O token foi substituído por um token mais recente. Ambos os tokens permanecem válidos durante um período de transição de 24 horas.
• Vencido: O token já passou da data de validade.
• Revogado: O token foi revogado manualmente e não pode mais ser utilizado.

Adicionar um token

Ao criar um token, configure os seguintes valores:

• Nome do token: Um nome legível por humanos usado para identificar o token no Aplicativo de Administração.
• Validade do token: O período durante o qual o token permanece válido. As opções disponíveis são 24 horas, 7 dias, 30 dias, 90 dias ou Nunca. Prazos de validade mais curtos aumentam a segurança, mas exigem uma rotação mais frequente dos tokens.

Girar um token

A rotação de um token gera um novo token com o mesmo nome e prazo de validade do token original. O token original entra em um período de carência de 24 horas, durante o qual ambos os tokens permanecem válidos. Use a rotação para renovar regularmente as credenciais sem tempo de inatividade.

Para conhecer o procedimento completo de rotação, consulte Gerenciar e alternar um token de autenticação.

Revogar um token

A revogação de um token o desativa imediatamente. Utilize essa opção caso um token tenha sido comprometido ou não seja mais necessário. A revogação é imediata e irreversível.

Guia “Configuração”

O token autentica as solicitações entre o PingOne e o conector da Vonage. O Configuração A guia contém as configurações que se aplicam a todos os tokens da instância do conector.

Camada 1 – Informações sobre identidade (pré-OTP)

Perspectivas sobre identidade realiza verificações opcionais antes que o conector envie uma OTP. O conector executa a ação configurada com base nos resultados dessas verificações.

Cada verificação ativada é cobrada por solicitação. Formato numérico e Validade é gratuito. Consulta da operadora original e Consulta de operadora atual são cobrados por solicitação. Os detalhes sobre preços estão disponíveis no Página de preços da Vonage.

Para configurar o Identity Insights:

1. Alternar Ativar o Identity Insights em.
2. Selecione uma ou mais das seguintes opções:

• Formato e validade dos números: Valida o formato do número de telefone e verifica se o número está acessível.
• Consulta da operadora original: Identifica a operadora à qual o número foi originalmente atribuído. Essa verificação identifica números de VoIP e números virtuais.
• Consulta atual da operadora: Identifica a operadora que atualmente presta serviço para o número. Essa verificação detecta números portados.

Filtros geográficos e de canal

Lista de países autorizados: Insira os códigos de país ISO 3166-1 alfa-2 (por exemplo, US, GB, DE). Somente números associados a esses países serão permitidos. Deixe em branco para permitir todos os países.

Quando o número é sinalizado

Escolha a ação a ser tomada quando um número de destino for sinalizado durante as verificações:

• Bloquear OTP: O OTP não é enviado. O evento bloqueado aparece em Atividades recentes do OTP.
• Marcar e entregar: O OTP foi entregue, mas o evento está marcado com o status âmbar no Painel.
• Apenas o log: O resultado da verificação é registrado, mas nenhuma ação é tomada. A senha de uso único (OTP) é enviada normalmente.

Camada 2 – Defesa contra fraudes (durante a OTP)

Protetor contra fraudes oferece proteção durante a entrega da senha de uso único (OTP), incluindo proteção contra o envio excessivo de SMS, tráfego inflacionado artificialmente e ataques de picos de tráfego.

O Fraud Defender Advanced está incluído no Verify e aparece como Incluído na configuração do conector. O Fraud Defender Premium está disponível como uma atualização paga. Entre em contato com seu gerente de contas para ativá-lo.

Você pode configurar as seguintes proteções no Painel da Vonage:

• Regras de trânsito: Crie regras de bloqueio e permissão por país ou prefixo para controlar para onde os OTPs podem ser enviados (disponível no Fraud Defender Standard, incluído em todas as Accounts).
• Proteção AIT: Detecte e bloqueie o tráfego de SMS inflado artificialmente. Os níveis de proteção disponíveis são: Nenhum, (apenas alertas, sem bloqueio), Padrão (bloqueia o tráfego de alto risco e emite alertas sobre o restante), e Alto (bloqueia todo o tráfego potencialmente fraudulento). Saiba mais aqui.
• Proteção contra enxurrada de SMS: Configure limites de restrição por país. Saiba mais aqui.
• Alertas volumétricos: Receba alertas quando forem detectados aumentos anormais no tráfego de um país. Saiba mais aqui.

Configurar o limite de taxa

O conector limita o número de solicitações de envio de OTP que podem ser feitas para um usuário em um intervalo de 10 minutos. O limite padrão é de cinco solicitações por usuário a cada 10 minutos. Isso protege contra fraudes de tarifas e solicitações repetidas de OTP direcionadas ao mesmo usuário.

Configurar o tempo limite do canal

O tempo limite do canal determina por quanto tempo o conector aguarda o primeiro canal de entrega antes de passar para o próximo canal. É possível configurar um valor entre 15 e 900 segundos.

Quando Recurso de fallback para chamadas de voz Se estiver ativado, esta é a janela após a qual uma mensagem SMS não entregue aciona a chamada de voz automática.

Modelos personalizados de mensagens OTP

Por padrão, o conector utiliza o modelo padrão de mensagem OTP da Vonage para envio por SMS e voz.

Os modelos personalizados de mensagens de OTP permitem que você substitua esse texto padrão pelo seu próprio corpo de mensagem, dando a você controle sobre o texto e o idioma da notificação de OTP que seus usuários finais recebem.

Uma vez configurado, o modelo ativo se aplica a todas as entregas de OTP nesta instância do conector.

Ativar modelos personalizados

O gerenciamento de modelos personalizados está desativado por padrão e precisa ser ativado na sua conta da Vonage. Entre em contato com o seu gerente de contas da Vonage ou com o suporte da Vonage para ativá-lo.

Depois que o Gerenciamento de Modelos Personalizados estiver ativado, você poderá criar e gerenciar modelos no Modelos seção do Aplicativo de Administração.

Para ativar um modelo para esta instância do conector:

1. Abra o Configuração aba.
2. Sob Modelo preferido, selecione um modelo.

Configurar um modelo

Os modelos personalizados contêm os seguintes elementos:

• Modelo: Um contêiner com nome. O nome é um rótulo legível para o modelo. Se É o padrão Se essa opção estiver selecionada, o modelo será utilizado quando não houver nenhum modelo preferencial configurado.
• Fragmento: Um corpo de mensagem associado a um canal de entrega e a uma configuração regional. Ao criar um fragmento, configure o canal de entrega (SMS ou chamada de voz), a configuração regional e o texto (um corpo de mensagem com espaços reservados). Saiba mais aqui.

O texto da mensagem pode utilizar os seguintes marcadores de posição:

• ${code}: Obrigatório. A senha de uso único (OTP) que o usuário deve digitar.
• ${brand}: Nome da marca configurado para a instância do conector.
• ${time-limit}: Período de validade numérico da OTP.
• ${time-limit-unit}: Unidade utilizada para o período de validade, como minutos.

Por exemplo:

Your ${brand} verification code is ${code}. Valid for ${time-limit} ${time-limit-unit}.

Os limites de caracteres seguem as regras padrão de codificação de SMS:

• GSM-7 (latim padrão): 160 caracteres por SMS individual, 153 por parte, se concatenado.
• UCS-2 (árabe, chinês, cirílico etc.): 70 caracteres por SMS individual, 67 por parte, se concatenados.

Os modelos são globais para a instância: um modelo preferencial se aplica a todos os tokens na instância do VCR. Os tokens individuais não possuem suas próprias substituições de modelo.

Idiomas suportados

Os fragmentos são correspondidos pelo campo de localidade (por exemplo, en-us). Se a localidade não for fornecida na solicitação de Verify, a Vonage tenta detectá-la a partir do prefixo do número de telefone ou, caso contrário, utiliza en-us por padrão. Consulte as localidades disponíveis para fragmentos de SMS e chamadas de voz aqui.

Locais marcados default+custom possuem mensagens padrão criadas pela Vonage e permitem a substituição por mensagens personalizadas. As configurações regionais marcadas custom only exigem um fragmento personalizado — não há nenhuma mensagem integrada da Vonage para eles.

O que acontece se não houver um modelo personalizado

Se nenhum modelo preferencial estiver definido (ou se estiver definido como “nenhum”), o modelo padrão integrado da Vonage será usado para o canal e a localidade. A ordem de substituição aplicada pela Vonage é:

1. Fragmento que corresponde à localidade solicitada no modelo preferencial.
2. Fragmento no modelo padrão da instância que corresponde à localidade.
3. A mensagem padrão integrada da Vonage para essa localidade e esse canal.
4. Mensagem padrão em inglês (en-us) da Vonage, caso não seja encontrada nenhuma configuração de localidade correspondente.

Para as configurações regionais marcadas custom only, não há um mecanismo de fallback integrado da Vonage: é necessário um fragmento personalizado; caso contrário, a entrega falhará para essa localidade.

Registre os detalhes gerados

Após configurar as políticas de segurança e gerar um token de autenticação, anote os seguintes valores. Você precisará deles ao configurar o PingOne:

• URL do ponto de extremidade do remetente: O único ponto de destino utilizado tanto para o envio de SMS quanto para o envio de chamadas de voz. O canal de entrega é especificado no corpo da solicitação.
• URL do webhook de destino: O endpoint utilizado para eventos de verificação do PingOne.
• Token de autenticação: A credencial que o PingOne inclui em cada solicitação.
• Nome do cabeçalho de autenticação: Obrigatório apenas ao utilizar o esquema de autenticação “Custom Header”. O valor padrão é x-ping1-auth.
• Modelos de corpo de solicitação: Os modelos de SMS e de voz exibidos na caixa de diálogo de geração de tokens.

Configurar o PingOne

Após implantar o conector e gerar um token de autenticação, configure o PingOne para encaminhar o envio do OTP por meio do conector da Vonage.

Adicionar o Vonage como provedor de notificações personalizadas

1. Faça login no console de administração do PingOne e confirme se você está no ambiente correto.
2. Acesse Configurações > Remetentes.
3. Clique no + ícone para adicionar um remetente.

4. Para Tipo de remetente, selecione SMS/Voz.
5. Para Tipo de prestador, selecione Provedor personalizado.

6. Configure o provedor usando os valores que você registrou no Registre os detalhes gerados passo.

• Nome: Digite um nome descritivo, por exemplo, Vonage Protection Suite.
• Autenticação: Selecionar Token ao portador e insira o token de autenticação como valor do campo “bearer”. O conector também oferece suporte à autenticação HTTP Basic, por credenciais de cliente OAuth2 e por cabeçalho personalizado. Se você selecionar Cabeçalho personalizado, insira o “Nome do cabeçalho de autenticação” como chave do cabeçalho e o “Token de autenticação” como valor do cabeçalho.

7. Configurar o envio de SMS:

   1. Defina o método da solicitação como POST.
   2. Cole a URL do ponto de entrega da OTP.
   3. Selecione JSON bruto como formato do corpo da solicitação.
   4. Cole o modelo do corpo da solicitação por SMS. O modelo do corpo utiliza as variáveis dinâmicas do PingOne, incluindo ${to} para o número do destinatário, ${otp} para a senha gerada, e ${message} para ver o texto completo da mensagem:

{
 "phoneNumber": "${to}",
 "message": "${message}",
 "otpCode": "${otp}",
 "locale": "${locale}",
 "userId": "${user.username}",
 "channel": "sms"
}

Observação: Para enviar um SMS de teste ou uma mensagem de voz, substitua os valores nos campos a seguir:

8. Configurar a transmissão de voz:

   1. Defina o método da solicitação como POST.
   2. Cole a mesma URL do ponto de entrega da OTP.
   3. Cole o modelo do corpo da solicitação de voz usando as mesmas variáveis dinâmicas:

{
"phoneNumber": "${to}",
"message": "${message}",
"otpCode": "${otp}",
"locale": "${locale}",
"userId": "${user.username}",
"channel": "voice"
}

9. Adicione os números de telefone a serem usados como identificadores de remetente e selecione os recursos de SMS ou voz correspondentes.
10. Verifique o Sinal de mais para números para que os números de telefone utilizem o formato E.164 exigido pelo conector.

11. Clique Salvar.

Para obter mais informações, consulte Configurando um provedor de notificações personalizado para o PingOne.

Associar o provedor Vonage a uma política de notificação

1. No console de administração do PingOne, acesse Experiência do usuário > Políticas de notificação.
2. Editar o Padrão política ou clique em + Adicionar política para criar uma nova política.
3. Sob Provedor de SMS, selecione seu provedor personalizado da Vonage no menu suspenso.
4. Sob Provedor de serviços de voz, selecione seu provedor personalizado da Vonage no menu suspenso.
5. Configure a prioridade do provedor e quaisquer regras de roteamento específicas por país, conforme necessário.
6. Clique Salvar.

Para obter mais informações, consulte Políticas de notificação.

Ative o SMS e a chamada de voz nas configurações de MFA e na política de MFA

Configurar as definições de MFA

1. Acesse Autenticação > MFA.
2. Abrir Configurações do MFA clicando no engrenagem ícone.
3. Conjunto Status do MFA para novos usuários para Ativado, portanto, a MFA é ativada automaticamente para usuários recém-criados.
4. Clique Salvar.

Configurar a política de MFA

Após atribuir o provedor Vonage a uma política de notificação, as opções de SMS e voz ficam disponíveis na política de MFA.

1. Acesse Autenticação > MFA > Políticas de MFA.
2. Editar o Política padrão de autenticação multifatorial (MFA) clicando no lápis ícone ou criar uma nova política.
3. Sob Métodos de autenticação permitidos, selecione SMS e Voz.
4. Sob Política de Notificação, selecione a política de notificação que você configurou no Associar o provedor Vonage a uma política de notificação passo.
5. Clique Salvar.

Para obter mais informações, consulte:

• Configurando uma política de autenticação multifatorial (MFA)
• Configurando as opções de MFA

Exigir MFA em uma política de autenticação

Configure uma política de autenticação que exija MFA após o login para acionar o fluxo de envio da OTP:

1. Acesse Autenticação > Autenticação.
2. Editar o arquivo existente Multifatorial política ou adicionar uma nova política.
3. Confirme que Entrar está configurado com nome de usuário e senha.
4. Adicione uma segunda etapa do tipo Autenticação multifatorial.
5. Selecione a política de MFA que você configurou no Configurar a política de MFA passo.
6. Atribua a política de autenticação às aplicações que exigem autenticação multifatorial (MFA) por telefone.

Para obter mais informações, consulte Adicionar uma etapa de autenticação multifatorial.

Configurar um webhook do PingOne para eventos de verificação

O Provedor de Notificações Personalizadas é responsável pelo envio da OTP, enquanto o webhook retorna o resultado da verificação ao conector. O PingOne gera e valida a OTP.

Quando um usuário digita o código correto, o PingOne registra o resultado da verificação da OTP como um evento de Audit e o envia de forma assíncrona para a URL do webhook de eventos. O conector recebe esse evento juntamente com a entrega original da OTP, permitindo que o Eventos recentes relacionados à autenticação visualizar e oferecer visibilidade completa do processo de conversão.

A configuração do webhook é opcional e deve ser ativada pelo cliente:

1. No console de administração do PingOne, verifique se você está no ambiente correto.
2. Acesse Integrações > Webhooks.
3. Clique Adicionar Webhook.
4. Digite um nome, por exemplo, Vonage Verification Events.
5. Para URL de destino, insira a URL do webhook de evento que você registrou no Registre os detalhes gerados etapa. O endpoint aceita HTTPS POST solicitações.
6. Para Formato, selecione Formato da atividade de ping. Este é o formato JSON genérico utilizado pela API do PingOne para atividades de Audit e é o formato correto para o endpoint da Vonage.
7. Sob Tipos de eventos, procure e selecione Verificação do OTP bem-sucedida. O conector utiliza esse evento para confirmar que a verificação foi bem-sucedida. Ele ignora e confirma com segurança outros tipos de eventos; portanto, selecionar eventos adicionais resulta na inclusão de dados desnecessários.
8. Opcionalmente, use Condições adicionais para filtrar eventos por tags, Applications ou populações. Restrinja o escopo para que apenas os eventos de verificação relevantes sejam enviados, a fim de evitar dados desnecessários.
9. Opcionalmente, configure um Limite de carga útil por tamanho em KB ou por número de eventos. Se você não definir um limite para a carga útil, o PingOne inclui até 500 eventos em cada carga útil.
10. Salve e ative o webhook.

Para obter mais informações, consulte:

• Criando ou editando um webhook
• Eventos de relatório de Audit

Verifique a conectividade do conector

Após configurar o Provedor de Notificações Personalizado e o webhook no PingOne, verifique se a conexão entre o PingOne e o conector da Vonage está ativa:

1. No console de administração do PingOne, acesse Configurações > Remetentes.
2. Abra o provedor personalizado da Vonage.
3. Use a opção de teste integrada para enviar uma mensagem SMS de teste para um número de telefone real.
4. Confirme se você recebeu a mensagem de texto.
5. No painel do conector, verifique se a entrega de teste aparece em Atividades recentes do OTP com um SUCCESS status.
6. No PingOne, acesse Integrações > Webhooks e confirme se o webhook da Vonage está ativado e funcionando corretamente.

Teste a integração

Antes de colocar o sistema em produção, verifique todo o fluxo de autenticação de ponta a ponta com um usuário de teste.

Antes de começar

Certifique-se de ter um dos seguintes itens:

• Um pedido nos termos de Conexões > Applications com a política de autenticação habilitada para MFA atribuída a partir do Exigir MFA em uma política de autenticação passo. Como alternativa, você pode usar o Portal de Autoatendimento da PingOne.
• Um usuário de teste em Diretório > Usuários com autenticação MFA ativada e um número de telefone capaz de receber mensagens SMS e chamadas de voz.

Teste usando um navegador

Este é o método de teste recomendado.

1. Abra uma janela do navegador no modo privado ou anônimo.
2. Acesse a URL de autorização do PingOne para seu aplicativo de teste:

https://auth.pingone.com/{environmentId}/as/authorize?response_type=code&client_id={clientId}&redirect_uri={redirectUri}&scope=openid

Substituir {environmentId}, {clientId}, e {redirectUri} com os valores das guias “Visão geral” e “Configuração” do aplicativo.

3. Na página de login do PingOne, digite o nome de usuário e a senha do usuário de teste.
4. Quando o PingOne solicitar a autenticação multifatorial (MFA) ao usuário, selecione “SMS” ou “Voz”. Se o usuário de teste não tiver registrado um número de telefone para a MFA, o PingOne solicitará que ele conclua o registro. Digite o número de telefone quando solicitado.
5. Aguarde até que a Vonage envie a senha de uso único (OTP) por meio do provedor personalizado que você configurou.
6. Digite a senha de uso único (OTP) na tela do PingOne.
7. Após a verificação bem-sucedida, você é redirecionado para o URI de redirecionamento do aplicativo com um código de autorização.

Teste usando o Portal de Autoatendimento PingOne

1. Acesse o Portal de Autoatendimento do PingOne para o seu ambiente:

https://apps.pingone.com/{environmentId}/myaccount/

2. Substituir {environmentId} com o seu ID do ambiente PingOne.
3. Faça login usando as credenciais do usuário de teste.
4. Quando o PingOne solicitar a autenticação multifatorial (MFA) ao usuário, conclua o desafio de MFA.
5. A Vonage envia a senha de uso único (OTP).

Confirme os resultados

Após concluir o fluxo de autenticação, verifique os resultados no Painel da Vonage e no Painel do conector:

Painel do Vonage

1. No Painel de Controle da Vonage, acesse Registros > Registros de SMS ou Registros de voz.
2. Confirme se a senha de uso único (OTP) foi enviada para o número de telefone do usuário de teste.
3. Verifique o status da entrega, a latência e as informações da transportadora.

Painel do Conector

1. Verifique se a entrega consta em Atividades recentes do OTP.
2. Se você configurou o webhook do PingOne, verifique se há um OTP Check Success o evento aparece em Eventos recentes relacionados à autenticação.

Um teste bem-sucedido confirma o seguinte fluxo de ponta a ponta:

PingOne > Vonage connector > SMS or voice delivery > user enters the OTP > PingOne validates the OTP > verification event returned to Vonage

Gerenciar e alternar um token de autenticação

O token de autenticação protege a comunicação entre seu ambiente PingOne e o conector da Vonage. Como prática recomendada de segurança, você pode alternar o token no Aplicativo de Administração ou programaticamente, utilizando a API de Gerenciamento de Tokens.

A renovação de um token gera um novo token e inicia um período de carência de 24 horas para o token anterior. Durante esse período, ambos os tokens permanecem válidos, permitindo que você atualize a configuração do PingOne sem interromper o envio da OTP.

Girar um token no Painel de Administração

1. Faça login no Painel de Administração com seu Account de administrador da Vonage.
2. Abra a Lista de tokens.
3. Encontre o token que você deseja girar.
4. Clique Girar.
5. Clique Confirmar.
6. Seu novo token será exibido. Copie-o e guarde-o em local seguro. O novo token é exibido apenas uma vez.
7. Verifique se o novo token aparece na lista de tokens. O token antigo está marcado com Rotated status e permanece válido durante o período de carência de 24 horas. Após o término do período de carência, ele expira.

Rotacionar um token usando a API

Você também pode alternar os tokens de autenticação programaticamente usando a API de gerenciamento de tokens.

A especificação OpenAPI e a coleção do Postman estão disponíveis para consulta no Artigo da Base de Conhecimento do Vonage Protection Suite para PingOne > etapa 6 > Girar um token – via API.

Autenticação

Os endpoints da API de gerenciamento de tokens utilizam autenticação HTTP Basic. Inclua sua chave de API e seu segredo de API da Vonage, separados por dois pontos e codificados em Base64, em cada solicitação:

Basic base64(API_KEY:API_SECRET)

Obter a lista de tokens

Antes de alternar um token, recupere seu UUID usando o endpoint “List Tokens”:

GET /admin/tokens

O endpoint retorna um mapa dos tokens associados à instância do conector. Cada entrada contém o ID do token, o nome, o status, as reivindicações e os contadores de uso.

Gire o token

A rotação de tokens emite um novo token com os mesmos direitos e um novo carimbo de data/hora, e dá início ao período de carência de 24 horas para o token anterior, após o qual este é invalidado.

Envie uma solicitação ao endpoint de rotação:

POST /admin/rotate-token

No corpo da solicitação, forneça o UUID retornado por GET /admin/tokens:

{
"id": "<token-uuid>"
}

Substituir "<token-uuid>" com o UUID do token que você deseja substituir.

Uma solicitação bem-sucedida retorna um 200 OK resposta contendo o token recém-assinado e seu identificador. O valor do token é retornado apenas uma vez.

A URL do ponto de entrega do OTP, a URL do webhook de eventos e o nome do cabeçalho de autenticação não se alteram quando você renova um token. Você pode recuperar esses valores usando:

GET /admin/config

Para conhecer o esquema completo da resposta, consulte a especificação OpenAPI.

Atualize o PingOne após a rotação de um token

Após renovar um token, atualize as credenciais no PingOne:

1. Acesse Configurações > Remetentes.
2. Edite o provedor personalizado da Vonage.
3. Na seção “Autenticação”, substitua a credencial existente pelo novo token:

• Se você usar a autenticação por token Bearer, atualize o valor do token Bearer.
• Se você utilizar o esquema de autenticação por cabeçalho personalizado, atualize o valor do cabeçalho personalizado.

4. Se o webhook for autenticado por meio do token, acesse Integrações > Webhooks, abra o webhook da Vonage e atualize suas credenciais.

A falta de atualização do PingOne fará com que o envio da OTP falhe assim que o token antigo for invalidado (após o período de carência de 24 horas).

Solução de problemas

Se o envio ou a verificação da OTP não funcionarem conforme o esperado, faça as seguintes verificações:

• Verifique as credenciais do conector: Verifique se a URL do ponto de entrega da OTP, a URL do webhook de eventos, o esquema de autenticação e o token de autenticação no PingOne correspondem aos valores da caixa de diálogo de geração de token.
• Verifique a Política de Notificações: Confirme se o provedor personalizado da Vonage está selecionado como provedor de SMS e voz na Política de Notificação e se a política de MFA está vinculada a essa Política de Notificação. Verifique a prioridade do provedor caso haja vários provedores configurados.
• Configuração do MFA: Certifique-se de que as opções de SMS e voz estejam habilitadas na política de MFA, que a política de MFA esteja vinculada à política de autenticação e que a MFA esteja habilitada para o usuário.
• Analise o painel: No painel do conector, verifique Atividades recentes do OTP para FAILED ou FLAGGED eventos. Clique no ícone de descrição para visualizar os detalhes do erro.
• Verifique os resultados do Identity Insights: Se o conector bloquear o OTP, verifique se o Identity Insights sinalizou o número de destino. Para fins de teste, considere ajustar a ação “Quando o número for sinalizado” (Bloquear > Sinalizar e Entregar ou Apenas Registrar).
• Verifique o formato do número: Verifique se o Sinal de mais para números A configuração no provedor personalizado corresponde ao formato E.164 esperado pelo conector.

Para obter detalhes sobre o rastreamento de solicitações de ponta a ponta, locais de registro e informações de suporte, consulte o Artigo da Base de Conhecimento do Vonage Protection Suite para PingOne.

Ciclo de vida completo da OTP – Rastreando uma única solicitação

Para obter instruções detalhadas sobre como rastrear uma solicitação de OTP no PingOne, no Vonage Cloud Runtime e no Vonage Verify, consulte o Artigo da Base de Conhecimento do Vonage Protection Suite para PingOne.

Referência sobre códigos de erro e informações sobre identidade

Quando uma solicitação de OTP é bloqueada, falha ou é sinalizada, você pode visualizar o erro estruturado no Painel de Controle Atividades recentes do OTP seção. Clique no olho ícone ao lado de um BLOCKED, FAILED, ou FLAGGED evento para visualizar os detalhes do erro.

Códigos de erro do conector

Os erros de conexão podem incluir:

• errorCode: O código de erro do conector.
• errorSummary: Uma descrição do erro em linguagem compreensível para o usuário.
• errorId: O identificador de correlação da solicitação é usado para localizar a solicitação nos registros do conector e pode ser informado ao Suporte da Vonage.
• errorCauses: Detalhes sobre os campos que não passaram na validação.

Subcódigos do Identity Insights

Quando a mensagem de erro contiver Identity Insight flagged: <reasons>, o reasons O campo contém um ou mais dos seguintes subcódigos. Podem aparecer vários motivos quando mais de uma verificação sinaliza o mesmo número.

Recursos adicionais para solução de problemas

Para obter instruções detalhadas sobre como rastrear uma solicitação de OTP em cada etapa do fluxo de entrega e verificação, consulte o Artigo da Base de Conhecimento do Vonage Protection Suite para PingOne. O artigo também oferece uma referência rápida aos caminhos de navegação do PingOne.

Precisa de ajuda?

Caso não consiga resolver o problema seguindo as orientações da seção “Solução de problemas” acima, entre em contato com Central de Ajuda da Vonage. Ao enviar uma solicitação, selecione o formulário intitulado Como usar os conectores da Vonage e, em seguida, selecione seu conector > Utilizando o Vonage Protection Suite para o PingOne Assim, o ticket é encaminhado diretamente para a equipe de suporte do PingOne Connector.

O que incluir (para uma resolução mais rápida)

Experiência de envio da OTP

Os usuários finais não precisam configurar o conector. Depois que um administrador concluir a configuração no Instalar e configurar o conector Nessa seção, o conector da Vonage lida com o envio da senha de uso único (OTP) de forma transparente. Do ponto de vista do usuário final, o fluxo de autenticação permanece idêntico à sua experiência atual com o PingOne:

1. O usuário inicia um fluxo de autenticação em um aplicativo protegido pelo PingOne, como login, cadastro para autenticação multifatorial (MFA) ou acesso à conta por meio do autoatendimento.
2. O PingOne solicita que o usuário faça a verificação por telefone.
3. O usuário seleciona SMS ou Voz.
4. O conector da Vonage envia a senha de uso único (OTP) para o telefone do usuário por meio do Vonage Verify.
5. O usuário digita a OTP na interface do PingOne.
6. O PingOne valida a senha de uso único (OTP) e conclui a autenticação.

O conector da Vonage opera em segundo plano durante todo esse processo. Se Recurso de fallback para chamadas de voz Se essa função estiver ativada e o envio de SMS falhar, o conector tentará novamente o envio por meio de uma chamada de voz, sem exigir nenhuma ação adicional do usuário.

Leitura complementar

• Perspectivas sobre identidade
• Protetor contra fraudes
• Artigo da Base de Conhecimento do Vonage Protection Suite para PingOne