Como criar um endpoint de API JWT do OAuth para clientes externos (integração entre máquinas)

  • Versão de lançamento: Zurich
  • Atualizado 31 de jul. de 2025
  • 5 min. de leitura

    • O token transmissor JWT do OAuth permite que as aplicações da Web de clientes se autentiquem perfeitamente na sua instância usando o tipo de concessão JWT de entrada, em vez de exigir que o usuário final faça login manualmente ou compartilhe a senha.

    Antes de começar

    Os algoritmos compatíveis para JSON Web Token (JWT): RS256, RS384, RS512, ES256, ES384, ES512.

    Gere um JWT com as seguintes declarações no lado do cliente:

    • aud: deve corresponder ao valor do ID de cliente.
    • sub: deve ser um identificador de usuário, como o e-mail do usuário ao qual você deseja associar o token.
    • iss: recomenda-se que corresponda ao valor do ID do cliente. Se aud e iss não corresponderem, adicione o valor iss à validação da declaração.
    • exp: qualquer expiração desejada.
    Figura 1. Exemplo de token Web JSON decodificado
    Exemplo de token Web JSON decodificado

    Configuração na ServiceNow

    Por Que e Quando Desempenhar Esta Tarefa

    Já que o uso do tipo de concessão JWT não inclui a senha na solicitação, ele proporciona maior segurança entre os serviços da Web. Por exemplo, é possível desenvolver uma aplicação externa e usar tokens para autenticar solicitações de entrada para sua instância da ServiceNow.

    Função necessária: administrador

    Para obter mais informações sobre tokens Web JSON, consulte https://jwt.io/.

    Procedimento

    1. Adicione a chave pública do app cliente à tabela sys_certificate.
    2. Defina a configuração em sua instância da ServiceNow para verificar o JWT de entrada.
      1. Navegar até OAuth de Sistema > Registro de aplicações.
      2. Selecione Criar um endpoint da API da OAuth JWT para clientes externos
      3. Preencha o formulário com informações sobre seu token.
        Tabela 1. Tabela OAuth JWT
        Campo Descrição
        Nome Um nome exclusivo que identifica a aplicação para o qual você solicitou acesso ao JWT OAuth.
        ID de cliente O ID exclusivo da aplicação, gerado automaticamente. O sistema usa o valor deste campo para recuperar a chave pública ou compartilhada e validar o JWT. O valor deste campo deve corresponder ao valor das declarações do emissor e do público no JWT.
        Segredo do Cliente A cadeia de caracteres do segredo compartilhado que a instância e a aplicação cliente ou site usam para autorizar as comunicações entre si. Deixe este campo em branco para que a instância gere um segredo do cliente automaticamente. Para exibir segredos existentes do cliente, clique no ícone de cadeado.
        Nota:
        Se for selecionado Cliente público, você poderá omitir o segredo do cliente.
        Campo de usuário Campo na tabela Usuário (sys_user) que o sistema usa para corresponder ao valor da declaração do assunto no JWT. Por exemplo, se você adicionar um token que tenha um valor de declaração de assunto de nome.usuário@exemplo.com, defina o campo Usuário como E-mail. Este campo informa ao sistema para pesquisar o campo de e-mail para o valor nome.usuário@exemplo.com e usar o registro de usuário correspondente na solicitação de entrada.
        Habilitar a verificação de JTI Selecione para exigir um novo token a cada troca de token.

        Padrão: selecionado.
        Aplicação Escopo da aplicação de somente leitura. Este campo é preenchido automaticamente.
        Acessível de Política de acesso entre escopos. Para obter mais informações, consulte Configurações de acesso à aplicação.
        Tempo de vida do token de acesso Quantidade de tempo em que o token é válido.

        Unidade: segundos
        Formato do token Formato do token a ser gerado. O formato determina a estrutura de um token e as informações que ele inclui.
        Sinistro do assunto Campo na tabela Usuário (sys_user) que é usado para preencher o valor da declaração de assunto (sub) de um token JWT. A subdeclaração é uma informação que identifica o assunto, ou usuário, do token JWT. Este campo se aplica somente se Formato do token JWT.
        Distorção do relógio Diferença de tempo permitida entre os relógios do servidor e do cliente ao validar as declarações exp e nbf no JWT.

        Unidade: segundos

        Padrão: 300.
        Impor restrições de token Selecione para permitir somente o uso de tokens com as APIs definidas a fim de ativar o perfil de autenticação. Você pode definir a concessão de acesso usando uma política de acesso à API. Para obter mais informações, consulte Criar política de acesso à REST API.

        Padrão: não selecionado.
        Comentários Informações adicionais a serem associadas à aplicação.
        Cliente público Adicione este campo ao formulário se o cliente JWT for público. Ao selecioná-lo, não é necessário incluir um segredo do cliente.

        Padrão: não selecionado.
        Tipo de Cliente Escolha o tipo de cliente com base no tipo do seu cliente. Opções:
        • Integrado em iframe
        • Integração como um usuário
        • Integração como um serviço
        Para saber mais, consulte Como configurar o tipo de cliente para registros de OAuth e SSO.
      4. Salve o formulário.
      5. Adicione registros à lista relacionada "Mapas do verificador JWT" para verificar a assinatura do JWT.
        Tabela 2. Tabela "Mapas do verificador JWT"
        Campo Descrição
        Nome Nome do registro de mapeamento do JWT.
        Criança ID da chave do JWT.
        Chave Compartilhada A chave compartilhada para o ID da chave especificado.
        Aplicação Escopo da aplicação de somente leitura.
        Certificado de sistema Registro de certificado na tabela Certificados X.509 (sys_certificate). O certificado que foi carregado na etapa 1.
      6. Adicione quaisquer declarações personalizadas associadas ao seu JWT à lista relacionada de Validações da declaração de JWT do OAuth.

        Não é necessário adicionar registros para as seguintes declarações obrigatórias:

        • iss
        • aud
        • sub
        • exp
        Nota:
        • Se aud e iss não corresponderem, adicione o valor iss à validação da declaração.
        • Para certificados, é possível adicionar vários mapas de verificador associados a várias chaves.
        Tabela 3. Tabela Validações de declaração OAuth JWT
        Campo Descrição
        Meu cliente externo Preenchido automaticamente com o registro OAuth JWT.
        Tipo de Valor de Declaração Tipo de dados do valor da declaração.
        Nome da declaração Nome da declaração que você deseja adicionar.
        Valor da declaração Valor da declaração
        Aplicação Escopo da aplicação de somente leitura.
    3. Envie uma solicitação cURL contendo o token JWT para obter um token de acesso da sua instância.

      A seguir está um exemplo de comando cURL solicitando um token de acesso:

      $ curl -d"grant_type= urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id=be3aeb583ace210011c15b24a43e25d8
