{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":40478,"path":"platform-security/authentication/configure-hmac.md","title":"Configure HMAC - Token-based authentication","bundle":null,"doc_type":null,"release":"australia","body":"\n# Configure HMAC - Token-based authentication\n\nConfigure HMAC to support authentication for REST API endpoints.\n\n## Before you begin\n\nRole required: api\\_service\\_admin, adaptive\\_auth\\_policy\\_admin\n\nPlugin required: API Key and HMAC Authentication \\(`com.glide.tokenbased_auth`\\)\n\n**Note:** While configuring the HMAC, ensure the name of the script that starts with HMAC to populated in the script list view.\n\n## Procedure\n\n1.  Create an HMAC configuration.\n\n    1.  Navigate to **All** &gt; **System Web Services** &gt; **API Access Policies** &gt; **HMAC Configuration**.\n\n    2.  Select **New**.\n\n        **Note:** You can also use the **Default HMAC SHA256 Base64 Encoding** which is created when installing the plugin.\n\n    3.  On the form, fill the fields:\n\n<table id=\"table_y3b_h1f_nzb\"><thead><tr><th>\n\nField\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nName\n\n</td><td>\n\nName for the HMAC configuration.\n\n</td></tr><tr><td>\n\nApplication\n\n</td><td>\n\nScope of the configuration.\n\n</td></tr><tr><td>\n\nDescription\n\n</td><td>\n\nDetailed description about the configuration.\n\n</td></tr><tr><td>\n\nHash Algorithm\n\n</td><td>\n\nChoose the Hash Algorithm. Options available:-   HmacSHA256\n-   HmacSHA384\n-   HmacSHA512\n\n\n</td></tr><tr><td>\n\nHMAC util script\n\n</td><td>\n\nUtility script for HMAC.**Note:** If you validate HMAC authentication using Request body, Time stamp and Secret with no Key Id, then do the following:\n\n-   Create a customized script include as HMAC util script\n-   Use that script include util to interpret the passed in timestamp, and request body.\nFor every shared secret created in the ServiceNow® instance, there is a key ID. You need to configure the key ID into Default key id in HMAC auth profile.\n\n</td></tr></tbody>\n</table>        \\[Omitted image \"configure-hmac.png\"\\] Alt text: HMAC Configuration\n\n    4.  Submit the record.\n\n2.  Create an inbound authentication profile.\n\n    1.  Navigate to **All** &gt; **System Web Services** &gt; **API Access Policies** &gt; **Inbound Authentication Profiles**.\n\n    2.  Select **New**.\n\n        The system displays the message `What kind of authentication profile?`\n\n    3.  Select **Create HMAC authentication profiles**.\n\n        \\[Omitted image \"hmac-profile.png\"\\] Alt text: HMAC authentication profile\n\n    4.  On the form, fill in the fields.\n\n<table id=\"table_nnk_yqx_mzb\"><thead><tr><th>\n\nField\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nName\n\n</td><td>\n\nName to identify the authentication policy.\n\n</td></tr><tr><td>\n\nApplication\n\n</td><td>\n\nScope of the authentication policy.\n\n</td></tr><tr><td>\n\nConfiguration for HMAC\n\n</td><td>\n\nSelect the HMAC configuration that was created.\n\n</td></tr><tr><td>\n\nAuth Parameter\n\n</td><td>\n\nSelect the auth parameter for the authentication request. You can select the default options or create a new auth parameter:-   x-sn-hmac-signature-256: Auth Header\n-   x-sn-hmac-signature-256: Query Parameter\n\n\n</td></tr><tr><td>\n\nDefault Key ID of Shared Secret\n\n</td><td>\n\nThe token information that can be updated in this field for using HMAC.\n\n</td></tr></tbody>\n</table>        **Note:** The selected option has to be defined in the REST call as part of the Auth Header or Query Parameter.\\[Omitted image \"hmac-parameter.png\"\\] Alt text: HMAC Profile\n\n    5.  Submit the form.\n\n3.  Create an HMAC secret.\n\n    1.  Navigate to **All** &gt; **System Web Services** &gt; **API Access Policies** &gt; **REST API HMAC Secret**.\n\n    2.  Select **New**.\n\n    3.  On the form, fill the fields:\n\n<table id=\"table_tpz_x1f_nzb\"><thead><tr><th>\n\nField\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nName\n\n</td><td>\n\nName to identify the REST API HMAC secret.\n\n</td></tr><tr><td>\n\nDescription\n\n</td><td>\n\nDescription for the REST API HMAC secret.\n\n</td></tr><tr><td>\n\nActive\n\n</td><td>\n\nStatus of the REST API HMAC secret.\n\n</td></tr><tr><td>\n\nUser\n\n</td><td>\n\nUser associated to the REST API HMAC secret. Use the look-up icon to select the user.\n\n</td></tr><tr><td>\n\nKey ID\n\n</td><td>\n\nKey ID that must be sent as part of the REST call. Key ID is generated after submitting the form.\n\n</td></tr><tr><td>\n\nShared Secret\n\n</td><td>\n\nShared secrets of the user. For example, the password.\n\n</td></tr><tr><td>\n\nSource\n\n</td><td>\n\nSource of the record.\n\n</td></tr><tr><td>\n\nExpiry\n\n</td><td>\n\nTime after which the credential is no longer valid. Empty value means no expiration.**Note:** For more information, about expiry of token, see [Cleaning up token Expiry](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/platform-security/authentication/token-expiry-api-and-hmac.md) .\n\n</td></tr></tbody>\n</table>    4.  Submit the form.\n\n    5.  Open the record that was created.\n\n        Find the Key ID generated by the ServiceNow AI Platform for the user.\n\n        \\[Omitted image \"hmac-key.png\"\\] Alt text: HMAC Key ID\n\n        **Note:** You can add the Key ID that was generated during the Key ID in the Authentication Profile that was created for HMAC if you don't want to specify the Auth or Query parameter for the API call.\n\n4.  Create a REST API access policy.\n\n    1.  Navigate to **All** &gt; **System Web Services** &gt; **REST API Access Policies**.\n\n    2.  Select **New**.\n\n    3.  On the form, fill in the fields.\n\n<table id=\"table_d4x_w45_d4b\"><thead><tr><th>\n\nField\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nName\n\n</td><td>\n\nUnique name of the API access policy.\n\n</td></tr><tr><td>\n\nActive\n\n</td><td>\n\nOption to make the API access policy active.\n\n</td></tr><tr><td>\n\nREST API\n\n</td><td>\n\nThe REST API to which the access policy is applied. For example, **Attachment API**.\n\n</td></tr><tr><td>\n\nREST API PATH\n\n</td><td>\n\nAPI path of the REST API. This field is auto-populated based on the selected REST API. For example, **now/attachment**.\n\n</td></tr><tr><td>\n\nHTTP Method\n\n</td><td>\n\nMethod used for interacting with the API. This field is auto-populated based on the selected REST API.\n\n</td></tr><tr><td>\n\nVersion\n\n</td><td>\n\nVersion of the API. For example, **v1**. This field is auto-populated based on the selected REST API.**Note:** If you want to create an authentication policy for all versions of a REST API, you must create individual policies for each version.\n\n</td></tr><tr><td>\n\nResource\n\n</td><td>\n\nChild resource of the REST API. This field is auto-populated based on the selected REST API. For example, **/now/attachment**\n\n</td></tr><tr><td>\n\nApplication\n\n</td><td>\n\nScope of the application.\n\n</td></tr><tr><td>\n\nGlobal\n\n</td><td>\n\nEnable this field to apply auth policy to all methods, versions, and resources for the API.**Note:** Token Based Auth isn’t allowed in the Global REST API Policy.\n\n</td></tr><tr><td>\n\nApply to all methods\n\n</td><td>\n\nEnable this field to apply the auth policy for the API to all the methods, versions, and resources for the API.\n\n</td></tr><tr><td>\n\nApply to all resources\n\n</td><td>\n\nEnable this field to apply the auth policy for the API to all the versions.\n\n</td></tr><tr><td>\n\nApply to all versions\n\n</td><td>\n\nEnable this field to apply the auth policy for the API to all the resources.\n\n</td></tr></tbody>\n</table>    4.  Add the API authentication profile that was created.\n\n        \\[Omitted image \"hmac-profile-added.png\"\\] Alt text: HMAC Profile added to Access Policy\n\n    5.  Submit the form.\n\n        You can send the REST API call:\n\n        -   With the x-sn-hmac-signature-256 that was generated by ServiceNow® during the API Key creation within the Header or Query parameter based on the configuration for authentication.\n        -   With pre-request Script with Shared Secret specified as part of the request.\n        **Warning:** Use **POST** request when submitting any sensitive information to the server.\n\n\n"}}