{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":824,"path":"api-reference/server-api-reference/HttpRequestAuthedDataAPI.md","title":"HttpRequestAuthedData - Scoped","bundle":null,"doc_type":null,"release":"australia","body":"\n# HttpRequestAuthedData- Scoped\n\nThe HttpRequestAuthedData\\(\\) API provides methods to access and set values in a signed REST or SOAP request.\n\nGenerate outbound signing requests using these APIs in the following order:\n\n1. HttpRequestData: Build the API request.\n2. AuthCredential: Create a credential object or update an existing one. Use the credential to sign the request through the RequestAuthAPI class.\n3. RequestAuthAPI: Sign the request and return an HttpRequestAuthedData object.\n4. HttpRequestAuthedData: Get information about the signed request.\n5. GlideHTTPRequest: Send the signed request.\n\nBefore using these APIs, you must [configure an authentication algorithm](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/configure-authentication-algorithm.md) to sign the request and associate it with the credential used to authenticate the request.\n\nUse this API in scoped scripts with the `sn_auth` namespace identifier. You can instantiate this class using the constructor, or you can return an HttpRequestAuthedData object from the generateAuth\\(\\) method in the RequestAuthAPI class.\n\n**Parent Topic:**[Server API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/api-server.md)\n\n## HttpRequestAuthedData - HttpRequestAuthedData\\(\\)\n\nInstantiates an HttpRequestAuthedData object.\n\nYou can instantiate this class using the constructor, or you can return an HttpRequestAuthedData object from the generateAuth\\(\\) method in the RequestAuthAPI class.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n## HttpRequestAuthedData - addHeader\\(String key, String value\\)\n\nAdds a header to the HttpRequestAuthedData object.\n\n|Name|Type|Description|\n|----|----|-----------|\n|key|String|Name of the HTTP header.|\n|value|String|Value of the HTTP Header.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\n// Define HttpRequestData\nvar endpoint= \"https://third-party-endpoint\";\nvar httpRequestData = new sn_auth.HttpRequestData();\nhttpRequestData.setEndpoint(endpoint);\nhttpRequestData.setService('s3');\nhttpRequestData.setRegion('us-east-1');\nhttpRequestData.setHttpMethod(\"PUT\");\nvar content = \"Action=SendMessage&MessageBody=This is a test message\";\nhttpRequestData.setContent(content);\n \n//Get AuthCredential\nvar credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID(\"5b61c16f73533300f662cff8faf6a74b\");\n \n// Create RequestAuthAPI and sign the request\nvar signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);\nvar output = signingAPI.generateAuth();\n \n// Update the signed response\noutput.addHeader('access-rights', 'public-read');\n```\n\n## HttpRequestAuthedData - addQueryParam\\(String key, String value\\)\n\nAdds a query parameter to the HttpRequestAuthedData object.\n\n|Name|Type|Description|\n|----|----|-----------|\n|key|String|Name of the query parameter.|\n|value|String|Value of the query parameter.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\n// Define HttpRequestData\nvar endpoint= \"https://third-party-endpoint\";\nvar httpRequestData = new sn_auth.HttpRequestData();\nhttpRequestData.setEndpoint(endpoint);\nhttpRequestData.setService('s3');\nhttpRequestData.setRegion('us-east-1');\nhttpRequestData.setHttpMethod(\"PUT\");\nvar content = \"Action=SendMessage&MessageBody=This is a test message\";\nhttpRequestData.setContent(content);\n \n//Get AuthCredential\nvar credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID(\"5b61c16f73533300f662cff8faf6a74b\");\n \n// Create RequestAuthAPI and sign the request\nvar signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);\nvar output = signingAPI.generateAuth();\n \n// Update the signed response\noutput.addQueryParameter('api_version', 'v2');\n```\n\n## HttpRequestAuthedData - getCredentialValue\\(\\)\n\nReturns the credential value that was included when the request was signed.\n\nUse a credential value to store a cookie, signature, or other value needed for an authentication algorithm. For example, create a Get Connection Info \\(GCI\\) step with a script that retrieves and stores a one-time token for a REST or SOAP call.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|String|Text of the credential value.|\n\nThis example shows the retrieval of a credential value.\n\n```\nvar RequestAuthGCISigner = Class.create();\nRequestAuthGCISigner.prototype = Object.extend(new RequestAuthInternal(), {\n initialize: function() {\n RequestAuthInternal.prototype.initialize.call(this);\n },\n\n generateAuth: function(authAPI) {\n var requestData = authAPI.getHttpRequestData();\n\n // get credentials\n var credential = authAPI.getAuthCredential();\n var username = credential.getAttribute(\"user_name\");\n var password = credential.getAttribute(\"password\");\n var httpRequestSignedData = new sn_auth.HttpRequestAuthedData();\n var directive = requestData.getDirective();\n\n // set CREDENTIAL_VALUE\n httpRequestSignedData.setCredentialValue(username+\":\"+password);\n httpRequestSignedData.setDirective(\"CREDENTIAL_VALUE\");\n httpRequestSignedData.setStatus(\"SUCCESS\");\n\n gs.info(\"The Credential Value is \" + httpRequestSignedData.getCredentialValue());\n return httpRequestSignedData;\n },\n type: 'RequestAuthGCISigner'\n});\n```\n\nOutput:\n\n```\nThe Credential Value is someUsername:somePassword\n```\n\n## HttpRequestAuthedData - getDirective\\(\\)\n\nReturns whether the signature is applied to the request in the header, as a query parameter, or as a credential value.\n\nBy default, the system applies the signature to the header. You can apply the signature as a query parameter or credential value by using the setDirective\\(\\) API.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n\n
\n\nType\n\n\n\nDescription\n\n
\n\nString\n\n\n\nWhether the signature is applied to the header, as a query parameter, or as a credential value. Values include:\n\n - HEADER: The signature is applied to the request header.\n- QUERY: The signature is applied as a query parameter.\n- CREDENTIAL\\_VALUE: The signature is applied as a credential value.\n\n
```\n// Define HttpRequestData\nvar endpoint= \"https://third-party-endpoint\";\nvar httpRequestData = new sn_auth.HttpRequestData();\nhttpRequestData.setEndpoint(endpoint);\nhttpRequestData.setService('s3');\nhttpRequestData.setRegion('us-east-1');\nhttpRequestData.setHttpMethod(\"PUT\");\nvar content = \"Action=SendMessage&MessageBody=This is a test message\";\nhttpRequestData.setContent(content);\n \n//Get AuthCredential\nvar credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID(\"5b61c16f73533300f662cff8faf6a74b\");\n \n// Create RequestAuthAPI and sign the request\nvar signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);\nvar output = signingAPI.generateAuth();\noutput.setDirective(\"header\");\n\ngs.info(\"Signature applied to: \" + output.getDirective());\n```\n\nOutput:\n\n```\nSignature applied to: HEADER\n```\n\n## HttpRequestAuthedData - getHeaderMap\\(\\)\n\nReturns an object containing the headers that were included when the request was signed.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n\n
\n\nType\n\n\n\nDescription\n\n
\n\nObject\n\n\n\nKey-value pairs that define all of the headers included when the request was signed. Each key-value pair includes these parts:- key: String. Name of the header.\n- value: String. Value of the header.\n\n
```\n// Define the HttpRequestData object\nvar endpoint= \"https://third-party-endpoint\";\nvar httpRequestData = new sn_auth.HttpRequestData();\nhttpRequestData.setEndpoint(endpoint);\nhttpRequestData.setService('s3');\nhttpRequestData.setRegion('us-east-1');\nhttpRequestData.setHttpMethod(\"PUT\");\nvar content = \"Action=SendMessage&MessageBody=This is a test message\";\nhttpRequestData.setContent(content);\nhttpRequestData.addHeader('x-amz-acl' , 'public-read' );\n \n// Get an AuthCredential object\nvar credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID(\"5b61c16f73533300f662cff8faf6a74b\");\n \n// Create the RequestAuthAPI object and sign the request\nvar signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);\nvar output = signingAPI.generateAuth();\n \n// get the signed response detail\nvar authH = headerM[\"Authorization\"];\nvar xamzdateH = headerM[\"X-Amz-Date\"];\nvar content256 = headerM[\"x-amz-content-sha256\"];\n \ngs.debug('authH:' + authH );\ngs.debug('xamzdateH:' + xamzdateH );\ngs.debug('content256:' + content256 );\n\n```\n\nOutput:\n\n```\n*** Script: [DEBUG] authH:AWS4-HMAC-SHA256 Credential=lsjfljljfllfwek/20191127/us-east-1/s3/aws4_request, \nSignedHeaders=host;x-amz-acl;x-amz-content-sha256;x-amz-date, \nSignature=5c349011324910c34596ba7abbd10e07c4127774049f8953418bd7bed7d02b90 \n*** Script: [DEBUG] xamzdateH:20191127T175210Z \n*** Script: [DEBUG] content256:UNSIGNED-PAYLOAD\n```\n\n## HttpRequestAuthedData - getQueryMap\\(\\)\n\nReturns an object containing the query parameters included when the request was signed.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n\n
\n\nType\n\n\n\nDescription\n\n
\n\nObject\n\n\n\nKey-value pairs that define the query parameters included when the request was signed. Each key-value pair includes these parts:- key: String. Name of the query parameter.\n- value: String. Value of the query parameter.\n\n
```\n// Define the HttpRequestData object\nvar endpoint= \"https://third-party-endpoint\";\nvar httpRequestData = new sn_auth.HttpRequestData();\nhttpRequestData.setEndpoint(endpoint);\nhttpRequestData.setService('s3');\nhttpRequestData.setRegion('us-east-1');\nhttpRequestData.setHttpMethod(\"PUT\");\nvar content = \"Action=SendMessage&MessageBody=This is a test message\";\nhttpRequestData.setContent(content);\nhttpRequestData.addQueryParam('api_version', 'v2' );\nhttpRequestData.addQueryParam('limit', '1000' );\nhttpRequestData.addQueryParam('offset', '1' );\n \n// Get an AuthCredential object\nvar credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID(\"5b61c16f73533300f662cff8faf6a74b\");\n \n// Create the RequestAuthAPI object and sign the request\nvar signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);\nvar output = signingAPI.generateAuth();\n \n// Get the signed response\nqueryMap = output.getQueryMap();\n\ngs.info(\"API Version is: \" + queryMap[\"api_version\"]);\n```\n\nOutput:\n\n```\nAPI Version is: v2\n```\n\n## HttpRequestAuthedData - getStatus\\(\\)\n\nReturns the status of the request signing.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n\n
\n\nType\n\n\n\nDescription\n\n
\n\nString\n\n\n\nThe status of the request signing. Possible values:\n\n - SUCCESS: The system successfully signed the request.\n- FAIL: The system failed to sign the request.\n- SKIPPED: The system skipped signing because the information was incomplete.\n\n
```\n// Define the HttpRequestData object\nvar endpoint= \"https://third-party-endpoint\";\nvar httpRequestData = new sn_auth.HttpRequestData();\nhttpRequestData.setEndpoint(endpoint);\nhttpRequestData.setService('s3');\nhttpRequestData.setRegion('us-east-1');\nhttpRequestData.setHttpMethod(\"PUT\");\nvar content = \"Action=SendMessage&MessageBody=This is a test message\";\nhttpRequestData.setContent(content);\n \n// Get an AuthCredential object\nvar credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID(\"5b61c16f73533300f662cff8faf6a74b\");\n \n// Create the RequestAuthAPI object and sign the request\nvar signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);\nvar output = signingAPI.generateAuth();\n \n// Get the signed status\ngs.info(\"Status is: \" + output.getStatus());\n```\n\nOutput:\n\n```\nStatus is: SUCCESS\n```\n\n## HttpRequestAuthedData - getStatusMessage\\(\\)\n\nReturns a detailed message about the request signing. If the request signing fails, this method returns the error message.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n\n
\n\nType\n\n\n\nDescription\n\n
\n\nString\n\n\n\nMessage about the request signing. If the request signing fails, returns one of these error messages:- `credential is not valid`: Check the AuthCredential object you used to sign the request. Make sure an authentication algorithm is associated with the credential. For more information, see [Configure an authentication algorithm](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/configure-authentication-algorithm.md).\n- `Request data is empty. Request auth is skipped`: Check the HttpRequestData object because required information may be missing.\n- `Can't find script includes scope`: Verify that the authentication algorithm record and associated script includes used to sign the request are in the correct scope.\n\n
```\n// Define the HttpRequestData object\nvar endpoint= \"https://third-party-endpoint\";\nvar httpRequestData = new sn_auth.HttpRequestData();\nhttpRequestData.setEndpoint(endpoint);\nhttpRequestData.setService('s3');\nhttpRequestData.setRegion('us-east-1');\nhttpRequestData.setHttpMethod(\"PUT\");\nvar content = \"Action=SendMessage&MessageBody=This is a test message\";\nhttpRequestData.setContent(content);\nhttpRequestData.addQueryParam('api_version', 'v2' );\nhttpRequestData.addQueryParam('limit', '1000' );\nhttpRequestData.addQueryParam('offset', '1' );\n \n// Get AuthCredential object and set an attribute\nvar credential = new sn_auth.AuthCredential();\ncredential.setAttribute(\"user_name\", \"admin\");\ncredential.setAttribute(\"password\", \"admin\");\n \n// Create the RequestAuthAPI object and sign the request\nvar signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);\nvar output = signingAPI.generateAuth();\n \n// Get the signed status\ngs.info(\"Status message is: \" + output.getStatusMessage());\n```\n\nOutput:\n\n```\nStatus message is: credential is not valid.\n```\n\n## HttpRequestAuthedData - setCredentialValue\\(String credential\\_value\\)\n\nSets a credential value for the HttpRequestAuthedData object.\n\nUse a credential value to store a cookie, signature, or other value needed for an authentication algorithm. For example, create a Get Connection Info \\(GCI\\) step with a script that retrieves and stores a one-time token for a REST or SOAP call.\n\nUse the setCredentialValue\\(\\) method to set the **Credential Value** data pill for REST, SOAP, and GCI steps in Workflow Studio.\n\n|Name|Type|Description|\n|----|----|-----------|\n|credential\\_value|String|Text of the credential value.|\n\n|Type|Description|\n|----|-----------|\n|None| |\n\nThis example shows how to set a credential value for a GCI step.\n\n```\nvar RequestAuthGCISigner = Class.create();\nRequestAuthGCISigner.prototype = Object.extend(new RequestAuthInternal(), {\n initialize: function() {\n RequestAuthInternal.prototype.initialize.call(this);\n },\n\n generateAuth: function(authAPI) {\n var requestData = authAPI.getHttpRequestData();\n\n // get credentials\n var credential = authAPI.getAuthCredential();\n var username = credential.getAttribute(\"user_name\");\n var password = credential.getAttribute(\"password\");\n var httpRequestSignedData = new sn_auth.HttpRequestAuthedData();\n var directive = requestData.getDirective();\n var b64data = GlideStringUtil.base64encode(username+\":\"+password);\n\n // set CREDENTIAL_VALUE\n httpRequestSignedData.setCredentialValue(\"Basic \" + b64data);\n httpRequestSignedData.setDirective(\"CREDENTIAL_VALUE\");\n httpRequestSignedData.setStatus(\"SUCCESS\");\n return httpRequestSignedData;\n },\n type: 'RequestAuthGCISigner'\n});\n```\n\n## HttpRequestAuthedData - setDirective\\(String directive\\)\n\nDefines whether to apply the signature to the signed request in the header, as a query parameter, or as a credential value.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\ndirective\n\n\n\nString\n\n\n\nWhether to apply the signature to the header, query parameter, or credential value of the signed request. Values include:\n\n - `query`: Applies signature as a query parameter.\n- `header`: Applies signature to the request header.\n- `credential_value` : Applies signature to the credential value.\n\n
|Type|Description|\n|----|-----------|\n|void| |\n\n```\n// Define HttpRequestData\nvar endpoint= \"https://third-party-endpoint\";\nvar httpRequestData = new sn_auth.HttpRequestData();\nhttpRequestData.setEndpoint(endpoint);\nhttpRequestData.setService('s3');\nhttpRequestData.setRegion('us-east-1');\nhttpRequestData.setHttpMethod(\"PUT\");\nvar content = \"Action=SendMessage&MessageBody=This is a test message\";\nhttpRequestData.setContent(content);\n \n//Get AuthCredential\nvar credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID(\"5b61c16f73533300f662cff8faf6a74b\");\n \n// Create RequestAuthAPI and sign the request\nvar signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);\nvar output = signingAPI.generateAuth();\noutput.setDirective(\"header\");\n\n```\n\n## HttpRequestAuthedData - setStatus\\(String status\\)\n\nSets the status of the request signing.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\nstatus\n\n\n\nString\n\n\n\nThe status of the request signing. Possible values:\n\n - `success`: The system successfully signed the request.\n- `fail`: The system failed to sign the request.\n- `skipped`: The system skipped signing because the information was incomplete.\n\n
|Type|Description|\n|----|-----------|\n|void| |\n\n```\n// Define the HttpRequestData object\nvar endpoint= \"https://third-party-endpoint\";\nvar httpRequestData = new sn_auth.HttpRequestData();\nhttpRequestData.setEndpoint(endpoint);\nhttpRequestData.setService('s3');\nhttpRequestData.setRegion('us-east-1');\nhttpRequestData.setHttpMethod(\"PUT\");\nvar content = \"Action=SendMessage&MessageBody=This is a test message\";\nhttpRequestData.setContent(content);\n \n// Get an AuthCredential object\nvar credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID(\"5b61c16f73533300f662cff8faf6a74b\");\n \n// Create the RequestAuthAPI object and sign the request\nvar signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);\nvar output = signingAPI.generateAuth();\noutput.setStatus(\"fail\");\n \n// Get the signed status\ngs.info(\"Status is: \" + output.getStatus());\n```\n\nOutput:\n\n```\n Status is: FAIL\n```\n\n## HttpRequestAuthedData - setStatusMessage\\(String statusMessage\\)\n\nSets a status message for the request signing.\n\n|Name|Type|Description|\n|----|----|-----------|\n|statusMessage|String|Message to set for the request signing status.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\n// Define the HttpRequestData object\nvar endpoint= \"https://third-party-endpoint\";\nvar httpRequestData = new sn_auth.HttpRequestData();\nhttpRequestData.setEndpoint(endpoint);\nhttpRequestData.setService('s3');\nhttpRequestData.setRegion('us-east-1');\nhttpRequestData.setHttpMethod(\"PUT\");\nvar content = \"Action=SendMessage&MessageBody=This is a test message\";\nhttpRequestData.setContent(content);\n \n// Get an AuthCredential object\nvar credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID(\"5b61c16f73533300f662cff8faf6a74b\");\n \n// Create the RequestAuthAPI object and sign the request\nvar signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);\nvar output = signingAPI.generateAuth();\noutput.setStatusMessage(\"The request was successfully signed.\");\n \n// Get the signed status message\ngs.info(\"Status message is: \" + output.getStatusMessage());\n```\n\nOutput:\n\n```\nStatus message is: The request was successfully signed.\n```\n\n"}}