&client_secret=client_password
&assertion= eyJraWQiOiJzYW1wbGVrZXlpZCIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJhdWQiOiI5YzZlMmQxNzU0MzMyMDEwMDFhMTE4Y2FhMGVhMmE0MyIsInN1YiI6ImFkbWluQGV4YW1wbGUuY29tIiwiaXNzIjoiOWM2ZTJkMTc1NDMzMjAxMDAxYTExOGNhYTBlYTJhNDMiLCJleHAiOjE2MjI3MDI1MjYsImlhdCI6MTYyMjcwMjQ2NiwianRpIjoiNWRkMGUxYzctYjY1Ny00YmQ4LTlkY2UtMTdhZDdlZmUwNmFiIn0.PDoffnN2nq9ZNdxhOTLNbzlls4C1gsacahWr0kmPcGJDUJ_OQunmY5YXfpqkASiZixcQDS4kMwyqK9bha1-SnPOXq7zCIlJGCGFOv_OjEpQvMqmiKtLVk3jCsD03eXSoR4V-EzoCChiXpK87K5tMfM5k0YV9KfrxgvjUipgfni5N0JeyqkssMXBdkuE90XW_hBCo9AMMQm6J2PNMWb2O_O8rOX06KHuc4-Ip8wcRZ8a_bndCSmHl8Em7v4DvqTkLzlnF_-BXuM3T7nTI21cDXQKqZnqzzriu8irlAsscJFTxkh-_Ynei5RgYtL_Mvx2-HDO-XGofBhlAY2t9K36sz71HHqFZr5qCOIOAPguNzAy5-MOuZjOU_kH6ugIRycaNMDRjaU7gOvUHEERw3d0sI20OChIWOryBSwdTs7lgB1WzsJWCNVo81ssc2yko3jPoygt90tMwI_6A-4J-mlgq_fS_SvPUAqq_2UUJfVOTT5WGeq58cXfwRJmsDo49IhL3kXDVWT2gxaqhEdBQEW16UmRoTUzRs9A9sOm18y3skmOVtnEOm-MlJMFQZ754UMzbiH0ZsMmk1ivCGIjex5J0_lDjKElWF5RHGz3YShCoa4JKDZsqYMvIk1SvzyQXjuFqPdS2vzg2m1eKGUwr3m6uNs_HflcDystwVdMZ7nLlBG4"
https://instancename.service-now.com/oauth_token.do

      Se o cliente JWT for um cliente público, como o Mobile SDK, você poderá omitir os parâmetros client_id e client_secret da solicitação. A seguir está um exemplo de comando cURL solicitando um token de acesso que omite o client_id e o client_secret:

      $ curl -d"grant_type= urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion= eyJraWQiOiJzYW1wbGVrZXlpZCIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJhdWQiOiI5YzZlMmQxNzU0MzMyMDEwMDFhMTE4Y2FhMGVhMmE0MyIsInN1YiI6ImFkbWluQGV4YW1wbGUuY29tIiwiaXNzIjoiOWM2ZTJkMTc1NDMzMjAxMDAxYTExOGNhYTBlYTJhNDMiLCJleHAiOjE2MjI3MDI1MjYsImlhdCI6MTYyMjcwMjQ2NiwianRpIjoiNWRkMGUxYzctYjY1Ny00YmQ4LTlkY2UtMTdhZDdlZmUwNmFiIn0.PDoffnN2nq9ZNdxhOTLNbzlls4C1gsacahWr0kmPcGJDUJ_OQunmY5YXfpqkASiZixcQDS4kMwyqK9bha1-SnPOXq7zCIlJGCGFOv_OjEpQvMqmiKtLVk3jCsD03eXSoR4V-EzoCChiXpK87K5tMfM5k0YV9KfrxgvjUipgfni5N0JeyqkssMXBdkuE90XW_hBCo9AMMQm6J2PNMWb2O_O8rOX06KHuc4-Ip8wcRZ8a_bndCSmHl8Em7v4DvqTkLzlnF_-BXuM3T7nTI21cDXQKqZnqzzriu8irlAsscJFTxkh-_Ynei5RgYtL_Mvx2-HDO-XGofBhlAY2t9K36sz71HHqFZr5qCOIOAPguNzAy5-MOuZjOU_kH6ugIRycaNMDRjaU7gOvUHEERw3d0sI20OChIWOryBSwdTs7lgB1WzsJWCNVo81ssc2yko3jPoygt90tMwI_6A-4J-mlgq_fS_SvPUAqq_2UUJfVOTT5WGeq58cXfwRJmsDo49IhL3kXDVWT2gxaqhEdBQEW16UmRoTUzRs9A9sOm18y3skmOVtnEOm-MlJMFQZ754UMzbiH0ZsMmk1ivCGIjex5J0_lDjKElWF5RHGz3YShCoa4JKDZsqYMvIk1SvzyQXjuFqPdS2vzg2m1eKGUwr3m6uNs_HflcDystwVdMZ7nLlBG4"
https://instancename.service-now.com/oauth_token.do

      A instância retorna o token de acesso em sua resposta:

      {
    "access_token": "KynMY2H0uwWkRc8g8YLXjnQxWbH5_wbnSiLsnaOoKw61GZkkV0ytZP74uF7hJyjfsWfaaFijqQzq2kcABNJxNA",
    "scope": "useraccount",
    "token_type": "Bearer",
    "expires_in": 1799
}
      Nota:
      O tipo de concessão JWT de entrada não inclui tokens de atualização.
    4. Faça uma chamada de REST API para acessar um recurso usando o token de acesso.

      A seguir está um comando cURL para acessar a tabela de incidentes usando o token.

      $ curl -H "Authorization: Bearer KynMY2H0uwWkRc8g8YLXjnQxWbH5_wbnSiLsnaOoKw61GZkkV0ytZP74uF7hJyjfsWfaaFijqQzq2kcABNJxN" 
https://instancename.service-now.com/api/now/v1/table/incident

    Resultado

    O sistema recupera o token de acesso na chamada REST e permite o acesso ao recurso solicitado.