{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":40390,"path":"platform-security/authentication/add-OIDC-entity.md","title":"Configure an OAuth OIDC provider for accepting third-party token","bundle":null,"doc_type":null,"release":"australia","body":"\n# Configure an OAuth OIDC provider for accepting third-party token\n\nConfigure an OAuth OpenID Connect \\(OIDC\\) provider to accept identity tokens generated by a third-party OIDC provider using inbound API calls using Single Sign-On option \\(Multi-Provider SSO\\).\n\n## Before you begin\n\nRole required: oauth\\_admin\n\n## About this task\n\nThe ServiceNow AI Platform supports OpenID Connect \\(OIDC\\) through the external Single Sign-On \\(SSO\\) implementation in addition to inbound API calls.\n\nFor an example of an OIDC provider configuration, see [Set up Microsoft Entra ID spoke](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/integrate-applications/set-up-azure.md). For an SSO-specific example of an OIDC provider configuration, see [Create an OpenID Connect \\(OIDC\\) configuration for Single Sign-On \\(SSO\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/platform-security/authentication/create-OIDC-configuration-SSO.md).\n\n## Procedure\n\n1.  Navigate to **All** &gt; **System OAuth** &gt; **Application Registry**.\n\n2.  Select **New**, then select **Configure an OIDC provider to verify ID tokens**, and then fill in the form.\n\n    Alternately, you can select an existing template for an OIDC provider \\(ADFS, Auth0, Azure AD, Google, Okta\\), and then fill in the form.\n\n<table id=\"table_sgc_qqv_yq\"><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\nA unique name that identifies the OAuth OIDC entity.\n\n</td></tr><tr><td>\n\nClient ID\n\n</td><td>\n\nThe client ID of the application registered in the third-party OAuth OIDC server. This value should be the same as the value of the `aud` claim in the JWT token.\n\n</td></tr><tr><td>\n\nOAuth API Script\n\n</td><td>\n\nA script you can use to customize requests and responses to an external OAuth provider.\n\n</td></tr><tr><td>\n\nOAuth OIDC Provider Configuration\n\n</td><td>\n\nThe OIDC providers \\(ADFS, Auth0, Azure AD, Google, Okta\\) can be used to validate the JWT token. Select the record of your OIDC provider configuration to validate the **User Claim** and **User Field** are set appropriately. Also, make sure to fill the following fields:\n\n-   **Enable JTI claim verification**: When enables,the ServiceNow JWT token validation also validates the JTI sent by the provider.\n-   **OIDC Metadata URL**: Details of the Well-known configuration of the OIDC provider.\n**Note:** If validation isn’t checked, the `jti` can’t be validated, regardless if it’s present in the JWT token. The claim name in the token must be `jti`.\n\n</td></tr><tr><td>\n\nClock Skew\n\n</td><td>\n\nThe number, in seconds, for the constraint to be considered valid. The default is 300.\n\n</td></tr><tr><td>\n\nEnforce Token Restrictions\n\n</td><td>\n\nSelect this option to allow only tokens used with APIs set to enable the authentication profile. You can grant access using an API access policy. For more information, see [Create REST API access policy](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/platform-security/authentication/create-api-access-policy.md).\n\n</td></tr><tr><td>\n\nActive\n\n</td><td>\n\nSelect the check box to make the OAuth application active.\n\n</td></tr><tr><td>\n\nClient Type\n\n</td><td>\n\nChoose the client type, based on the type of your client. Options:-   **Iframe Embedded**\n-   **Integration as a User**\n-   **Integration as a Service**\nTo learn more, see [Configure client type for OAuth and SSO records](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/platform-security/authentication/client-type.md).\n\n</td></tr></tbody>\n</table>3.  Select **Submit**.\n\n    The record is saved in the Application Registries \\[oauth\\_entity\\] table.\n\n    When your instance issues tokens and authorization codes it creates a record in the Application Registries \\[oauth\\_entity\\] table with type **External OIDC Provider**. For more information, see .\n\n4.  Go to the related list on the record OAuth Entity Profiles to validate a system-generated default profile for the new OAuth provider without any scope.\n\n    You can change or add an OAuth provider profile including the name, grant type, and OAuth Scope.\n\n5.  Go to the related list on the record OAuth Entity Scopes to define all available OAuth scopes for this OAuth provider.\n\n    The scopes defined can be selected when you create or update a profile. Each OAuth scope defined contains a name and a scope that you must get from the provider specification, such as a read-scope or a write-scope. Each scope must be defined separately.\n\n6.  Go to the related list on the record User Provisioning to enable automatic user provisioning.\n\n<table id=\"choicetable_wzq_2cc_l2b\"><tbody><tr><td id=\"d269061e308\">\n\n**Automatically provision users**\n\n</td><td>\n\nOption to enable force authentication for users.\n\n</td></tr><tr><td id=\"d269061e317\">\n\n**Provision data source**\n\n</td><td>\n\nThe data source to use to transform an OIDC token to a ServiceNow user. Use the **Lookup list** to select the predefined data source template, then open the record to configure the Transformed table mapping. When configuring the Transform mapping, the source fields are from the **JWT token**, the target fields are from the **sys\\_user** table.\n\n</td></tr><tr><td id=\"d269061e338\">\n\n**User roles applied to provisioned users**\n\n</td><td>\n\nThe user roles applied to the newly provisioned ServiceNow users.\n\n</td></tr></tbody>\n</table>\n## The following is an example of a cURL request to invoke a REST API call\n\nInvoke a REST API call.\n\nPerform the following steps:\n\n1.  Register the app in the OpenID Connect Provider.\n2.  Configure the OAuth OIDC Entity.\n3.  Configure the OIDC Provider:\n\n<table id=\"table_wmd_ddz_gbc\"><thead><tr><th>\n\n \n\n</th><th>\n\n \n\n</th></tr></thead><tbody><tr><td>\n\nOIDC Provider\n\n</td><td>\n\nName of the OIDC provider.\n\n</td></tr><tr><td>\n\nOIDC Metadata URL\n\n</td><td>\n\nSpecify the OIDC Metadata URL \\(well-known configuration URL\\). This information is used to fetch the public keys to validate the token through the `jwks` endpoint.\n\n</td></tr><tr><td>\n\nUser Claim\n\n</td><td>\n\nThe the claim which is validated against user table.\n\n</td></tr><tr><td>\n\nUser Field\n\n</td><td>\n\nUser claim which identifies user record.\n\n</td></tr><tr><td>\n\nEnable JTI claim verification\n\n</td><td>\n\nWhen enabled, the ServiceNow JWT token validation will also validate the JTI sent by the provider. **Note:** If validation isn’t checked, the `jti` can’t be validated, regardless if it’s present in the JWT token. The claim name in the token must be `jti`. This information is used to help prevent replay attacks.\n\n</td></tr></tbody>\n</table>4.  Get a JWT token from your OIDC provider. The method depends on your provider and the OAuth flow your application uses. For example, to get an ID token from Okta using a resource owner password grant:\n\n    ```\n    curl -X POST https://<your-okta-domain>/oauth2/default/v1/token \\\n      -H \"Accept: application/json\" \\\n      -H \"Content-Type: application/x-www-form-urlencoded\" \\\n      --data-urlencode \"grant_type=password\" \\\n      --data-urlencode \"username=<user@example.com>\" \\\n      --data-urlencode \"password=<password>\" \\\n      --data-urlencode \"scope=openid\" \\\n      --data-urlencode \"client_id=<client_id>\" \\\n      --data-urlencode \"client_secret=<client_secret>\"\n    ```\n\n    Copy the `id_token` value from the response. Use this as the Bearer token in the next step.\n\n5.  Invoke a REST API call.\n    1.  Use the ID token in the Authorization header to access the Table API or a scripted web service.\n\n        ```\n        curl -X GET --header \"Accept:application/json\" https://<instance_name>.service-now.com/api/now/table/incident/897b04f2dbd4a300a135364e9d961952 -k \n        --header \"Authorization: Bearer eyJraWQiOiJjNTZtZTlXU0xPVnY3UFMwcTg4Qzl1b0lzNjFQYTdmUG4yZFVFOW9RNUg4IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiIwMHVnZDg1OD\n        VkczI1WXpUSjBoNyIsIm5hbWUiOiJpbXJhbiBhbGkiLCJsb2NhbGUiOiJlbi1VUyIsImVtYWlsIjoiaW1yb241NDNAZ21haWwuY29tIiwidmVyIjoxLCJpc3MiOiJodHRwczovL2Rldi05MzQ\n        xMjEub2t0YXByZXZpZXcuY29tIiwiYXVkIjoiMG9hZ2Q4bzk3a2lCT3dwd0IwaDciLCJpYXQiOjE1Mzc5MzMzMjYsImV4cCI6MTUzNzkzNjkyNiwianRpIjoiSUQueThVdXpWNUg2bm16SzRs\n        OTI1RFVrQnJoR1o1MmJzVVpGVHRVTEphQjg3ayIsImFtciI6WyJwd2QiXSwiaWRwIjoiMDBvZ2Q4NTgycEFqZDZTemcwaDciLCJub25jZSI6InNub3ciLCJwcmVmZXJyZWRfdXNlcm5hbWUiO\n        iJpbXJvbjU0M0BnbWFpbC5jb20iLCJnaXZlbl9uYW1lIjoiaW1yYW4iLCJmYW1pbHlfbmFtZSI6ImFsaSIsInpvbmVpbmZvIjoiQW1lcmljYS9Mb3NfQW5nZWxlcyIsInVwZGF0ZWRfYXQiOj\n        E1Mzc5MzAxOTcsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJhdXRoX3RpbWUiOjE1Mzc5Mjk2NjF9.OG87SYxWFgHGlhBYby2H79diRm9rlYZTeEkIINRUatwg-p4739htB8xEY-5_t6yU_6k5w1\n        0pdgtt5M5QFZRPXVbQZNoGtY-Bxn0BjaimcFgoWfhY_0ldnGTkzN2RYyIHvrf9-yhxg347zvczmLrgMMa_VwG4rxrtE6rUXaIpIeIK5b-Deq8ADz8UTUTKpF_5RWk4X-oh5xK6BLniFHk4ShO\n        Zq2v_mjproXwKk5euJKrVrar2lQ4adZCOSTRuTf3ThMO5WDh0sel-82LngXtLzRJJ51IqxAsXns0kJHLLqLtH1hXNRKfwT1ScQoE_OfWm4t0KryI2j4wSMEanFtLXIw\"\n        ```\n\n    2.  If the user is authenticated, a valid application/json response is returned. Otherwise, a \"User Not Authenticated\" error message is returned.\n\n        ```\n        User Not Authenticated\n        {\"error\":{\"message\":\"User Not Authenticated\",\"detail\":\"Required to provide Auth information\"},\"status\":\"failure\"}\n        ```\n\n\n"}}