HttpRequestAuthedData - com escopo

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

    • A API HttpRequestAuthedData() fornece métodos para acessar e definir valores em uma solicitação REST ou SOAP assinada.

    Gere solicitações de assinatura de saída usando essas APIs na seguinte ordem:
    1. HttpRequestData: crie a solicitação de API.
    2. AuthCredential: crie um objeto de credencial ou atualize um existente. Use a credencial para assinar a solicitação por meio da classe RequestAuthAPI.
    3. RequestAuthAPI: assine a solicitação e retorne um objeto HttpRequestAuthedData.
    4. HttpRequestAuthedData: obtenha informações sobre a solicitação assinada.
    5. GlideHTTPRequest: envia a solicitação assinada.

    Antes de usar essas APIs, você deve configurar um algoritmo de autenticação para assinar a solicitação e associá-lo à credencial usada para autenticar a solicitação.

    Use esta API em scripts com escopo com o identificador de namespace sn_auth. Você pode instanciar essa classe usando o construtor ou retornar um objeto HttpRequestAuthedData do método generateAuth() na classe RequestAuthAPI.

    HttpRequestAuthedData - HttpRequestAuthedData()

    Instancia um objeto HttpRequestAuthedData.

    Você pode instanciar essa classe usando o construtor ou retornar um objeto HttpRequestAuthedData do método generateAuth() na classe RequestAuthAPI.

    Tabela 1. Parâmetros
    Nome Tipo Descrição
    Nenhum

    HttpRequestAuthedData - addHeader(cadeia de caracteres chave, cadeia de caracteres valor)

    Adiciona um cabeçalho ao objeto HttpRequestAuthedData.

    Tabela 2. Parâmetros
    Nome Tipo Descrição
    chave Cadeia de caracteres Nome do cabeçalho HTTP.
    valor Cadeia de caracteres Valor do cabeçalho HTTP.
    Tabela 3. Retorna
    Tipo Descrição
    vazio 
    // Define HttpRequestData
var endpoint= "https://third-party-endpoint";
var httpRequestData = new sn_auth.HttpRequestData();
httpRequestData.setEndpoint(endpoint);
httpRequestData.setService('s3');
httpRequestData.setRegion('us-east-1');
httpRequestData.setHttpMethod("PUT");
var content = "Action=SendMessage&MessageBody=This is a test message";
httpRequestData.setContent(content);
 
//Get AuthCredential
var credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID("5b61c16f73533300f662cff8faf6a74b");
 
// Create RequestAuthAPI and sign the request
var signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);
var output = signingAPI.generateAuth();
 
// Update the signed response
output.addHeader('access-rights', 'public-read');

    HttpRequestAuthedData - addQueryParam(Chave de cadeia de caracteres, Valor de cadeia de caracteres)

    Adiciona um parâmetro de consulta ao objeto HttpRequestAuthedData.

    Tabela 4. Parâmetros
    Nome Tipo Descrição
    chave Cadeia de caracteres Nome do parâmetro de consulta.
    valor Cadeia de caracteres Valor do parâmetro de consulta.
    Tabela 5. Retorna
    Tipo Descrição
    vazio 
    // Define HttpRequestData
var endpoint= "https://third-party-endpoint";
var httpRequestData = new sn_auth.HttpRequestData();
httpRequestData.setEndpoint(endpoint);
httpRequestData.setService('s3');
httpRequestData.setRegion('us-east-1');
httpRequestData.setHttpMethod("PUT");
var content = "Action=SendMessage&MessageBody=This is a test message";
httpRequestData.setContent(content);
 
//Get AuthCredential
var credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID("5b61c16f73533300f662cff8faf6a74b");
 
// Create RequestAuthAPI and sign the request
var signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);
var output = signingAPI.generateAuth();
 
