Configuring Secure OAuth 2.0 and SAML Authentication Profiles in Pega Infinity

Authentication in Pega Infinity spans two directions that are easy to conflate but must be configured separately: outbound, where Pega calls a protected external API and must present credentials, and inbound, where an external client (or a human via SSO) authenticates to Pega. This article walks through configuring OAuth 2.0 for both directions and SAML 2.0 single sign-on, with concrete attribute mapping and the troubleshooting checklist that resolves the majority of real-world failures.

Outbound OAuth 2.0: authentication profiles

When a Connect-REST rule calls a protected endpoint, it references an authentication profile of type OAuth 2.0. The profile owns the token lifecycle so your connector never deals with raw tokens. The two grant types you will configure most often are:

• Client credentials — machine-to-machine. Pega authenticates as itself using a client ID and secret; no user is involved. This is the right choice for backend integrations.
• Authorization code — a user delegates access. The flow involves a browser redirect to the provider's authorization endpoint and a callback to Pega. Use this when calls must act on behalf of a specific user.

For client credentials you configure the token endpoint URL, the client ID and client secret, and the scopes you are requesting. Pega posts to the token endpoint and receives an access token plus an expiry. A typical client-credentials token request and response look like this:

POST /oauth2/token HTTP/1.1
Host: idp.partner.example
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)>

grant_type=client_credentials&scope=orders.read%20orders.write

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "orders.read orders.write"
}

Token caching and refresh

Pega caches the access token and reuses it across calls until it nears expiry, which avoids minting a token on every request and dramatically reduces load on the provider. For the authorization-code flow, the provider also issues a refresh token; Pega uses it to obtain a new access token silently when the old one expires, so the user is not redirected again. Two configuration habits keep this healthy:

1. Store the client secret in a secured location (a Keystore data instance or secret reference), never in plain rule text.
2. Verify the provider's expires_in matches reality — some gateways shorten token lifetime behind the scenes, and a stale cached token produces intermittent 401s.

You can validate the outbound profile end-to-end against a sandbox endpoint before wiring it into a real connector. If outbound calls start returning 401 after working, the first suspect is the cached token: invalidate it and confirm a fresh mint succeeds. Our companion piece on REST/SOAP connector exceptions covers how those 401s surface in pyStatusMessage and the retry rules around them.

Inbound OAuth 2.0: Client Registration and Provider

Securing your Pega-hosted services with OAuth 2.0 uses two cooperating rules:

• OAuth 2.0 Client Registration — defines a registered client (its client ID/secret, allowed grant types, redirect URIs, token lifetimes, and the operator/access-group context the token maps to). Each external consumer of your API gets its own registration.
• OAuth 2.0 Provider — defines how Pega issues and validates tokens: the supported grant types, the signing approach, introspection, and the identity mapping used to resolve the authenticated operator.

The flow: an external client calls your token endpoint with its registered credentials, Pega's provider issues a token, and subsequent calls to your Pega REST service present that token as a bearer credential. Pega validates it and resolves the operator context from the registration plus an identity mapping rule. The identity mapping is the bridge that turns claims in the token (or the registration default) into a Pega operator and access group, which in turn determines what the request is authorized to do.

A request to a protected Pega service then simply carries the bearer token:

GET /prweb/api/application/v2/cases/MYORG-WORK-O-1042 HTTP/1.1
Host: crm.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6...
Accept: application/json

Define least-privilege access groups for inbound clients. A service account that only needs to read cases should not resolve to an operator with developer access.

SAML 2.0 SSO: the authentication service

SAML handles human single sign-on. You configure an authentication service rule of type SAML 2.0, in which Pega acts as the Service Provider (SP) and your corporate identity system (Azure AD/Entra, Okta, PingFederate, ADFS, etc.) is the Identity Provider (IdP).

The trust between them is established by exchanging metadata:

• Import the IdP metadata into the authentication service. This gives Pega the IdP's SSO URL, its entity ID, and its signing certificate so Pega can validate the signature on incoming assertions.
• Generate and hand the IdP your SP metadata. This advertises Pega's entity ID (the SP entityID), its Assertion Consumer Service (ACS) URL (the redirect URI the IdP posts the assertion back to), and the SP's signing/encryption certificates.

Key concepts to get right:

