Identity Cloud

Transactional authorization

Transactional authorization improves security by requiring a user to perform additional actions when trying to access a resource protected by an AM policy. For example, they must re-authenticate, or respond to a push notification on their mobile device.

Performing the additional action successfully grants access to the protected resource, but only once. Additional attempts to access the resource will require the user to perform the configured actions again.

Transactional authorization is implemented as a environment condition type that can be added to authorization policies.


The transactional authorization environment condition can be combined in policies with the other conditions. For example, only requiring a push notification response when access is attempted to the employees subrealm, but outside usual working hours, as shown below:

Combined with other environment conditions
Figure 1. Combining With Other Environment Conditions

Related information: Authorization and policy decisions

How does transactional authorization work?

The following diagram describes the sequence of events that occur when accessing a resource that is protected by a REST application, and an AM policy containing a transactional environment condition:

Access Resources with Transactional Authorization
Figure 2. 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 is protected by an AM server.

  2. The resource server contacts AM to evaluate the policies that apply.

    The resource server can be protected with ForgeRock’s Web or Java Agents, which support transactional authorization natively, or a custom application that uses ForgeRock’s REST API as per the diagram to manage the transactional authorization.

  3. As the policy contains a transaction environment condition, AM creates a transaction token in the Core Token Service (CTS) store. The initial transaction token state is set to CREATED.

    The transaction token contains information about the policy evaluation, including the:

    • Realm

    • Resource

    • Subject

    • Audit tracking ID

    • Authentication method

    To protect against tampering, AM verifies that these details do not change and match those in the incoming requests for the duration of the transaction.

    The transaction token has a time-to-live (default 180 seconds) defined in the Transaction Authentication Service. If the transaction is not completed in this time, the token is deleted, and the flow will need to be restarted. Alter the default if the transaction includes authentication actions that take more time to complete. For example, using HOTP authentication for a one-time password over email.

    The time-to-live can be configured per realm. See Transaction Authentication service.

  4. In the JSON response to the policy evaluation request, AM returns the transaction ID—the unique ID of the newly created transaction token—in the TransactionConditionAdvice array in the advices object:

        "resource": "",
        "actions": {},
        "attributes": {},
        "advices": {
            "TransactionConditionAdvice": [
        "ttl": 0
  5. As the JSON response to the evaluation does not grant any actions but does contain advices, the REST application on the resource server extracts the transaction ID and returns it to the authentication service to commence the authentication.

    The transaction ID is included in the TransactionConditionAdvice attribute value pair in the composite advice query parameters sent as part of the request for actions.

    ForgeRock web and Java agents manage this interaction natively. For information on using the REST API to handle advices elements in policy evaluations, see Request policy decisions over REST.

  6. AM extracts the transaction ID from the composite advice, verifies the corresponding transaction token, and changes the state to IN_PROGRESS.

    If the transaction ID is not in the expected state or does not exist, a 401 Unauthorized error is returned. For example:

        "code": 401,
        "reason": "Unauthorized",
        "message": "Unable to read transaction.",
        "detail": {
            "errorCode": "128"
  7. AM 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 will have to complete the non-transactional condition advices before they can complete the transactional condition advices.

  8. The REST application renders the callbacks and presents them to the user.

  9. The user completes the required actions.

    For example, authenticates to the specified tree, or responds to the push notification on their registered mobile device.

    If the user is unable to complete the actions, AM returns an HTTP 200 message and the user is redirected to the protected resource. Policy evaluation will fail since the transactional authorization process has failed.

  10. The REST app completes the callbacks and returns the result to AM.

  11. AM verifies the transaction token, and changes the state to COMPLETED.

  12. With the transaction now complete, AM returns the original token.

    Note that the authentication performed as part of an authorization flow does not behave exactly the same as a standard authentication. The differences are:

    • The user’s original session is not upgraded or altered in any way.

    • Failing the authentication during the authorization flow does not increment account lockout counters.

  13. The web or Java agent or custom application on the resource server can reevaluate the policies applying to the protected resources again, but includes the ID of the completed transaction as a value in the TxId array in the environment object:

        "resources" : [""],
        "application" : "iPlanetAMWebAgentService",
        "subject" : {
            "ssoToken" : "AQIC5w....*AJTMQAA*"
        "environment": {
            "TxId": ["7b8bfd4c-60fe-4271-928d-d09b94496f84"]
  14. AM verifies the transaction was authorized and that the transaction token is in the COMPLETED state.

  15. If the transaction was completed successfully, authorization continues.

    The transaction token is marked for deletion, so that it cannot be used to grant more than a single access.

  16. As the authentication required to complete the transaction was successful, AM returns the result of the policy reevaluation.

    For example, the following response grants the POST and GET actions to the resource

        "resource": "",
        "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 is not cached and cannot be used more than once.

    ForgeRock agents prior to version 5 do not support a time-to-live value of zero and cannot be used for transactional authorization.

  17. The user is able to access the protected resource once.

    Additional attempts to access a resource protected with a policy containing a transactional environment condition require a new transaction to be completed.

To configure transactional authorization, first configure the trees you need for session upgrade, then configure your policies.

Copyright © 2010-2022 ForgeRock, all rights reserved.