// Update the signed response
output.addQueryParameter('api_version', 'v2');

    HttpRequestAuthedData – getCredentialValue()

    Retorna o valor de credencial que foi incluído quando a solicitação foi assinada.

    Use um valor de credencial para armazenar um cookie, assinatura ou outro valor necessário para um algoritmo de autenticação. Por exemplo, crie uma etapa Obter informações de conexão (GCI) com um script que recupera e armazena um token único para uma chamada REST ou SOAP.

    Tabela 6. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 7. Retorna
    Tipo Descrição
    Cadeia de caracteres Texto do valor da credencial.

    Este exemplo mostra a recuperação de um valor de credencial.

    var RequestAuthGCISigner = Class.create();
RequestAuthGCISigner.prototype = Object.extend(new RequestAuthInternal(), {
  initialize: function() {
    RequestAuthInternal.prototype.initialize.call(this);
  },

  generateAuth: function(authAPI) {
    var requestData = authAPI.getHttpRequestData();

    // get credentials
    var credential = authAPI.getAuthCredential();
    var username = credential.getAttribute("user_name");
    var password = credential.getAttribute("password");
    var httpRequestSignedData = new sn_auth.HttpRequestAuthedData();
    var directive = requestData.getDirective();

    // set CREDENTIAL_VALUE
    httpRequestSignedData.setCredentialValue(username+":"+password);
    httpRequestSignedData.setDirective("CREDENTIAL_VALUE");
    httpRequestSignedData.setStatus("SUCCESS");

    gs.info("The Credential Value is " + httpRequestSignedData.getCredentialValue());
    return httpRequestSignedData;
  },
  type: 'RequestAuthGCISigner'
});

    Saída:

    The Credential Value is someUsername:somePassword

    HttpRequestAuthedData – getDirective()

    Retorna se a assinatura é aplicada à solicitação no cabeçalho, como um parâmetro de consulta ou como um valor de credencial.

    Por padrão, o sistema aplica a assinatura ao cabeçalho. Você pode aplicar a assinatura como um parâmetro de consulta ou valor de credencial usando a API setDirective().

    Tabela 8. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 9. Retorna
    Tipo Descrição
    Cadeia de caracteres Se a assinatura é aplicada ao cabeçalho, como um parâmetro de consulta ou como um valor de credencial.

    Os valores incluem:

    • CABEÇALHO: a assinatura é aplicada ao cabeçalho da solicitação.
    • CONSULTA: a assinatura é aplicada como um parâmetro de consulta.
    • CREDENTIAL_VALUE: a assinatura é aplicada como um valor de credencial.
    		 
    // Define HttpRequestData
var endpoint= "https://third-party-endpoint";
var httpRequestData = new sn_auth.HttpRequestData();
httpRequestData.setEndpoint(endpoint);
httpRequestData.setService('s3');
httpRequestData.setRegion('us-east-1');
httpRequestData.setHttpMethod("PUT");
var content = "Action=SendMessage&MessageBody=This is a test message";
httpRequestData.setContent(content);
 
//Get AuthCredential
var credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID("5b61c16f73533300f662cff8faf6a74b");
 
// Create RequestAuthAPI and sign the request
var signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);
var output = signingAPI.generateAuth();
output.setDirective("header");

gs.info("Signature applied to: " + output.getDirective());

    Saída:

    Signature applied to: HEADER

    HttpRequestAuthedData – getHeaderMap()

    Retorna um objeto que contém os cabeçalhos que foram incluídos quando a solicitação foi assinada.

    Tabela 10. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 11. Retorna
    Tipo Descrição
    Objeto Pares de chave-valor que definem todos os cabeçalhos incluídos quando a solicitação foi assinada. Cada par de chave-valor inclui estas partes:
    • chave: Cadeia de caracteres. Nome do cabeçalho.
    • valor: Cadeia de caracteres. Valor do cabeçalho.
    		 
    // Define the HttpRequestData object
var endpoint= "https://third-party-endpoint";
var httpRequestData = new sn_auth.HttpRequestData();
httpRequestData.setEndpoint(endpoint);
httpRequestData.setService('s3');
httpRequestData.setRegion('us-east-1');
httpRequestData.setHttpMethod("PUT");
var content = "Action=SendMessage&MessageBody=This is a test message";
httpRequestData.setContent(content);
httpRequestData.addHeader('x-amz-acl' , 'public-read' );
 
