Skip to content
KiweelyKiweelyKiweely

Restricting Workday OAuth Token Use by IP with Maintain IP Ranges

Lock down external Workday OAuth 2.0 API traffic by defining CIDR allowlists in Maintain IP Ranges, binding authentication rules in Manage Authentication Policies, and running Activate All Pending Authentication Policy Changes without locking out administrators.

  • Checked against Workday on
  • Applies to Workday Authentication Policies
  • 6 min read
  • Published
  • By Kiweely
On this page

Restrict where external OAuth 2.0 credentials can be redeemed or presented in Workday by registering static egress addresses in Maintain IP Ranges, referencing those ranges inside Manage Authentication Policies, and committing the policy via Activate All Pending Authentication Policy Changes. Without explicit policy activation—or when browser sign-in IPs are confused with backend server egress IPs—IP rules either silently fail to enforce or block remote employees from signing in.

Browser Sign-In IP vs. API Caller Egress IP

Before editing authentication rules for a user-delegated OAuth 2.0 application (configured via Register API Client), distinguish the two network hops involved in an Authorization Code Grant flow:

OAuth / API Phase Target Workday Endpoint Source IP Seen by Workday Policy Requirement
OAuth / API Phase1. Interactive Sign-In Target Workday EndpointGET /<tenant>/authorize + SAML SSO / MFA Source IP Seen by WorkdayEmployee’s laptop or phone IP (corporate VPN, office Wi-Fi, or home ISP) Policy RequirementMust match the employee’s normal desktop/mobile SSO authentication rule
OAuth / API Phase2. Code Exchange & Refresh Target Workday EndpointPOST /ccx/oauth2/<tenant>/token Source IP Seen by WorkdayExternal gateway or cloud container’s outbound NAT IP Policy RequirementCan be locked to a static IP range if your gateway uses dedicated egress
OAuth / API Phase3. Resource API Execution Target Workday Endpoint/ccx/api/v1/..., /ccx/api/wql/v1/..., RaaS, SOAP Source IP Seen by WorkdayExternal gateway or cloud container’s outbound NAT IP (or user’s device if calling directly from a native mobile/desktop app) Policy RequirementEvaluated against authentication policy rules and access restrictions
OAuth / API Phase4. Headless ISU Integration Target Workday Endpoint/ccx/oauth2/<tenant>/token + SOAP/REST/RaaS Source IP Seen by WorkdayMiddleware / ETL static outbound NAT IP Policy RequirementLock strictly to the middleware CIDR via an ISU-specific security group rule

Dynamic Cloud Egress Trap

Never bind an IP range rule to shared serverless infrastructure whose outbound IPs rotate across broad cloud provider ASN blocks. Use either a VPC NAT gateway with a reserved static IP or a dedicated single-tenant connector with a pinned outbound IP.

Step 1: Register CIDR Blocks in Maintain IP Ranges

You need Modify permission on the Security Administration or Set Up: Tenant Setup - Security domain in the System functional area.

  1. Search for and open the Maintain IP Ranges task in Sandbox.
  2. Add a new row for each trusted network perimeter or gateway static IP:
    • Range Name: Use an explicit operational name including owner and environment, such as Gateway Dedicated Egress - US Central or Corporate VPN Egress Pool.
    • From IP Address / To IP Address (or CIDR): Enter exact /32 single-host addresses (for example, 198.51.100.42 to 198.51.100.42) or narrow CIDR subnets (198.51.100.0/28).
    • Description: Document the external service, ticket reference, and rotation contact.
  3. Click OK to save the named IP ranges. Saving an IP range alone enforces nothing until an active authentication policy references it.

Step 2: Order Rules in Manage Authentication Policies

Workday evaluates authentication rules top to bottom within an authentication policy and stops at the first rule whose Security Group and Authentication Condition (including IP Range) match the caller. Rule ordering mistakes are the number-one cause of accidental lockouts and bypassed IP checks.

  1. Open the Manage Authentication Policies report and click Edit on your tenant’s active policy (always test in Sandbox first).
  2. Keep a Security Administrator Break-Glass Rule at Order 1 scoped to your Security Administrator group using strong MFA/SSO so an IP misconfiguration below never locks admins out of fixing the policy.
  3. Configure targeted rules for headless integrations or restricted API callers above general workforce rules:
Evaluation Order Rule Name Security Groups IP Range Condition Allowed Authentication Types Purpose
Evaluation Order1 Rule NameAdmin Emergency & SSO+MFA Security GroupsSecurity Administrator IP Range ConditionAny (or Admin Bastion VPN) Allowed Authentication TypesSAML / User Name Password + MFA PurposePrevents tenant lockout during IP changes
Evaluation Order2 Rule NamePayroll & Data Lake ISUs - Trusted IP Security GroupsISSG - Payroll & Warehouse IP Range ConditionMiddleware Static NAT (/32) Allowed Authentication TypesOAuth 2.0, WS-Security / Basic PurposePermits ISU calls from approved egress IP
Evaluation Order3 Rule NamePayroll & Data Lake ISUs - Deny Elsewhere Security GroupsISSG - Payroll & Warehouse IP Range ConditionAny Allowed Authentication TypesDeny / Restricted (No allowed types) PurposeBlocks stolen ISU refresh credentials from any other IP
Evaluation Order4 Rule NameWorkforce Corporate Network Security GroupsAll Employees IP Range ConditionCorporate VPN & Office CIDRs Allowed Authentication TypesSAML (SSO), OAuth 2.0 PurposeDirect SSO and user-delegated OAuth on network
Evaluation Order5 Rule NameWorkforce Off-Network Security GroupsAll Employees IP Range ConditionAny Allowed Authentication TypesSAML (with IdP MFA) PurposeAllows remote workers to complete SSO + MFA unless Access Restrictions apply
Evaluation OrderDefault Rule NameDefault Catch-All Security Groups(All other accounts) IP Range ConditionAny Allowed Authentication TypesRestricted per company baseline PurposeFallback rule required at bottom of policy

Pairing IP Ranges with Create Access Restrictions

If remote employees sign in from home (Any IP) via SAML SSO + MFA, but you want to block specific high-risk capabilities (such as bulk report downloads or specific tasks) when off-network, run Create Access Restrictions and attach the restriction to the off-network authentication condition on Manage Authentication Policies.

Step 3: Run Activate All Pending Authentication Policy Changes

Edits in Manage Authentication Policies sit in a pending state and have zero effect on live OAuth or UI traffic until activated:

  1. Run the Activate All Pending Authentication Policy Changes task.
  2. Review the diff of modified authentication rules, security groups, IP ranges, and allowed authentication types.
  3. Enter a change-control comment, select the Confirm check box, and click OK.

Step 4: Verify Enforcement and Audit Rejected Attempts

Keep your original admin browser window open while testing from two separate network origins:

  1. Positive test (allowed IP): Trigger an OAuth /token exchange and a GET /workers/me REST call from your allowlisted server IP. Confirm HTTP 200 OK.
  2. Negative test (non-allowlisted IP): Run the exact same /token or API call from a developer laptop outside the CIDR range. Confirm Workday rejects the request (401 Unauthorized or 403 Forbidden).
  3. Confirm in Workday logs: Run the Signons and Attempted Signons report for the test window (see Auditing External API Calls in Workday Sign-On History and Activity Logs). Verify that the off-network attempt appears as a failed authentication citing the authentication policy condition, while the allowlisted request records the exact egress IP.

Common Lockout and Cutover Traps

  • Forgetting Sandbox refresh drift: When Production refreshes Sandbox, Production IP ranges copy over to Sandbox. If your Sandbox integration middleware uses a different NAT IP than Production, add both or update Maintain IP Ranges immediately post-refresh.
  • Blocking SAML ACS callbacks or mobile browser SSO: Ensure off-network employees who need mobile or external OAuth access aren’t caught by a blanket IP deny rule before SAML SSO completes (see Resolving SSO Redirect Loops on the Workday OAuth Authorize Endpoint).
  • Rotating cloud egress without dual-homing: Always add the new static IP to Maintain IP Ranges and activate pending policy changes before cutting DNS or NAT traffic over from the old IP.

For organizations enforcing strict network perimeters on workforce AI, Kiweely Bridge (coming next) supports both Dedicated single-tenant hosting—providing a dedicated static outbound IP built specifically for Workday Maintain IP Ranges and Manage Authentication Policies—and a Self-hosted stateless container you can deploy directly inside your own AWS, GCP, Azure, or Kubernetes VPC.

Frequently asked questions

Why didn't my IP restriction take effect after saving Manage Authentication Policies?

Changes made in Manage Authentication Policies remain staged until you run the Activate All Pending Authentication Policy Changes task and confirm activation.

If an employee signs in from home, whose IP does Workday check during API calls?

Workday evaluates the employee's browser IP during interactive sign-in at the Authorize Endpoint, and evaluates the external server's outbound NAT IP when that server calls the Token Endpoint and Workday REST, WQL, SOAP, or RaaS APIs.

Can I restrict an Integration System User to a single static IP without affecting employees?

Yes. Create an Integration System Security Group containing only that ISU, add a rule above your default catch-all rule in Manage Authentication Policies scoped to that security group and your CIDR range, and block or restrict unauthenticated origins.

How do I prevent locking out Security Administrators when testing IP rules?

Always place a high-priority administrator recovery rule at the top of your authentication policy (requiring SAML SSO + MFA or native MFA for the Security Administrator security group) and test every rule change in Sandbox with a second active admin session open.

Sources checked

Related guides

All guides

Let Workday check the work.

Kiweely writes WQL and builds orchestrations in your own tenant, and Workday, not Kiweely, says whether they passed.

Get the next guide in your inbox.

One email a month with new guides and one Extend tip. Nothing else.

We’ll email you once to confirm. Unsubscribe in one click from any issue.