Caso esteja procurando mais informação sobre os modelos de autenticação da Plataforma mobileX cheque a sessão Cadastro e Autenticação de Usuário. Essa sessão descreve o cadastro e autenticação nativo com segundo fator de autenticação com base em uma informação disponível no sistema de retaguarda do cliente.
A Plataforma mobileX possui uma API própria de autenticação que é utilizada por todos os seus frontends disponibilizados, baseada em login e senha seguindo os padrões Oauth 2.0.
As contas criadas nos aplicativos da plataforma ficam no domínio da plataforma e servirão para viabilizar o acesso seguro aos recursos disponibilizados através dos módulos de CMS (Integração), Atendimento, Questionários e Mensageria.
No processo de autenticação o usuário informa seu login e senha que são utilizados para autenticar na plataforma, uma vez logado essas informações por segurança são descartadas conforme padrão OAuth 2.0 de autenticação, isso torna mais segura as aplicações front-end.
A imagem a seguir apresenta uma visão geral do processo de autenticação e validação de usuário.
Permissões de Acesso para Execução de Actions
Toda ação configurada no app permite a definição de 3 níveis de acesso (permissionlevel): “público”, “autenticado”, “validado”.
Público: A action pode ser executada, mesmo quando o app é compilado na versão sem uso obrigatório login.
Autenticado: Exige que o usuário esteja autenticado no aplicativo para continuar a execução da action. Isto significa que o app precisa ter embarcado o token de segurança gerado pela API da plataforma, o qual é obtido quando o usuário faz login no app.
Validado: Exige que o usuário tenha sua identidade validada com base em alguma informação contida em um sistema externo para continuar a execução da action. Isto significa que o app precisa ter embarcado o token de segurança gerado pela API de integração do cliente. Este token pode ser obtido de diversas formas, conforme explicação na seção a seguir.
Obtendo Tokens de Credenciamento
A plataforma suporta diversos mecanismos de obtenção de tokens gerados pela API do cliente. Quando uma action do app tem o nível de permissão (permissionLevel) igual a 3, o app verifica se o usuário logado já possui um token de validação embarcado. Se não possuir, ele irá procurar nas configurações do endpoint qual o método de validação que será utilizado.
Este método disponibiliza uma tela padrão para que o usuário informe uma chave de validação fornecida pelo cliente proprietário do app. Quando o usuário enviar a chave, o app irá acionar a requisição de credenciamento do cliente, informada no mapeamento de integrações.
O método key é o mais recomendando. A API de validação da identidade recebe informações sobre o usuário tentando se autenticar e pode disparar um token via e-mail, SMS ou outro canal utilizando uma informação de contato validada pelo sistema de retaguarda. Ao digitar o token na tela de validação a identidade do usuário pode ser confirmada.
//Configure o método de credenciamento do Endpoint
{ …,
"authType": "Key",
"authPath": "LOGIN”
}
//Crie um mapeamento de segurança do tipo “UserSecurity” dentro do Endpoint
[ {
"identifier": "LOGIN",
"serviceConfiguration": {
"protocol": "https",
"url":”api.cliente.br/Login",
"method": "POST",
"header": {
"KEY":"[[USERNAME]]",
...
},
"content-type": "x-www-form-urlencoded”
}
},
{
//Mapping adicional caso a integração possua refresh token.
"identifier": "REFRESHTOKEN",
"serviceConfiguration": {
"protocol": "https",
"url":”api.cliente.br/Login",
"method": "POST",
"header": {
...
},
"body": {
-campos do formulário -
"refresh_token":"[[REFRESHTOKEN]]",
},
"content-type": "x-www-form-urlencoded”
}
}
]
//Retorno do serviço de integração:
Statuscode: 200 ou 202 ou 206
{
"access_token": "TbeMM-iwSQEHQfKEHfpX...",
"refresh_token": "AFeMM-iwSQEHQfKEHHJH...",
"userId": "83e1c3df-fe12-41fc-a4ce-e37d6732cef3",
"message": "Seu credenciamento foi realizado com sucesso",
"actions":[..]
}
Usuário e Senha
Este método disponibiliza uma tela para que o usuário informe uma chave de validação fornecida pelo cliente proprietário do app. Quando o usuário enviar a chave, o app irá acionar a requisição de validação do cliente, informada no mapeamento de integrações.
// Configure o método de credenciamento do Endpoint
{ …,
"authType": "password",
"authPath": "LOGIN”
}
// Crie um mapeamento de segurança do tipo “UserSecurity” dentro do Endpoint
[ {
"identifier": "LOGIN",
"serviceConfiguration": {
"protocol": "https",
"url":”api.cliente.br/Login",
"method": "POST",
"header": {
"username":"[[USERNAME]]",
"password":"[[PASSWORD]]",
...
},
"content-type": "x-www-form-urlencoded”
}
},
{
//Mapping adicional caso integração possua refresh token.
"identifier": "REFRESHTOKEN",
"serviceConfiguration": {
"protocol": "https",
"url":”api.cliente.br/Login",
"method": "POST",
"header": {
...
},
"body": {
"refresh_token":"[[REFRESHTOKEN]]",
...
},
"content-type": "x-www-form-urlencoded”
}
}
]
// Retorno do serviço de integração:
Statuscode:200 ou 202 ou 206
{
"access_token": "TbeMM-iwSQEHQfKEHfpX...",
"refresh_token": "AFeMM-iwSQEHQfKEHHJH...",
"userId": "83e1c3df-fe12-41fc-a4ce-e37d6732cef3",
"message": "Seu credenciamento foi realizado com sucesso",
"actions":[..]
}
Customizado - credenciamento via ação configurada
Diferente dos dois últimos, este método não possui uma tela fixa de entrada de dados. Ela é baseada na configuração da action de validação a ser executada.
Esta ação tanto pode chamar diretamente um serviço de integração para credenciar o usuário de forma silenciosa (passando por exemplo os dados da conta do aplicativo), quanto pode abrir um formulário dinâmico para que o usuário informe mais dados e então os submeta ao serviço.
A depender do statuscode de retorno do serviço de integração será possível apresentar as informações de sucesso ou erro de diversas formas. O statuscode suportados no processo de credenciamento são:
200: Exibe o resultado de sucesso dentro de um template.
202: Exibe o resultado de sucesso dentro de uma tela de mensagem.
206: Exibe o resultado de sucesso dentro de um toast (tag volátil de notificação interna do app).
400: Exibe o resultado de erro dentro de uma tela de mensagem.
401: Exibe o resultado de falha na autenticação dentro de uma tela de mensagem.
Exemplo de autenticação utilizando a abertura de um formulário:
// Configure o método de credenciamento do Endpoint
{
"authType": "action",
"authAction": {
"name": "open-search",
"path": "LOGIN",
"parameters": [
{ "title":"initialSearchForm",
"value": "identificado-unico"}
]
},
//Crie um mapeamento de segurança do tipo “UserSecurity” dentro do endpoint
[
{
"identifier": "LOGIN",
"serviceConfiguration": {
"protocol": "https",
"url":”api.cliente.br/Login",
"method": "POST",
"header": {
...
},
"body": {
-campos do formulário - são informados no body de forma automatica
},
"content-type": "x-www-form-urlencoded”
}
},
{
//Mapping adicional caso integração possua refresh token.
"identifier": "REFRESHTOKEN",
"serviceConfiguration": {
"protocol": "https",
"url":”api.cliente.br/Login",
"method": "POST",
"header": {
...
},
"body": {
-campos do formulário -
"refresh_token":"[[REFRESHTOKEN]]",
},
"content-type": "x-www-form-urlencoded”
}
}
]
//Retorno do serviço de integração
Statuscode:200 ou 202 ou 206
{
"access_token": "TbeMM-iwSQEHQfKEHfpX...",
"refresh_token": "AFeMM-iwSQEHQfKEHHJH...",
"userId": "83e1c3df-fe12-41fc-a4ce-e37d6732cef3",
"message": "Seu credenciamento foi realizado com sucesso",
"actions":[..]
}
Utilizando Validação nas Integrações
Para utilizar a funcionalidade que precisa da validação do usuário, é necessário configurar tanto a “action” quanto o mapeamento que será utilizado por ela.
Configure o endpoint com o tipo de credenciamento desejado. Ele deve ser único para todas as requisições.
Crie o mapeamento de credenciamento no endpoint. A depender do método de credenciamento configurado para o endpoint, você deve utilizar algumas palavras reservadas para informar à requisição a Key ou Usuário e Senha ou o campos do formulário dinâmico utilizado.
// Exemplo quando o método de credenciamento escolhido para o endpoint é KEY
"userSecurity": [
{
"identifier": "LOGIN",
"description": "",
"serviceConfiguration": {
"protocol": "https",
"url": "url-da-api/mobile/login",
"content-type": "x-www-form-urlencoded",
"method": "POST",
"header": {
"logInfo": "{{LOGINFO}}"
},
"body": {
"chave_acesso": "{{USERNAME}}",
“grant_type": "password",
….
},
"integrationSecurity": {
"enable": false,
"userName": "",
"password": ""
}
}
}
],
// Exemplo quando o método de credenciamento escolhido para o endpoint é “Password”
"userSecurity": [
{
"identifier": "LOGIN",
"description": "",
"serviceConfiguration": {
"protocol": "https",
"url": "url-da-api/mobile/login",
"content-type": "x-www-form-urlencoded",
"method": "POST",
"header": {
"logInfo": "{{LOGINFO}}"
},
"body": {
"username": "{{USERNAME}}",
"password": "{{PASSWORD}}", "grant_type": "password",
….
},
"integrationSecurity": {
"enable": false,
"userName": "",
"password": ""
}
}
}
],
//Exemplo quando o método de credenciamento escolhido para o endpoint é “Action”
"userSecurity": [
{
"identifier": "LOGIN",
"description": "",
"serviceConfiguration": {
"protocol": "https",
"url": "url-da-api/mobile/login",
"content-type": "x-www-form-urlencoded",
"method": "POST",
"header": {
"logInfo": "{{LOGINFO}}"
},
"body": {
"grant_type": "password",
+ "campos do form serão adicionados ao body de forma automatica” "grant_type": "password",
},
"integrationSecurity": {
"enable": false,
"userName": "",
"password": ""
}
}
}
],
Faça com que a sua requisição de credenciamento retorne um json no seguinte padrão.
Retorno do serviço de integração com sucesso → Statuscode: 200 ou 202 ou 206
{
"access_token": "TbeMM-iwSQEHQfKEHfpX...",
"refresh_token": "AFeMM-iwSQEHQfKEHHJH...",
"userId": "83e1c3df-fe12-41fc-a4ce-e37d6732cef3",
"message": "Seu credenciamento foi realizado com sucesso",
"actions":[..]
}