// Get an AuthCredential object
var credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID("5b61c16f73533300f662cff8faf6a74b");
 
// Create the RequestAuthAPI object and sign the request
var signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);
var output = signingAPI.generateAuth();
 
// get the signed response detail
var authH = headerM["Authorization"];
var xamzdateH = headerM["X-Amz-Date"];
var content256 = headerM["x-amz-content-sha256"];
 
gs.debug('authH:' + authH );
gs.debug('xamzdateH:' + xamzdateH );
gs.debug('content256:' + content256 );

    Saída:

    *** Script: [DEBUG] authH:AWS4-HMAC-SHA256 Credential=lsjfljljfllfwek/20191127/us-east-1/s3/aws4_request, 
SignedHeaders=host;x-amz-acl;x-amz-content-sha256;x-amz-date, 
Signature=5c349011324910c34596ba7abbd10e07c4127774049f8953418bd7bed7d02b90 
*** Script: [DEBUG] xamzdateH:20191127T175210Z 
*** Script: [DEBUG] content256:UNSIGNED-PAYLOAD

    HttpRequestAuthedData – getQueryMap()

    Retorna um objeto que contém os parâmetros de consulta incluídos quando a solicitação foi assinada.

    Tabela 12. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 13. Retorna
    Tipo Descrição
    Objeto Pares de chave-valor que definem os parâmetros de consulta incluídos quando a solicitação foi assinada. Cada par de chave-valor inclui estas partes:
    • chave: Cadeia de caracteres. Nome do parâmetro de consulta.
    • valor: Cadeia de caracteres. Valor do parâmetro de consulta.
    		 
    // Define the HttpRequestData object
var endpoint= "https://third-party-endpoint";
var httpRequestData = new sn_auth.HttpRequestData();
httpRequestData.setEndpoint(endpoint);
httpRequestData.setService('s3');
httpRequestData.setRegion('us-east-1');
httpRequestData.setHttpMethod("PUT");
var content = "Action=SendMessage&MessageBody=This is a test message";
httpRequestData.setContent(content);
httpRequestData.addQueryParam('api_version', 'v2' );
httpRequestData.addQueryParam('limit', '1000' );
httpRequestData.addQueryParam('offset', '1' );
 
// Get an AuthCredential object
var credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID("5b61c16f73533300f662cff8faf6a74b");
 
// Create the RequestAuthAPI object and sign the request
var signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);
var output = signingAPI.generateAuth();
 
// Get the signed response
queryMap = output.getQueryMap();

gs.info("API Version is: " + queryMap["api_version"]);

    Saída:

    API Version is: v2

    HttpRequestAuthedData – getStatus()

    Retorna o status da solicitação de assinatura.

    Tabela 14. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 15. Retorna
    Tipo Descrição
    Cadeia de caracteres O status da solicitação de assinatura.

    Valores possíveis:

    • ÊXITO: o sistema assinou a solicitação com sucesso.
    • FALHA: o sistema não conseguiu assinar a solicitação.
    • SKIPPED: o sistema ignorou a assinatura porque as informações estavam incompletas.
    		 
    // Define the HttpRequestData object
var endpoint= "https://third-party-endpoint";
var httpRequestData = new sn_auth.HttpRequestData();
httpRequestData.setEndpoint(endpoint);
httpRequestData.setService('s3');
httpRequestData.setRegion('us-east-1');
httpRequestData.setHttpMethod("PUT");
var content = "Action=SendMessage&MessageBody=This is a test message";
httpRequestData.setContent(content);
 
// Get an AuthCredential object
var credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID("5b61c16f73533300f662cff8faf6a74b");
 
// Create the RequestAuthAPI object and sign the request
var signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);
var output = signingAPI.generateAuth();
 
