When your application needs to enforce step-up authentication for wire transfers, account changes, or other high-risk operations, you're implementing Transactional Authorization (TAuthZ). This guide covers the REST API approach for teams building custom enforcement into applications or proprietary gateways.
Scope
This reference covers REST-based TAuthZ integration with PingOne Advanced Identity Cloud and PingAM. You'll find sequence details, policy configuration requirements, and implementation patterns for enforcing single-use authorization decisions on sensitive operations.
What's included:
- Direct PDP REST API integration patterns
- Policy evaluation and advice handling
- Transaction ID lifecycle management
- Session token strategies for performance
What's excluded:
- PingGateway or PingAgent configurations (those use different integration patterns)
- SDK-based implementations for mobile/web apps
- Policy design principles (this assumes you've defined your risk thresholds)
Key Concepts
Policy Decision Point (PDP): The authorization engine that evaluates access requests against configured policies. In this architecture, PingAM or PingOne Advanced Identity Cloud serves as your PDP.
Policy Enforcement Point (PEP): The component that intercepts requests and enforces PDP decisions. In REST integration, your application or custom gateway acts as the PEP.
Transaction ID (TxId): A single-use identifier binding a specific step-up authentication attempt to a policy evaluation. The PDP issues this in the initial advice; you return it after completing the step-up journey.
TransactionConditionAdvice: The policy response instructing your PEP to execute a specific authentication journey before re-evaluating the request. This contains the TxId and journey reference.
Admin SSO Token: A session token with extended idle and maximum timeouts (e.g., 60 minutes) used for policy endpoint access. Cache this to avoid repeated admin authentication overhead.
REST Flow Sequence
The complete authorization cycle involves seven distinct API interactions:
- User authentication, Obtain standard SSO token via login journey.
- Admin authentication, Obtain extended-session SSO token for policy API access.
- Initial policy evaluation, Request authorization for target resource/action.
- Receive TransactionConditionAdvice, PDP returns TxId and required journey.
- Execute step-up journey, Complete authentication callbacks with TxId context.
- Obtain step-up token, Journey completion returns new session token.
- Final policy evaluation, Re-submit request with TxId, receive authorization decision.
The authorization decision in step 7 is single-use. If the user attempts the same operation again, the flow restarts from step 3.
Policy Configuration Requirements
Your TAuthZ policy must specify three elements precisely:
Resource pattern: Define the protected endpoint as a complete URL including protocol, domain, port, and path. Example: https://api.bankingexample.com:443/makepayment.
Allowed actions: Specify HTTP methods explicitly (POST, PUT, DELETE). Don't use wildcards for high-risk operations.
Transaction condition: Reference your step-up journey by name. The journey should implement strong authentication (push notification, TOTP, FIDO2 ceremony). The source example uses a simplified journey for demonstration, but production implementations require phishing-resistant or multi-factor methods.
Subject condition: Typically set to AuthenticatedUsers, but you can narrow to specific groups or attributes if needed.
Implementation Guidance
Session Token Strategy
Don't authenticate an admin user for every policy evaluation. The admin token provides access to the policy endpoint, not the protected resource itself. Request an admin session with extended timeouts during initialization, cache it, and reuse it until expiration. This reduces latency and authentication overhead.
The user SSO token authenticates the actual subject. You'll need both tokens for the initial policy evaluation call.
Transaction ID Handling
When the PDP returns TransactionConditionAdvice, extract the TxId immediately. You'll pass this to the authentication endpoint when initiating the step-up journey, then include it again in the final policy evaluation.
The TxId binds the step-up authentication to the specific authorization request. Don't reuse TxIds across operations or users. Each high-risk action gets a fresh TxId.
Callback Completion
The step-up journey returns authentication callbacks (OTP input, push approval status, biometric prompts). Your application must:
- Parse the callback structure from the initial journey response.
- Collect required inputs from the user.
- Submit completed callbacks back to the authentication endpoint.
- Handle callback failures (wrong OTP, timeout, user cancellation).
If callback submission fails, the flow terminates. The user must restart from the initial policy evaluation.
Policy Re-Evaluation
After completing the step-up journey, you'll have a new session token and the original TxId. Submit both to the policy endpoint in the final evaluation request. The PDP verifies the TxId matches a completed transaction context, then issues the authorization decision.
This decision grants access to the specific resource and action defined in the policy. It doesn't extend to other operations or resources.
Common Pitfalls
Skipping admin token caching: Authenticating an admin user for every policy call adds 200-500ms latency and unnecessary load. Cache the admin token and refresh only on expiration.
Reusing Transaction IDs: Each TxId is single-use. Attempting to reuse a TxId from a previous transaction will fail policy evaluation. Don't build TxId pools or caching mechanisms.
Incomplete callback submission: If your step-up journey requires three callbacks (username, OTP, consent), you must complete all three before resubmitting to the policy endpoint. Partial callback submission fails silently in some configurations.
Missing error handling for journey timeouts: Step-up journeys typically expire after 2-5 minutes. If the user delays OTP entry or doesn't approve a push notification, the TxId becomes invalid. Your application must detect this and restart the flow.
Hardcoding journey names in policy evaluation requests: The journey name comes from the TransactionConditionAdvice response. Don't assume the journey name remains constant across environments or policy updates.
Ignoring TTL in policy decisions: The authorization decision includes a TTL field (time-to-live). For TAuthZ, this is typically 0, meaning immediate expiration. Don't cache or reuse authorization decisions beyond their TTL.
Quick Reference
| Endpoint | Purpose | Required Tokens | Returns |
|---|---|---|---|
/authenticate (user journey) |
Obtain user SSO token | None | User session token |
/authenticate (admin journey) |
Obtain policy API access | None | Admin session token (extended) |
/policies (initial) |
Request authorization | User + Admin tokens | TransactionConditionAdvice + TxId |
/authenticate (TAuthZ journey) |
Get step-up callbacks | TxId | Callback structure |
/authenticate (callback submit) |
Complete step-up | TxId + completed callbacks | New session token |
/policies (final) |
Obtain authorization decision | User token + TxId | Authorization decision (single-use) |
Session timeout recommendations:
- User SSO: 15-30 minute idle, 8-hour maximum
- Admin SSO: 60 minute idle, 8-hour maximum
- TxId validity: 2-5 minutes from issuance
Policy evaluation response codes:
200with"POST": true, Authorized200withTransactionConditionAdvice, Step-up required401, Invalid or expired session token403, Policy denies access (no step-up available)
To integrate Transactional Authorization effectively, ensure your team understands these components and processes. This will enhance security for high-risk operations in your financial services applications.
