As organizations increasingly adopt external Identity Providers (IDPs) to centralize identity and access management, establishing federated trust between systems becomes essential for secure API integrations. ServiceNow supports Third-Party ID Token Flow, which enables the platform to trust JWT tokens issued by third-party IDPs—allowing both human users and service accounts to access APIs without managing credentials directly within ServiceNow.
This flow allows ServiceNow to accept and validate JWT tokens—either ID tokens or access tokens—issued by trusted third-party IDPs. Once validated, ServiceNow maps the token claims to internal user records and authorizes access to APIs based on the user’s roles and permissions.
In this blog, we’ll walk through how to configure ServiceNow to accept federated JWT tokens for inbound API authentication, covering both user and service account scenarios.
What is Federated Token Authentication?
Federated token authentication allows ServiceNow to trust and validate JWT tokens issued by external Identity Providers. These tokens carry identity claims that ServiceNow maps to internal user records, enabling secure and seamless API access.
Authentication: Handled by your IDP.
Token Issuance: IDP generates a JWT token (ID token or access token).
Validation: ServiceNow validates the token using a public key.
Access: ServiceNow grants access based on mapped user permissions.
This process is implemented in ServiceNow as the Third-Party ID Token Flow.
Accessing ServiceNow APIs with Federated User Accounts
Flow Overview
The diagram below shows the Authorization Code flow between your client application and the IDP to obtain a token. However, you may use any other flow suitable for your requirements to get a JWT token from the IDP.
Steps to Configure
1. Configure Your Client Application to get JWT token
Set up your client to authenticate with your IDP and obtain tokens. The authentication method between your client and IDP—such as Authorization Code Flow, JWT Bearer Flow, or any other flow—is entirely up to you and depends on your application's requirements and your IDP's capabilities.
Note: ServiceNow does not participate in or influence how your client obtains the token. This process is managed entirely between your client and your IDP.
2. Configure ServiceNow to validate and accept the federated JWT token
To allow ServiceNow to validate JWT tokens issued by your Identity Provider, you need to register an external OIDC provider:
- Navigate to: All → System OAuth → Application Registry → New
- Select "Configure an OIDC provider to verify ID tokens".
- Enter a unique Name to identify the OAuth OIDC entity.
- Enter the Client ID that matches the aud (audience) claim in the JWT token. This ensures the token is intended for ServiceNow or the specific client application, allowing proper validation. ServiceNow uses this Client ID to identify the corresponding OIDC Provider record and validate the token. To avoid conflicts, ensure each OIDC Provider record has a unique value of Client ID.
- Select a template for your IDP in ‘OAuth OIDC Provider Configuration’ (such as Azure AD, Okta, Google, Auth0, or ADFS). To review template details like User Claim name and User field, click the ‘Preview this record’ icon. You can also change the values by opening the record.
- If your IDP isn’t available in the template, create a new template:
- Click the search icon in ‘OAuth OIDC Provider Configuration’ and select New.
- Enter the OIDC Provider name and OIDC Metadata URL.
- Specify the claim name in the User Claim field that contains the user identifier from the JWT token.
- Select the User Field to map this identifier to a ServiceNow user record.
- Enable JTI claim verification if necessary to prevent replay attacks.
- Click Submit.
- Clock Skew: Time buffer (in seconds) to account for clock differences; default is 300 seconds.
- Enforce Token Restrictions: (Optional) Restrict access to only the APIs configured in REST API Access Policy for the OAuth authentication profile.
- Client Type: Choose based on your integration model (e.g., Integration as a User or Service).
- Right click the header and Save. The configuration will be saved in the Application Registries.
- Go to the related list on the record --> Auth Scopes to associate the scope for this OAuth entity. Assigning the Useraccount scope grants the client application all permissions of the logged-in user. For better security, assign more specific scopes based on the application's needs to maintain least privilege access.
- Click Submit.
Accessing ServiceNow APIs with Federated Service Accounts
Service accounts follow the same Third-Party ID Token Flow as user accounts, with a few additional steps to ensure proper mapping and access control.
Flow Overview
Steps to Configure
1. Reuse Configuration Steps from User Account Setup
To begin, follow the same initial setup as for user accounts. This includes configuring your third-party client application to get tokens using a service account and configuring ServiceNow to validate and accept the federated JWT token.
2. Set up a User account in ServiceNow for mapping your service account identity.
Unlike human users who typically have existing records in ServiceNow, service accounts are application-specific and require manual creation to establish a valid identity in the platform. Ensure the value of the configured claim in the token matches the value in the user field (e.g., user_name, email, etc.) of this account, as defined during the initial setup.
When creating the Sys User account in ServiceNow, enable the Web Service Access Only flag to restrict this account to only API access. Assign the necessary permissions by adding the appropriate roles and groups to the account.
Token Mapping and Authorization
When the client sends a token to ServiceNow while calling API
Example
GET https://<servicenow_base_url/api/now/incident
Authorization: Bearer YOUR_JWT_TOKEN
The platform associates the configured claim in the token with a corresponding sys_user record. User access is then determined by the roles and groups assigned to that user record, along with the scope defined for the client application.
