Autenticação JWT personalizada

Autenticação e autorização

O provedor de JWT de terceiros autentica usuários e retorna um JWT. O App Services utiliza o JWT para identificar os usuários do seu aplicativo e autorizar suas solicitações.

O App Services é independente dos métodos de autenticação utilizados pelo fornecedor terceirizado. Não impõe quaisquer restrições aos requisitos ou métodos de autenticação do sistema de autenticação externo. Por exemplo, o sistema pode exigir que o usuário execute autenticação multifator (MFA), forneça credenciais específicas ou identifique-se de outra forma.

Como funciona a autenticação JWT

Existem muitos recursos online que mergulham nos meandros da autenticação de JWT e da estrutura do token. No contexto do App Services, o diagrama a seguir fornece o fluxo do processo de um usuário que faz login em uma aplicação Device Sync. As etapas abaixo do diagrama fornecem detalhes.

clique para ampliar

A autenticação JWT com o App Services segue estas etapas gerais:

1. O usuário faz logon no fornecedor de autenticação terceirizado por qualquer meio exigido pelo fornecedor.

2. Se a autenticação for bem-sucedida, o provedor retorna um JWT para o aplicativo cliente.

3. O aplicativo cliente faz login no App Services através da credencial JWT.

4. O App Services analisa e decodifica o JWT.

5. Se você colocou manualmente as chaves de assinatura no App Services, ele verifica se a chave de assinatura no JWT corresponde a uma das chaves que você especificou. Caso corresponda, o usuário é autenticado.

6. Se você configurou o App Services para usar um URI de chave da Web JSON (JWK), o App Services passa o JWT e a chave pública para a API JWK do fornecedor terceirizado.

   1. O provedor decodifica e verifica a assinatura e retorna um JWK.

   2. O App Services verifica se a assinatura no JWK corresponde à assinatura do JWT. Em caso afirmativo, o usuário é autenticado.

Configuração

Você configura a autenticação JWT personalizada a partir da UI ou com a CLI. Escolha seu método preferido abaixo.

{
  "custom-token": {
    "name": "custom-token",
    "type": "custom-token",
    "config": {
      "audience": "<JWT Audience>",
      "requireAnyAudience": <boolean>,
      "signingAlgorithm": "<JWT Signing Algorithm>",
      "useJWKURI": <boolean>,
      "jwkURI": "<JWK or JWKS URL>",
    },
    "secret_config": {
      "signingKeys": [
        "<Signing Key Secret Name>",
        ...
      ]
    },
    "metadata_fields": [
      {
        "required": <boolean>,
        "name": "<JWT Field Path>",
        "field_name": "<Metadata Field Name>",
      },
      ...
    ],
    "disabled": <boolean>
  }
}

Método de verificação

O campo Verification Method determina como os App Services validarão o JWT retornado do fornecedor do JWT. Você pode configurar o App Services para validar o JWT usando a(s) chave(s) de assinatura fornecida(s) ou para validar usando um URI de chave da Web JSON (JWK) enviado pelo fornecedor terceirizado.

Especificar Chaves de Assinatura Manualmente

Você pode configurar sua aplicação para usar uma ou mais chaves de assinatura para validar o JWT. Existem duas configurações que você precisa fornecer:

Campo	Descrição
Signing Algorithm config.signingAlgorithm	O método criptográfico que o sistema externo usa para assinar o JWT. A autenticação personalizada suporta JWTs assinados usando um dos seguintes algoritmos: HS256 RS256
Signing Key secret_config.signingKeys	Uma lista de até três Segredos que cada um contém uma chave de assinatura utilizada pelo sistema de autenticação de terceiros para assinar JWTs. A chave só pode conter letras, números, sublinhados e hífens ASCII e deve ter entre 32 e 512 caracteres. A seguir está uma chave de assinatura válida de 256 bits: 231a58b00632c9c4d8ac02b268ca4caf8dd48fd020e3dffa72666523d860988f Observação Se você não tiver certeza de qual valor usar, considere visitar um site gerador de chaves aleatório, como keygen.io, e usar um dos valores de 256 bits gerados.