• SP vs IdP — the SP (Pega) never sees the user's password; it trusts a signed assertion from the IdP that the user authenticated successfully.
• Signing and encryption certificates — the IdP signs assertions with its private key; Pega validates with the IdP's public cert. If you require encrypted assertions, the IdP encrypts to Pega's public cert and Pega decrypts with its private key. Keep both sides' certificates current — expiry is the single most common SSO outage.
• NameID — the primary subject identifier in the assertion (often the user's email or UPN). This is typically what you map to the Pega operator ID.

Mapping SAML assertion attributes to Pega operator fields

After the signature validates, Pega must turn the assertion into a usable session: it provisions or looks up an operator and assigns an access group. This is driven by attribute mapping in the authentication service. The IdP releases attributes (claims) in the assertion; you map each to an operator property.

SAML assertion attribute	Pega operator field	Notes
NameID (Subject)	Operator ID (pyUserIdentifier)	Primary key; must be unique and stable
email / emailAddress	.pyUserEmailAddress	Often equals NameID; used for notifications
givenName + surname	.pyUserName (full name)	Concatenate first + last for display
displayName	.pyUserName	Use directly if the IdP sends a full name
groups / memberOf	Access group selection	Drives authorization; map IdP groups to Pega access groups
department / orgUnit	Custom operator property / org unit	Optional, for routing and reporting

The groups/memberOf mapping is the most security-sensitive: it decides what the user can do. Define an explicit mapping from IdP group names to Pega access groups, with a safe default (or a hard deny) for unmapped users so a misconfigured group claim cannot silently grant broad access.

You can let Pega auto-provision operators on first login from the mapped attributes, which removes manual operator creation but means your attribute mapping must be complete and correct — a missing access-group mapping will provision a user who cannot do anything useful.

Identity mapping rules

Both inbound OAuth 2.0 and SAML rely on identity mapping rules to translate external identity into a Pega context. For OAuth 2.0 this maps token claims to the operator/access group; for SAML it maps assertion attributes. Keep identity mapping logic in these dedicated rules rather than scattering it through activities, so the mapping is auditable and reusable across authentication services. When you change which claim represents the user, change it in one place.

For a concrete example, a mapping might read the groups claim, look up a corresponding access group via a decision table, and fall back to a restricted read-only group if no match is found:

Identity mapping (conceptual):
  operatorId   <- assertion.NameID
  fullName     <- assertion.displayName | (givenName + " " + surname)
  email        <- assertion.email
  accessGroup  <- DecisionTable( assertion.groups )
                  default -> "MyOrg:RestrictedReadOnly"
  if operator not found and autoProvision = true:
      create operator from above, assign accessGroup

Troubleshooting OAuth 2.0 and SAML

Most authentication failures fall into a short list of root causes. Work them in order:

1. Clock skew — SAML assertions and OAuth tokens carry NotBefore/NotOnOrAfter (or exp/iat) timestamps. If the Pega host clock drifts from the IdP, valid assertions are rejected as expired or not-yet-valid. Ensure NTP is synced on all nodes; allow only a small skew tolerance.
2. Audience / entityID mismatch — the assertion's Audience (or the token's aud) must match the SP entityID Pega advertises. A trailing slash, http-vs-https, or a copy-paste typo between the SP metadata and the IdP's app config breaks trust. Compare them character for character.
3. Certificate expiry or wrong cert — if the IdP rotated its signing certificate and you did not re-import the metadata, signature validation fails. Likewise an expired SP cert breaks encrypted-assertion or signed-request flows. Track expiry dates and re-import metadata after any rotation.
4. Signature validation failures — caused by the wrong public cert, a changed canonicalization, or the IdP signing the response vs the assertion (or both) differently than Pega expects. Confirm whether your IdP signs the assertion, the response, or both, and align the SP config.
5. Redirect URI / ACS mismatch (OAuth authorization-code & SAML) — the IdP will refuse to post back to a URL not on its allow-list. The ACS URL in your SP metadata and the redirect URI registered with the provider must match Pega's actual callback exactly, including host, port, and path.
6. Scope or grant-type errors (OAuth) — requesting a scope the client is not entitled to, or a grant type the provider has not enabled for that client, yields invalid_scope or unauthorized_client. Reconcile the requested scopes with the registration.

A failed SAML validation in the logs typically looks like this, and the message usually points straight at one of the causes above:

2026-05-23 09:14:52,003 [ https-jsse-nio-8443-exec-7 ] [ STANDARD ]
  (security.saml.SAMLAuthenticator) ERROR - SAML assertion validation failed:
  Conditions NotOnOrAfter 2026-05-23T09:14:20Z is before current time
  2026-05-23T09:14:52Z (clock skew); IssuerEntityID=https://idp.example/saml
  AudienceRestriction=https://crm.example.com/prweb/PRSAML did not match SP entityID

When you read an entry like that, two distinct problems are visible — a clock-skew rejection and an audience mismatch — and each maps to a fix above. Reading these messages precisely, rather than guessing, is the fastest path to resolution. For structured practice on the security model end to end, see our Pega certification help.

Putting it together: a configuration checklist

Before you call any authentication setup "done," verify:

• Outbound OAuth profile mints and caches a token; a forced refresh succeeds.
• Inbound clients have least-privilege access groups via Client Registration.
• SAML SP and IdP metadata are exchanged, and both certificates are current with monitored expiry.
• Attribute mapping resolves operator, email, full name, and access group, with a safe default for unmapped users.
• NTP is synced (clock skew), entityID/audience match exactly, and redirect/ACS URLs are on the IdP allow-list.

Key takeaways

• Outbound vs inbound are separate concerns: outbound uses an OAuth 2.0 authentication profile; inbound uses Client Registration + Provider rules.
• Choose client credentials for machine-to-machine and authorization code when acting on behalf of a user; rely on Pega's token caching and refresh.
• SAML SSO makes Pega the SP trusting your IdP; trust is established by exchanging metadata and validated via the IdP's signing certificate.
• Drive authorization through attribute mapping — especially the groups/memberOf claim — and centralize translation in identity mapping rules.
• The top failure causes are clock skew, audience/entityID mismatch, certificate expiry, signature validation, and redirect/ACS mismatch — work them in that order.
• Always enforce least privilege and a safe default access group so a misconfigured claim never silently over-grants.

Authentication is one of the highest-stakes areas to get right and one of the easiest to misconfigure subtly. If you would like a senior practitioner to review your OAuth profiles and SAML service against a real IdP, our Pega mentorship program offers focused, hands-on sessions. Contact us with your identity provider and integration goals, and we will build a tailored walkthrough.