Mobile Platform as a Service:Autorização de API

A autorização de API permite que o Mobile Gateway Service (MGS) valide todas as requisições recebidas antes de encaminhá-las ao seu backend. Este tópico explica o funcionamento do mecanismo, quando utilizá-lo e como configure regras de autorização, implementar a interface do autorizador e aplicar essas regras às suas APIs.

Funcionamento

A autorização de API delega a verificação de identidade a uma API de autorização dedicada, desenvolvida e registrada por você no MGS. O fluxo para cada requisição autorizada é:

1. Crie uma API de autorização (API A) no gerenciamento de gateway e associe-a a uma API de negócio (API B) na configuração da API B.

2. Quando um cliente chama a API B, o MGS extrai os parâmetros de autorização do cabeçalho ou cookie da requisição conforme a configuração de autorização, insere-os no contexto da requisição e chama a API A. A implementação da API A verifica a permissão usando esses parâmetros de contexto.

3. Se a verificação for bem-sucedida, o MGS adiciona o resultado — chamado de principal — ao cabeçalho da requisição e a encaminha para a API B de backend. Com o cache ativado, o MGS armazena o principal em cache para requisições subsequentes e reduz a latência.

Casos de uso

Autorização baseada em sessão

Utilize este padrão quando seu backend mantiver um armazenamento de sessões distribuído. Após o login do usuário, um ID de sessão é emitido para o cliente e os dados da sessão são armazenados no servidor.

1. O Usuário A faz login com sucesso. Um ID de sessão é gerado e os dados da sessão — por exemplo, sessionId: {username:A, age:18, ...} — são armazenados em um cache distribuído. O ID de sessão retorna ao cliente.

2. O Usuário A chama uma API que exige autorização. O MGS recupera o ID de sessão do cabeçalho da requisição e o passa para a API de autorização. O autorizador consulta os dados da sessão no cache distribuído e retorna as informações do usuário — por exemplo, {username:A, age:18,...} — para o gateway.

3. O MGS confirma a autorização, anexa {username:A, age:18,...} ao cabeçalho da requisição como principal e encaminha a requisição para o servidor de negócios de backend.

Autorização baseada em token HMAC

Este padrão serve para autorização no lado do cliente usando Hash-based Message Authentication Code (HMAC). O token é calculado a partir de credenciais e verificado no servidor a cada requisição.

1. O Usuário A faz login com sucesso. Um token é calculado e enviado ao cliente — por exemplo, token=hmac(username+password).

2. O Usuário A chama uma API que exige autorização. O MGS recupera o token do cabeçalho da requisição e o passa para a API de autorização. O autorizador recalcula o HMAC e, se os tokens coincidirem, retorna as informações do usuário — por exemplo, {username:A, age:18,...} — para o gateway.

3. O MGS confirma a autorização, anexa {username:A, age:18,...} ao cabeçalho da requisição como principal e encaminha a requisição para o servidor de negócios de backend.

Configure regras de autorização

Crie uma regra de autorização

1. Faça login no console mPaaS. No painel de navegação à esquerda, escolha Background connection > Mobile Gateway Service.

2. Selecione a aba Gateway Management. Em API Authorization, clique em Create authorization API. Para modifique uma regra existente, localize-a na lista e clique em Details na coluna Actions.

   Configure os seguintes campos na página de configuração da regra de autorização:

   • Authorization API name: Obrigatório. Nome de exibição desta regra de autorização.

   • Authorization API: Obrigatório. API de autorização que verifica as requisições recebidas.

   • Cache authorization result: Define se o resultado da autorização deve ser armazenado em cache para requisições repetidas da mesma fonte de identidade.

   • Cache TTL: Tempo de validade do resultado de autorização em cache. O MGS usa os valores dos campos de fonte de identidade como chave de cache. Assim, requisições com os mesmos valores de fonte de identidade dentro do TTL reutilizam o resultado em cache sem chamar a API de autorização novamente.

   • Identity source: Clique em Add source field para especifique quais parâmetros da requisição o MGS extrai e passa ao autorizador. Cada campo de source possui duas propriedades:

     • Location: Local onde encontrar o parâmetro — header ou cookie.

     • Field: Nome do parâmetro.

   Nota

   Se o campo de fonte de identidade estiver ausente na requisição de API, a validação de autorização falhará.

Implementar a interface do autorizador

Antes de associar uma regra de autorização a uma API de negócio, implemente uma Auth API no seu sistema backend. Quando o MGS chama essa Auth API para verificar a autorização, a requisição e a resposta da Auth API devem seguir o contrato abaixo:

AuthRequest

public class AuthRequest {
  private Map<String,String> context;
}

AuthResponse

public class AuthResponse {
  private boolean success;
  private Map<String,String> principal;
}

Exemplo de interface

O exemplo a seguir lê um ID de sessão (sid) do contexto e retorna um principal derivado. Substitua a lógica pela sua própria verificação de identidade.

@PostMapping("/testAuth")
public AuthResponse testAuth(@RequestBody AuthRequest authRequest) {
    String sid = authRequest.getContext().get("sid");
    Map<String, String> principal = new HashMap<>();
    principal.put("uid", sid + "_uid");
    AuthResponse authResponse = new AuthResponse();
    authResponse.setSuccess(true);
    authResponse.setPrincipal(principal);
    return authResponse;
}

• Quando success é true, o MGS armazena o principal em cache conforme a política definida, adiciona o principal ao cabeçalho da requisição e a encaminha para o sistema de negócios de backend. Caso não haja principal para retornar, passe um Map vazio.

• Quando success é false, o MGS retorna o código de erro 2000 ao cliente. Trate essa situação no cliente solicitando que o usuário faça login novamente.

Aplicar regras de autorização a uma API

Após crie uma regra de autorização, abra a página de configuração da API de destino. Em Advanced Settings > API Authorization, selecione a regra para ative a autorização nessa API.

A autorização de API também exige que o recurso API Authorization esteja ativado no nível do gateway. Para ativá-lo:

1. Faça login no console mPaaS. No painel de navegação à esquerda, clique em Mobile Gateway Service.

2. Faça login no console mPaaS. No painel de navegação à esquerda, clique em Background connection > Mobile Gateway Service.

3. Na aba Gerencie gateway, verifique se o botão API Authorization está ativado.

Uma vez ativado, o MGS verifica a autorização antes que qualquer requisição de API chegue ao seu backend. Requisições aprovadas na verificação são encaminhadas ao sistema backend. Requisições reprovadas recebem uma resposta de erro indicando falha na autorização.