--- title: Authorize one-time access with transactional authz description: Transactional authorization requires a user to authorize every access to a resource. It's part of an Advanced Identity Cloud policy that grants single-use or one-shot access. component: pingoneaic page_id: pingoneaic:am-authorization:transactional-authorization canonical_url: https://docs.pingidentity.com/pingoneaic/am-authorization/transactional-authorization.html keywords: ["Transactional Authorization", "Policy", "Administration", "Configuration"] page_aliases: ["authorization-guide:transactional-authorization.adoc"] section_ids: understand_transactional_authorization: Understand transactional authorization configure_transactional_authorization: Configure transactional authorization the_user_journey: The user journey the_policy: The policy your_application: Your application demonstrate_transactional_authorization: Demonstrate transactional authorization --- # Authorize one-time access with transactional authz Transactional authorization requires a user to authorize *every* access to a resource. It's part of an Advanced Identity Cloud policy that grants single-use or one-shot access. For example, a user might approve a financial transaction with a one-time password (OTP) sent to their device, or respond to a push notification to confirm that they have indeed signed on from an unexpected location. Performing the extra action successfully grants access to the protected resource but only once. Later attempts to access the resource require the user to perform the configured actions again. You implement transactional authorization as an environment condition type in an [authorization policy](configuring-policies.html) and affects the [authorization decision](what-is-authz-decision.html). | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * Transactional authorization isn't designed to work with account lockout and doesn't increment lockout counters. Therefore, don't use transactional authorization with authentication mechanisms that are susceptible to brute force attacks, such as simple username/password authentication, or OTP authentication. Configure transactional authorization if you're using a strong authentication mechanism, such as [MFA: Authenticate using push notification](../am-authentication/authn-mfa-about-push.html), that isn't susceptible to brute force attacks. If you *do* use transactional authorization with a weaker authentication mechanism like OTP authentication, you *must* manage rate-limiting in some other way. * Transactional authorization policies aren't supported for the `JwtClaim` [subject type](rest-api-authz-policies.html#subject-conditions). | ## Understand transactional authorization The following diagram describes the sequence of events when accessing a resource protected by a REST application and an Advanced Identity Cloud policy that contains a transactional environment condition: ![Sequence of events for transaction authorization.](_images/figure-transactional-how-it-works.svg)Figure 1. Access Resources with Transactional Authorization The sequence of events for a transaction authorization is as follows: 1. An authenticated user attempts to access a resource that's protected by Advanced Identity Cloud. 2. The REST application, a resource server, contacts Advanced Identity Cloud to evaluate the policies that apply. 3. Because the policy has a transaction environment condition, Advanced Identity Cloud creates a transaction token in the Core Token Service (CTS) store. The initial transaction token state is set to `CREATED`. The transaction token includes the following information about the policy evaluation: * Realm * Resource * Subject * Audit tracking ID * Authentication method To protect against tampering, Advanced Identity Cloud verifies that these details don't change and match those in the incoming requests for the duration of the transaction. The transaction token has a time-to-live (TTL), defined in the [Transaction Authentication service](../am-reference/services-configuration.html#realm-transaction). The default TTL is 180 seconds. If the transaction is not completed within this time, the token is deleted, and the flow must be restarted. Change the default TTL if the transaction includes authentication actions that take more time to complete. For example, using HOTP authentication for an OTP over email. You can configure the time-to-live per realm. Refer to [Transaction Authentication service](../am-reference/services-configuration.html#realm-transaction). 4. In the JSON response to the policy evaluation request, Advanced Identity Cloud returns the transaction ID—​the unique ID of the newly created transaction token—​in the `TransactionConditionAdvice` array of the `advices` object: ```json { "resource": "https://bank.example.com:443/withdraw?amount=100.00", "actions": {}, "attributes": {}, "advices": { "TransactionConditionAdvice": [ "7b8bfd4c-60fe-4271-928d-d09b94496f84" ] }, "ttl": 0 } ``` 5. Because the JSON response to the evaluation doesn't grant any actions but contains advices, the REST application (resource server) extracts the transaction ID and returns it to the authentication service to start the authentication. The query parameters sent as part of the request for actions include an `authIndexType` of `transaction` and the transaction ID as the `authIndexValue`. 6. Advanced Identity Cloud extracts the transaction ID, verifies the corresponding transaction token, and changes the state to `IN_PROGRESS`. If the transaction ID isn't in the expected state or doesn't exist, Advanced Identity Cloud returns a `401 Unauthorized` error. For example: ```json { "code": 401, "reason": "Unauthorized", "message": "Unable to read transaction.", "detail": { "errorCode": "128" } } ``` 7. Advanced Identity Cloud responds with the callbacks necessary to satisfy any environment conditions. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The advices returned by transaction environment conditions have the lowest precedence when compared to the other condition advices. End users must respond to non-transactional condition advices before they respond to the transactional condition advices. | 8. The REST application (resource server) renders the callbacks and presents them to the user. 9. The user completes the required actions. For example, the user completes the journey specified in the policy, by responding to a push notification on their registered mobile device to confirm a transaction. If the user doesn't complete the required actions, Advanced Identity Cloud returns an HTTP 200 message, and redirects the user to the protected resource. Policy evaluation fails since the transactional authorization process failed. 10. Advanced Identity Cloud verifies the transaction token and changes the state to `COMPLETED`. 11. With the transaction now complete, Advanced Identity Cloud returns the original token. Note that the authentication performed as part of an authorization flow does not behave the same as a standard authentication. The differences are: * The user's original session isn't upgraded or altered in any way. * Failing the authentication during the authorization flow doesn't increment account lockout counters. 12. The REST application (resource server) requests the policy decision again, including the ID of the completed transaction as a value in the `TxId` array of the `environment` object: ```json { "resources" : ["https://bank.example.com:443/withdraw?amount=100.00"], "application" : "iPlanetAMWebAgentService", "subject" : { "ssoToken" : "AQIC5w...*AJTMQAA*" }, "environment": { "TxId": ["7b8bfd4c-60fe-4271-928d-d09b94496f84"] } } ``` 13. Advanced Identity Cloud verifies that the transaction was authorized and that the transaction token is in the `COMPLETED` state. 14. If the transaction completes successfully, the authorization continues. Advanced Identity Cloud marks the transaction token for deletion so that it can't be used to grant more than one access. 15. As the authentication required to complete the transaction was successful, Advanced Identity Cloud returns the result of the policy reevaluation. For example, the following response grants the `POST` and `GET` actions to the resource `https://bank.example.com:443/withdraw?amount=100.00`: ```json { "resource": "https://bank.example.com:443/withdraw?amount=100.00", "actions": { "POST": true, "GET": true }, "attributes": {}, "advices": {}, "ttl": 0 } ``` | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Successful transactional authorization responses set the time-to-live (`ttl`) value to zero to ensure that the policy decision isn't cached and can't be used more than once. | 16. The user is able to access the protected resource once. Additional attempts to access a resource protected by a policy containing a transactional environment condition require a new transaction to be completed. ## Configure transactional authorization To use transactional authorization, you must coordinate the configuration of: * An appropriate user journey for the transaction. * The Advanced Identity Cloud policy or policies that use the journey. * Support for transactional authorization in your applications. ### The user journey The journey communicates to the user what they're authorizing when they approve the transaction, and gives them the means to approve (or reject) the operation. For example, if the transaction involves a withdrawal from the user's bank account, you could configure a [multi-factor authentication](../am-authentication/authn-introduction-authn.html#about-mfa) journey that displays "Confirm $100 withdrawal from Example Bank?" with Yes and No options for a push notification to a registered device, or sends an OTP to a registered device with a similar message. Configure the journey in the same realm as the policy. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Consider the following points when configuring the journey:- To prevent users from authenticating directly through this journey, either for security reasons or because the journey is insufficient as a complete authentication service, configure it as a [transactional authentication journey](../am-authentication/configure-authentication-trees.html#configure-transactional-auth-journey). - You can't use a [Set Failure Details node](https://docs.pingidentity.com/auth-node-ref/latest/set-failure-details.html) with transactional authentication. A failed transaction returns a `200 OK` response, and the node only adds failure details for a `401 Unauthorized` response. | ### The policy A transactional authorization policy specifies the following: * The conditions that trigger the required authorization. * The journey the end user must complete to authorize the transaction. In other respects, it's a standard Advanced Identity Cloud authorization policy, configured under Native Consoles > Access Management. The following example policy applies to the `/withdraw` endpoint. Its transactional authorization environment condition specifies that the user must complete the `AuthorizeTransaction` journey to authorize access to the endpoint: ![Policy to approve withdrawls](_images/transactional-authorization-policy.png) To add the environment condition, set: * Type `Transaction` * Authentication Strategy `Authenticate to Tree` * Strategy Specifier The name of the journey ### Your application A quick way to protect your application is to use Ping Identity software. PingGateway, Ping SDKs, and agents all support transactional authorization. * When using PingGateway to protect your application, configure it for use with Advanced Identity Cloud. Refer to the [Advanced Identity Cloud](https://docs.pingidentity.com/pinggateway/latest/aic/preface.html) pages in the PingGateway documentation. These pages describe how to use PingGateway as an OAuth 2.0 client of Advanced Identity Cloud and resource server. They also describe and how to use cross-domain single sign on (CDSSO) for applications that aren't in your tenant's domain. Also refer to the PingGateway documentation to [configure PingGateway as a policy enforcement point (PEP) when using CDSSO](https://docs.pingidentity.com/pinggateway/latest/gateway-guide/policy-enforcement.html#pep-cdsso). PingGateway as a PEP transparently manages redirection when Advanced Identity Cloud policy requires transactional authorization. * When using the Ping SDKs, refer to [Perform transactional authorization](https://docs.pingidentity.com/sdks/latest/sdks/use-cases/how-to-perform-transactional-authorization.html). * When using an agent to protect your application, refer to the Java agent page on [enforcing Advanced Identity Cloud policy decisions](https://docs.pingidentity.com/java-agents/latest/identity-cloud-guide/pep.html) or the web agent page on [enforcing Advanced Identity Cloud policy decisions](https://docs.pingidentity.com/web-agents/latest/identity-cloud-guide/pep.html). ## Demonstrate transactional authorization After configuring the journey, the policy, and your application, access the protected resource. The example described here involves a bank withdrawal operation. The following steps put the end user interaction with Advanced Identity Cloud in context: 1. Barbara Jensen browses her online bank at `https://bank.example.com` and signs on to access her account: ![Signing on at the online bank](_images/transactional-bank-signon.png) 2. Barbara prepares to withdraw $100 from her account using the online bank application. The application as PEP continues to contact Advanced Identity Cloud for policy decisions as Barbara browses through the application. 3. Barbara confirms her intention to complete the withdrawal, triggering the application to access the `/withdraw` endpoint. When requesting a policy decision for this endpoint, the application gets advices indicating transactional authorization. It redirects Barbara to the journey required for this transaction according to the policy. The important step of the journey is the decision to authorize the withdrawal: ![Confirming a withdrawal](_images/transactional-bank-withdrawal.png) 4. Barbara receives the money and a receipt page after the application finishes processing the transaction with Advanced Identity Cloud. The steps the application follows to perform transactional authorization are identical to those for session upgrade. For details, refer to [Session upgrade with MFA](../am-sessions/session-upgrade.html).