// Get the signed status
gs.info("Status is: " + output.getStatus());

    Saída:

    Status is: SUCCESS

    HttpRequestAuthedData - getStatusMessage()

    Retorna uma mensagem detalhada sobre a assinatura da solicitação. Se a assinatura da solicitação falhar, este método retornará a mensagem de erro.

    Tabela 16. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 17. Retorna
    Tipo Descrição
    Cadeia de caracteres Mensagem sobre a assinatura da solicitação. Se a assinatura da solicitação falhar, retornará uma destas mensagens de erro:
    • Acredencial não é válida: verifique o objeto AuthCredential usado para assinar a solicitação. Certifique-se de que um algoritmo de autenticação esteja associado à credencial. Para obter mais informações, consulte Configurar um algoritmo de autenticação.
    • Os dados da solicitação estão vazios. A autenticação da solicitação foi ignorada: verifique o objeto HttpRequestData porque as informações necessárias podem estar ausentes.
    • Não é possível encontrar o escopo de inclusões de script: verifique se o registro do algoritmo de autenticação e as inclusões de script associadas usadas para assinar a solicitação estão no escopo correto.
    		 
    // Define the HttpRequestData object
var endpoint= "https://third-party-endpoint";
var httpRequestData = new sn_auth.HttpRequestData();
httpRequestData.setEndpoint(endpoint);
httpRequestData.setService('s3');
httpRequestData.setRegion('us-east-1');
httpRequestData.setHttpMethod("PUT");
var content = "Action=SendMessage&MessageBody=This is a test message";
httpRequestData.setContent(content);
httpRequestData.addQueryParam('api_version', 'v2' );
httpRequestData.addQueryParam('limit', '1000' );
httpRequestData.addQueryParam('offset', '1' );
 
// Get AuthCredential object and set an attribute
var credential = new sn_auth.AuthCredential();
credential.setAttribute("user_name", "admin");
credential.setAttribute("password", "admin");
 
// Create the RequestAuthAPI object and sign the request
var signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);
var output = signingAPI.generateAuth();
 
// Get the signed status
gs.info("Status message is: " + output.getStatusMessage());

    Saída:

    Status message is: credential is not valid.

    HttpRequestAuthedData - setCredentialValue(cadeia de caracteres credential_value)

    Define um valor de credencial para o objeto HttpRequestAuthedData.

    Use um valor de credencial para armazenar um cookie, assinatura ou outro valor necessário para um algoritmo de autenticação. Por exemplo, crie uma etapa Obter informações de conexão (GCI) com um script que recupera e armazena um token único para uma chamada REST ou SOAP.

    Use o método setCredentialValue() para definir a cápsula de dados do valor de credencial para etapas REST, SOAP e GCI em Flow Designer.

    Tabela 18. Parâmetros
    Nome Tipo Descrição
    credential_value Cadeia de caracteres Texto do valor da credencial.
    Tabela 19. Retorna
    Tipo Descrição
    Nenhum

    Este exemplo mostra como definir um valor de credencial para uma etapa de GCI.

    var RequestAuthGCISigner = Class.create();
RequestAuthGCISigner.prototype = Object.extend(new RequestAuthInternal(), {
  initialize: function() {
    RequestAuthInternal.prototype.initialize.call(this);
  },

  generateAuth: function(authAPI) {
    var requestData = authAPI.getHttpRequestData();

    // get credentials
    var credential = authAPI.getAuthCredential();
    var username = credential.getAttribute("user_name");
    var password = credential.getAttribute("password");
    var httpRequestSignedData = new sn_auth.HttpRequestAuthedData();
    var directive = requestData.getDirective();
    var b64data = GlideStringUtil.base64encode(username+":"+password);

    // set CREDENTIAL_VALUE
    httpRequestSignedData.setCredentialValue("Basic " + b64data);
    httpRequestSignedData.setDirective("CREDENTIAL_VALUE");
    httpRequestSignedData.setStatus("SUCCESS");
    return httpRequestSignedData;
  },
  type: 'RequestAuthGCISigner'
});

    HttpRequestAuthedData - setDirective(cadeia de caracteres "diretiva")

    Define se a assinatura deve ser aplicada à solicitação assinada no cabeçalho, como um parâmetro de consulta ou como um valor de credencial.

    Tabela 20. Parâmetros
    Nome Tipo Descrição
    diretiva Cadeia de caracteres Se a assinatura deve ser aplicada ao cabeçalho, ao parâmetro de consulta ou ao valor de credencial da solicitação assinada.

    Os valores incluem:

    • query: aplica assinatura como um parâmetro de consulta.
    • header: aplica assinatura ao cabeçalho da solicitação.
    • credential_value : aplica assinatura ao valor de credencial.
    Tabela 21. Retorna
    Tipo Descrição
    vazio 
    // Define HttpRequestData
