Autenticacão de Usuário mobileX

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”.

1. Público: A action pode ser executada, mesmo quando o app é compilado na versão sem uso obrigatório login.

2. 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.

3. 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.

Os métodos possíveis são:

• Key

• Usuário e Senha

• Customizado - credenciamento via ação configurada

Key

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.

Tela de validação via key

//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.

Tela de validação via usuário e senha

// 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.

1. Configure o endpoint com o tipo de credenciamento desejado. Ele deve ser único para todas as requisições.

{ ...
    "authType": "KEY",
    "authPath": "LOGIN",
...}
OU
{ ...
    "authType": "PASSWORD",
    "authPath": "LOGIN",
...}
OU
{ ...
    "authType": "ACTION",
    "authAction": {
	    "name": "open-search",
	    "path": "LOGIN",
	    "parameters": [
	      {  "title":"initialSearchForm", "value": "identificado-do-form"}
    	    ]
    },
...}

1. Na tela desejada, crie a action configurando o “PERMISSIONLEVE=3”.

...
"actions": [
              {
                "name": "open",
                "order": 0,
                "publishLevel": 1,
                "permissionLevel": 3,
                "path": "PACIENTES_PESQUISA",
                "parameters": [
                  {
                    "title": "querystring",   "value": "?pageNumber=1"
                  }
                ]
              }
            ]

1. 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": ""
			}
		}
	}
],

1. 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":[..]	
}