Criar um endpoint da API da OAuth JWT para clientes externos

  • Versão de lançamento: Washingtondc
  • Atualizado 1 de fev. de 2024
  • 4 min. de leitura

    • Crie um endpoint da API OAuth JSON Web Token (JWT) para permitir que clientes externos acessem sua instância ServiceNow usando tokens da Web.

    Antes de Iniciar

    Função necessária: administrador

    Gere um token Web JSON (JWT) com as seguintes declarações:

    • 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: recomendado para corresponder ao valor do ID de cliente.
    • exp: qualquer expiração desejada.
    Figura 1. Exemplo de token Web JSON decodificado
    Exemplo de token Web JSON decodificado

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

    Por Que e Quando Desempenhar Esta Tarefa

    Permita que aplicações da Web externos sejam autenticadas perfeitamente com 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. O uso do tipo de concessão JWT não inclui a senha na solicitação, permitindo maior segurança entre os serviços da Web. Por exemplo, você pode desenvolver uma aplicação externa e usar tokens para autenticar solicitações de entrada para sua instância ServiceNow.

    Procedimento

    1. Crie um par de chaves e adicione a chave pública à tabela Certificados X.509 (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 de cliente existentes, clique no ícone do cadeado.
        Nota:
        Se for selecionado Cliente público, você poderá omitir o segredo do cliente.
        URL de logotipo O URL que contém uma imagem a ser usada como logotipo da aplicação. O logotipo aparece na página de aprovação quando o usuário recebe uma solicitação para conceder acesso a uma aplicação cliente a um recurso restrito na instância.
        Campo 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.
        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
        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 que somente tokens sejam usados com APIs definidas para permitir 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. Quando selecionado, você não precisa incluir um segredo do cliente.

        Padrão: não selecionado.
      4. Salve o formulário.
      5. Adicione registros à lista relacionada de mapas do verificador JWT para verificar a assinatura do JWT.
        Tabela 2. Tabela de 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).
      6. Adicione quaisquer declarações personalizadas associadas ao seu JWT à lista relacionada de Validações da declaração de JWT do OAuth.

        Você não precisa adicionar registros para as seguintes declarações obrigatórias:

        • iss
        • aud
        • sub
        • exp
        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 do 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.