OAuth parameters

Set parameters to control OAuth passwords, default profile support, API requests, and API responses.

Change OAuth password parameter

Use this property to insure only POST body parameters are accepted as input for all supported grant types.

Sending sensitive information over URI query parameters might lead to sensitive information disclosure by clients, the server, or any host between the requests. Starting with the Kingston release, this new property insures only the POST body parameters are accepted as input for all supported grant types. Supported grant types include:
  • authorization code
  • password
  • client credential
  • refresh token
Table 1. OAuth password parameter property
Property Description
glide.oauth.allow.parameters.in.post.body.only This property is set to true for zBoots only, as part of the OAuth 2.0 plugin. If you need this setting for your instance, create and set the property to true.

OAuth parameters for default profile support

The default profile feature requires a set of parameters that you can use with the setParameter() API to specify the OAuth requestor, a context for the request, and the provider profile.

In the OAuth provider scenario, you must set three parameters that tell the OAuth provider which OAuth profile to use by default. When these three parameters are set, the access token is saved in the instance database. Use the parameters with GlideOAuthClientRequest.

Table 2. OAuth parameters for default profile support
Parameter Description
oauth_requestor The Sys ID of the object, which can be a user record or an email account.
oauth_requestor_context Descriptor that provides context for the OAuth requestor. As a good practice, use the name of the table where the oauth_requestor object is saved.
oauth_provider_profile The Sys ID of the OAuth profile record that is the default.

You do not need to use parameters to set the grant type and scope because the values are configured in the OAuth profile record. If you do not use the parameters, you can use the GlideOAuthClientRequest API methods setScope and setGrantType. For additional information, refer to setScope and setGrantType.

OAuth API request parameters

Access token requests use the following request parameters.

Table 3. Access token request parameters
Request parameter Description
grant_type [Required] The type of credentials authorizing the request for an access token. This parameter must have one of the following values:
  • password: A set of user credentials authorize the access token request. Specify the user credentials in the username and password parameters.
  • refresh_token: An existing refresh token authorizes the access token request. Specify the refresh token in the refresh_token parameter.
client_id [Required] Auto-generated unique ID of the client application requesting the access token.
client_secret [Required] Shared secret string that the instance and the OAuth application use to authorize communications with one another.
username User account name that authorizes the access token request. This parameter is required for access token requests with a grant_type of password.
password Password for the user account that authorizes the access token request. This parameter is required for access token requests with a grant_type of password.
refresh_token Existing refresh token that authorizes the access token request. This parameter is required for access token requests with a grant_type of refresh_token.

Requests Using User Credentials

The instance requires clients to provide user login credentials when first authorizing the client or when authorizing the creation of a new refresh token. This type of request always returns two tokens:

  • An access token
  • A refresh token

The instance verifies that the user is active, not currently locked out, and has an interactive session. If any of these conditions are false, the instance does not produce an access token. Access requests made within the expiration time of the access token always return the current access token.

Note: This type of authorization grant relies on TLS encryption to protect the user credentials during transmission.

The following example illustrates requesting an access token with a set of user credentials. (Spaces have been added to improve readability.)

$ curl -d"grant_type=password&client_id=be3aeb583ace210011c15b24a43e25d8
&client_secret=client_password
&username=admin&password=admin" 
https://instancename.service-now.com/oauth_token.do

Requests Using a Refresh Token

The instance can use an existing refresh token to create a new access token. This type of request returns only an access token. The instance confirms that the refresh token has not expired before generating a new access token. Access requests made within the refresh token expiration time always return the current refresh token. Transmitting refresh tokens is generally more secure than transmitting user credentials. The following example illustrates requesting an access token with an existing refresh token. (Spaces have been added to improve readability.)

$ curl -d"grant_type=refresh_token&client_id=be3aeb583ace210011c15b24a43e25d8
&client_secret=client_password
&refresh_token=w599voG89897rGVDmdp12WA681r9E5948c1CJTPi8g4HGc4NWaz62k6k1K0FMxHW40H8yOO3Hoe" 
https://instancename.service-now.com/oauth_token.do

OAuth API response parameters

The OAuth 2.0 API produces a JSON response containing the following parameters as name:value pairs.

Table 4. Access token response parameters
Response parameter Description
scope Amount of access granted by the access token. The scope is always useraccount, meaning that the access token has the same rights as the user account that authorized the token. For example, if Abel Tuter authorizes an application by providing his login credentials, then the resulting access token grants the token bearer the same access privileges as Abel Tuter.
token_type Type of token issued by the request as defined in the OAuth RFC. The token type is always Bearer, meaning that anyone in possession of the access token can access a protected resource without providing a cryptographic key. See RFC6750 for more information about how OAuth 2.0 uses bearer tokens.
expires_in Lifespan of the access token in seconds.
refresh_token String value of the refresh token.
access_token String value of the access token. Access requests made within the access token expiration time always return the current access token.
format [Optional] Output format of the response. This value is always JSON.

The following example illustrates the JSON string returned by an access token request. (Spaces have been added to improve readability.)

{"scope":"useraccount","token_type":"Bearer","expires_in":1800,
"refresh_token":"w599voG89897rGVDmdp12WA681r9E5948c1CJTPi8g4HGc4NWaz62k6k1K0FMxHW40H8yOO3Hoe",
"access_token":"F0jh9korTyzd9kaZqZ0SzjKZuS3ut0i4P46Lc52m2JYHiLIcqzFAumpyxshU9mMQ13gJHtxD2fy"}