App Services UI

CLI de serviços de aplicativos

1. Defina o algoritmo de assinatura:

   

2. Crie uma ou mais chaves de assinatura para assinar o JWT. Para fazer isso, forneça um nome para a chave (que será apenas para sua referência mais tarde) e, em seguida, especifique uma chave de assinatura de 256 bits.

   

"config": {
  "signingAlgorithm": "<JWT Signing Algorithm>",
},
"secret_config": {
  "signingKeys": [
    "<Signing Key Secret Name>",
    ...
  ]
}

Aviso

Um Signing Key é uma chave secreta e qualquer pessoa com a chave pode emitir credenciais de usuário válidas para sua aplicação. Certifique-se de que ela nunca seja armazenada em uma localização acessível ao público, como um repositório git, um quadro de mensagens ou em seu código.

Use a JWK URI

Alguns sistemas de autenticação externa fornecem um conjunto de chaves da Web JSON (JWKS) que descreve o algoritmo de assinatura e as chaves de assinatura que o sistema usa para assinar JWTs. Você pode usar o JWKS para configurar o provedor em vez de especificar manualmente o algoritmo e as chaves de assinatura. O JWKS retornado deve incluir um cabeçalho kid que especifique o ID da chave de uma chave do JWKS. O JWKS pode especificar até três chaves de assinatura e deve usar o algoritmo RS256 .

Observação

No Atlas App Services, JWK e JWKS são como sinônimos.

Há apenas um valor que você precisa fornecer:

• JWK URI, que é a URL de terceiros que hospeda um serviço JWK ou JWKS. Ao escolher esta opção, o App Service define automaticamente a codificação para o método RS256 necessário.

App Services UI

CLI de serviços de aplicativos

Especifique a URL para o ponto de conexão do JWKS de terceiros:

"config": {
  "useJWKURI": <boolean>,
  "jwkURI": "<JWK or JWKS URL>"
}

Campos de metadados

Metadata Fields são dados adicionais que descrevem cada usuário interno do App Services. O App Services determina o valor de cada campo de metadados a partir do valor de um campo incluído no JWT de terceiros. Por exemplo, se você definir o campo name de um usuário, o App Services utilizará esse campo no JWT como o nome de exibição do usuário.

Observação

App Services atualizam os metadados de um usuário sempre que ele faz logon e expõe os campos no objeto data dos metadados do usuário.

Importante

Limites de caracteres JSON web token e do campo de metadados

O tamanho de um token JWT aumenta com o número de campos de metadados no token e o tamanho de cada campo. Os Serviços de Aplicativos limitam o tamanho de um token JWT a 1 milhão de caracteres e o tamanho de cada campo de metadados a 4096 caracteres. Se você exceder esses limites, o App Services registrará um erro e o ticket não será processado.

Há três valores que você precisa especificar para cada campo de metadados:

Campo	Descrição
Required required	No caso de true , o campo de metadados é obrigatório para todos os usuários associados ao fornecedor. O JWT retornado pelo sistema externo deve ter um valor atribuído ao campo designado pelo Path.
Path name	O nome ou o caminho para um campo no JSON web token que contém o valor para o campo de metadados. Para especificar o caminho para um campo em um objeto incorporado, use a notação de ponto. Se o nome do campo em si no JSON web token contiver um caractere de ponto (.), use uma barra invertida (\) para escapar do ponto. Por exemplo, se o nome for http://example.com/id, use http://example\.com/id.
Field Name field_name	Opcional. Um nome para o campo de metadados no documento data do objeto de usuário que mapeia para o Caminho JWT. Este nome de campo deve ter menos de 64 caracteres. Regras de valor padrão Se este campo não for especificado, o nome padrão é o nome do campo JWT que contém o valor. Se este campo não for especificado e o valor do caminho utilizar notação de ponto, o nome padrão será a última parte da notação. Por exemplo, se você especificar um caminho de location.primary.city, o valor padrão para o nome será city.

