This is a cross-post of my article from https://sapphirenow.dev (https://sapphirenow.dev/post/wdc-oauth-part-1/). You can find the original and other articles I've written on this website, as well as a link to my YouTube channel where I occasionally post video content.
Up your OAuth2.0 Game in Washington DC with Inbound Client Credentials
This article and the following articles in the Up your OAuth2.0 series, will guide you through setting up different types of OAuth Clients and Providers, including extended concepts around OIDC and more! After the guide, I’ll also talk through brief cases of where you might use each variant.
Alongside implementing several inbound authentication flow features and improvements, ServiceNow has also implemented API Authentication Scopes in order to provide granular access to APIs through scope definitions. I’ll walk through an initial example in the guide, but this will likely warrant its own post at some point.
This first article focusses on Inbound API Authentication to your ServiceNow instance, using the Client Credentials grant which was implemented in the Washington DC release.
Guide:
This guide requires the user to have the admin role.
Preparing your instance:
There are two pre-requisites required to permit the client credentials flow in a Washington DC instance as of Early Access:
- Validate that the following four plugins are installed. This can be done by navigating to
Admin -> Application Manager, or by navigating tosys_plugins.listusing the Filter Navigator (UI15/16) or the Next Experience header menus, for example. Please install any that are not installed.OAuth 2.0(com.snc.platform.security.oauth)REST API Provider(com.glide.rest)Authentication scope(com.glide.auth.scope)REST API Auth Scope Plugin(com.glide.rest.auth.scope)- Note: In my Washington DC environment all four were already installed
- Navigate to the System Properties table and create or update the below property with the values listed. You can navigate to this table by navigating to
sys_properties.listusing the same method as above.- Name: glide.oauth.inbound.client.credential.grant_type.enabled
- Value: true
- Type: true | false
- Note: This flag is the primary mechanism for enabling and disabling this functionality
Creating an OAuth Client
You’ll now create a client and make an update to the OAuth Entity default view.
- Navigate to
System OAuth -> Application Registry. Create a new record, selectingCreate an OAuth API endpoint for external clientsfrom the interceptor list. Populate mandatory fields as you need. Save this record (or submit and return to the form).- Note: Redirect URL and Login URL are not required as they are not used by this grant type
- Note: Do not set Public Client to true, as RFC 6749, Section 4.4 indicates only confidential clients should use this flow. Section 2.1 of the same document defines client types.
- Using the context menu button indicated by the icon (or secondary/right click on the header bar), open the context menu and open
Configure -> Form Builder(Form Design and Layout will also work). Add the existingOAuth Application Userreference field to the ‘Default’ view, and save this change. - Populate the newly-available OAuth Application User with an appropriately permissioned user, and save the record.
An example of an OAuth Client after Step 3
At this point, you are now able to request an Access Token from the /oauth_token.do endpoint of the instance you created this in. You’ll note that this is a Bearer token, and will have no scopes.
Granting and creating scopes
The final piece of the puzzle is granting authorisation scopes to your OAuth Entity. As in the past, the default useraccount scope remains available, and this scope continues to permit the full scope of permissions afforded to a user profile.
As an alternative, ServiceNow has now implemented API Authentication Scopes. These are similar to the existing API Access Policies in format, but their intent is to form a relationship between an API, such as platform or bespoke scripted REST APIs, and a scope. This allows you to limit which APIs your OAuth Client has access to, and can be used elsewhere as well. This is a big step forward in API governance and control, and I’m eager to see how this feature gets adopted.
To set up a new authentication scope, you can take the following steps:
- Navigate to
sys_auth_scope.listusing the methods described above. Create a new record, specifying a name and description in line with the purpose of your scope. For example, this could be ‘interaction_closer`. Save this record. - Navigate to
System Web Services -> API Auth Scopes -> REST API Auth Scopeand create a new record, specifying a name, the Auth Scope you created in step 1, and a REST API. In my example, I’m implementing a scope to control access to only the Interaction Management API close resource, so I would set ‘Apply auth scope to all resources in this API’ to false, and select the ‘/now/interaction/{interaction_id}/close’ resource.
An example of an API Auth Scope after Step 2
This scope can now be applied to OAuth Clients, and its absence will block clients that do not have it from leveraging the resource in question. Ensure when implementing that you are aware of the breadth of use of your APIs, as this will be applied indescriminately as per your configuration. Disabling or deleting the REST API Auth Scope will allow you to restore the previous experience.
When to use Client Credentials?
The client credentials grant is designed for cases where the ‘client’ making the connection to ServiceNow is also the ‘resource owner’. This is most commonly the case for ServiceNow system-to-system integrations, where the authentication is not happening on behalf of an alternative ‘resource owner’, often a user. JWT bearer grants were supported and able to do this in the past, but client credentials now presents an alternative for situations wherein the JWT bearer grant may not be available, or is otherwise deemed unsuitable for your use case.
Closing notes
I hope this article gives you a bit of insight into the steps required to get a client credentials grant up and running in your ServiceNow instance. I think the real jewel in the crown here is the API Auth Scopes, which is an awesome maturity step.
Thank you for reading, and I hope you enjoyed/found value in this article. As always, I am open to feedback and can be reached here, as well as via Slack, LinkedIn, or email.
16 Comments