var endpoint= "https://third-party-endpoint";
var httpRequestData = new sn_auth.HttpRequestData();
httpRequestData.setEndpoint(endpoint);
httpRequestData.setService('s3');
httpRequestData.setRegion('us-east-1');
httpRequestData.setHttpMethod("PUT");
var content = "Action=SendMessage&MessageBody=This is a test message";
httpRequestData.setContent(content);
 
//Get AuthCredential
var credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID("5b61c16f73533300f662cff8faf6a74b");
 
// Create RequestAuthAPI and sign the request
var signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);
var output = signingAPI.generateAuth();
output.setDirective("header");

    HttpRequestAuthedData - setStatus(cadeia de caracteres status)

    Define o status da solicitação de assinatura.

    Tabela 22. Parâmetros
    Nome Tipo Descrição
    status Cadeia de caracteres O status da solicitação de assinatura.

    Valores possíveis:

    • sucesso: o sistema assinou a solicitação com sucesso.
    • fail: o sistema falhou ao assinar a solicitação.
    • ignorado: o sistema ignorou a assinatura porque as informações estavam incompletas.
    Tabela 23. Retorna
    Tipo Descrição
    vazio 
    // Define the HttpRequestData object
var endpoint= "https://third-party-endpoint";
var httpRequestData = new sn_auth.HttpRequestData();
httpRequestData.setEndpoint(endpoint);
httpRequestData.setService('s3');
httpRequestData.setRegion('us-east-1');
httpRequestData.setHttpMethod("PUT");
var content = "Action=SendMessage&MessageBody=This is a test message";
httpRequestData.setContent(content);
 
// Get an AuthCredential object
var credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID("5b61c16f73533300f662cff8faf6a74b");
 
// Create the RequestAuthAPI object and sign the request
var signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);
var output = signingAPI.generateAuth();
output.setStatus("fail");
 
// Get the signed status
gs.info("Status is: " + output.getStatus());

    Saída:

     Status is: FAIL

    HttpRequestAuthedData - setStatusMessage(cadeia de caracteres statusMessage)

    Define uma mensagem de status para a assinatura da solicitação.

    Tabela 24. Parâmetros
    Nome Tipo Descrição
    statusMessage Cadeia de caracteres Mensagem a ser definida para o status de assinatura da solicitação.
    Tabela 25. Retorna
    Tipo Descrição
    vazio 
    // Define the HttpRequestData object
var endpoint= "https://third-party-endpoint";
var httpRequestData = new sn_auth.HttpRequestData();
httpRequestData.setEndpoint(endpoint);
httpRequestData.setService('s3');
httpRequestData.setRegion('us-east-1');
httpRequestData.setHttpMethod("PUT");
var content = "Action=SendMessage&MessageBody=This is a test message";
httpRequestData.setContent(content);
 
// Get an AuthCredential object
var credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID("5b61c16f73533300f662cff8faf6a74b");
 
// Create the RequestAuthAPI object and sign the request
var signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);
var output = signingAPI.generateAuth();
output.setStatusMessage("The request was successfully signed.");
 
// Get the signed status message
gs.info("Status message is: " + output.getStatusMessage());

    Saída:

    Status message is: The request was successfully signed.