App Services UI

CLI de serviços de aplicativos

Para definir um campo de metadados, clique em Add Field e especifique o mapeamento entre o campo de metadados no JWT e seu nome de campo correspondente no objeto de usuário.

Para definir um campo de metadados em um arquivo de configuração de autenticação JSON web token personalizado, adicione uma entrada para o campo à array metadata_fields. Cada entrada deve ser um documento do seguinte formato:

{
  required: <boolean>,
  name: "<field path>",
  field_name: "<metadata field name>"
}

Use uma barra invertida (\) para escapar de caracteres de ponto (.) em chaves de JSON web token .

Por exemplo, neste objeto JSON, você representa o "nested_key" no nome do caminho como valid\.json\.key\.nested_key.

{ "valid.json.key": {
    "nested_key": "val"
  }
}

Exemplo

Um sistema de autenticação externo retorna JWTs que incluem informação adicional sobre cada usuário no campo user_data:

(JWT JSON)
{
  "aud": "myapp-abcde",
  "exp": 1516239022,
  "sub": "24601",
  "user_data": {
    "name": "Jean Valjean",
    "aliases": [
      "Monsieur Madeleine",
      "Ultime Fauchelevent",
      "Urbain Fabre"
    ]
  }
}

Para incluir os valores do campo user_data no objeto de usuário de cada usuário, especifique os seguintes campos de metadados em sua configuração do App Services:

Caminho	Nome do campo
user_data.name	name
user_data.aliases	aliases

O objeto do usuário agora incluirá esses campos:

(USER METADATA OBJECT)
{
  "id": "59fdd02846244cdse5369ebf",
  "type": "normal",
  "data": {
    "name": "Jean Valjean",
    "aliases": [
      "Monsieur Madeleine",
      "Ultime Fauchelevent",
      "Urbain Fabre"
    ]
  },
  identities: [
    {
      "id": "24601",
      "provider_type": "custom-token",
      "data": {
        "name": "Jean Valjean",
        "aliases": [
          "Monsieur Madeleine",
          "Ultime Fauchelevent",
          "Urbain Fabre"
        ]
      },
    }
  ]
}

Público

O Audience de um JWT especifica o destinatário pretendido do token. Os JWTs descrevem seu público na reivindicação de aud. O App Services espera que aud contenha o ID da aplicação para o qual o fornecedor está configurado. No entanto, se o JWT do sistema de autenticação externo especificar um valor aud diferente, você poderá configurar o fornecedor para usar esse valor.

App Services UI

CLI de serviços de aplicativos

Há dois campos que você configura:

Campo	Descrição
Audience	Um único valor ou uma lista de valores separados por vírgula para o público ou públicos que se espera que sejam encontrados em um cliente JWT.
Require	Se você fornecer vários públicos, deverá especificar como lidar com eles. Suas opções são: Todos esses públicos: o JWT deve incluir todos os públicos na lista. Qualquer um desses públicos: o JWT só precisa incluir um público da lista.

Para definir um público, configure config.audience. Há dois campos que você configura:

Campo	Descrição
audience	Uma array de strings especificando o público ou públicos que se espera encontrar em um JSON web token de um cliente .
requireAnyAudience	Boolean. Se false, o JSON web token deverá incluir todos os públicos listados. Se true, o JSON web token deverá incluir apenas um ou mais dos públicos listados.

"config": {
  "audience": [
    "<JWT Audience>",
  ],
  "requireAnyAudience": <boolean>,
}

Usando a autenticação JWT

Você pode registrar novos usuários de JWT personalizados e fazer login usando um dos Realm SDKs ou um serviço de API.