OAuth setup

Set up and configure OAuth to use token-based authentication.

Set up OAuth

To set up OAuth, register applications to OAuth, enable the OAuth system property, and generate token requests.

Before you begin

Role required: admin

Procedure

  1. Make sure the OAuth plugin is active and the OAuth activation property is set to true.
  2. Create an OAuth application registry using one of the following methods:
  3. Configure your client applications to create an HTTP POST that requests an OAuth token. The application must also be able to parse the JSON response to use the returned access token and refresh token.

Activate OAuth

By default, the OAuth plugin is active on new and upgraded instances. If the plugin is not active on your instance, you can activate the plugin.

Before you begin

Role required: admin

Procedure

  1. Navigate to System Definition > Plugins.
  2. Find and click the plugin name.
  3. On the System Plugin form, review the plugin details and then click the Activate/Upgrade related link.

    If the plugin depends on other plugins, these plugins are listed along with their activation status.

    If the plugin has optional features that depend on other plugins, those plugins are listed under Some files will not be loaded because these plugins are inactive. The optional features are not installed until the listed plugins are installed (before or after the installation of the current plugin).

  4. (Optional) If available, select the Load demo data check box.

    Some plugins include demo data—Sample records that are designed to illustrate plugin features for common use cases. Loading demo data is a good practice when you first activate the plugin on a development or test instance.

    You can also load demo data after the plugin is activated by clicking the Load Demo Data Only related link on the System Plugin form.

  5. Click Activate.

Set the OAuth property

To generate OAuth 2.0 tokens to registered applications, the com.snc.platform.security.oauth.is.active property must be active for the instance.

Before you begin

Role required: admin

Procedure

  1. Type sys_properties.list in the application navigator filter and then click New.
  2. Fill out the form with the following settings:
    • Name: com.snc.platform.security.oauth.is.active
    • Type: true | false
    • Default value: true
  3. Set the property to true to use OAuth 2.0.

Create an endpoint for clients to access the instance

Create an OAuth application endpoint for external client applications to access the ServiceNow instance.

Before you begin

Role required: admin

Procedure

  1. Navigate to System OAuth > Application Registry and then click New.
  2. On the interceptor page, click Create an OAuth API endpoint for external clients and then fill in the form.
    Field Description
    Name A unique name that identifies the application that you require OAuth access for.
    Client ID [Read-Only] The auto-generated unique ID of the application. The instance uses the client ID when requesting an access token.
    Client Secret [Required] The shared secret string that both the instance and the client application or website use to authorize communications with one another. The instance uses the client secret when requesting an access token. Leave this field blank to have the instance auto-generate a client secret. To display existing client secrets, click the lock icon.
    Redirect URL The callback URL that the authorization server redirects to. Enter the full URLs of the clients requesting access to the resource, appended by /oauth_redirect.do. For example, http://token_consumer:port/oauth_redirect.do. Enter as many URLs as needed for all possible token consumers. The instance matches the URL of the incoming request to one of the redirect URLs. If no match is made, the instance uses the first redirect URL.
    Logo URL The URL that contains an image to use as the application logo. The logo appears on the approval page when the user receives a request to grant a client application access to a restricted resource on the instance.
    Active Select the check box to make the application registry active.
    Refresh Token Lifespan The number of seconds that a refresh token is valid. The instance uses the lifespan value when requesting a refresh token. By default, refresh tokens expire in 100 days (8640000 seconds).
    Access Token Lifespan The number of seconds that an access token is valid. The instance uses the lifespan value when requesting an access token. By default, access tokens expire in 30 minutes (1800 seconds).
    Comments Additional information to associate with the application.
  3. Click Submit. The record is saved in the Application Registries [oauth_entity] table.

Result

The system creates a record in the Application Registries [oauth_entity] table with of type OAuth Client. When the instance actually issues tokens and authorization codes, they are stored in the table. See Manage OAuth tokens for more information.