Transactional authorization

Transactional authorization requires a user to authorize every access to a resource. It is part of an AM 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 additional action successfully grants access to the protected resource but only once. Additional attempts to access the resource require the user to perform the configured actions again.

Transactional authorization is implemented as an environment condition type in an authorization policy, and affects the authorization decision.

Transactional authorization is not designed to work with account lockout and does not increment lockout counters. As such, don’t use transactional authorization with authentication mechanisms that are susceptible to brute force attacks, such as simple username/password authentication, or OTP authentication. Instead, configure transactional authorization if you are using a strong authentication mechanism, such as MFA: Push authentication, which is not susceptible to brute force attacks. If you do use transactional authorization with an authentication mechanism, such as OTP authentication, make sure that you manage rate-limiting in some other way.

Understand transactional authorization

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:

Figure 1. Access Resources with Transactional Authorization

The sequence of events for a transaction authorization is as follows:

An authenticated user attempts to access a resource that is protected by an AM server.
The REST application, a resource server, contacts AM to evaluate the policies that apply.
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 at 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. Refer to Transaction Authentication service.

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 of the advices object:

{
    "resource": "https://bank.example.com:443/withdraw?amount=100.00",
    "actions": {},
    "attributes": {},
    "advices": {
        "TransactionConditionAdvice": [
            "7b8bfd4c-60fe-4271-928d-d09b94496f84"
        ]
    },
    "ttl": 0
}

As the JSON response to the evaluation does not grant any actions but does contain advices, the REST application (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.
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"
    }
}
```

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 must respond to non-transactional condition advices before they respond to the transactional condition advices.

The REST application (resource server) renders the callbacks and presents them to the user.
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 does not complete the required actions, AM returns an HTTP 200 message, and the user is redirected to the protected resource. Policy evaluation fails since the transactional authorization process failed.
AM verifies the transaction token and changes the state to COMPLETED.
With the transaction now complete, AM 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 is not upgraded or altered in any way.
- Failing the authentication during the authorization flow does not increment account lockout counters.

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:

{
    "resources" : ["https://bank.example.com:443/withdraw?amount=100.00"],
    "application" : "iPlanetAMWebAgentService",
    "subject" : {
        "ssoToken" : "AQIC5w....*AJTMQAA*"
    },
    "environment": {
        "TxId": ["7b8bfd4c-60fe-4271-928d-d09b94496f84"]
    }
}

AM verifies the transaction was authorized and that the transaction token is in the COMPLETED state.
If the transaction was completed successfully, the authorization continues.

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

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 https://bank.example.com:443/withdraw?amount=100.00:

{
    "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 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.

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 AM 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 are 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 journey that displays "Confirm $100 withdrawal from Online Bank?" with Yes and No options for a push notification to a registered device, or sends a one-time password to a registered device with a similar message.

Configure the journey in the same realm as the policy.

The policy

A transactional authorization policy specifies the conditions that trigger the required authorization. It also specifies a journey the end user must complete to authorize the transaction. In other respects, it is a normal AM authorization policy.

You configure the policy in the AM admin UI. For example, this completed 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:

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 ForgeRock software. ForgeRock Identity Gateway (IG), SDKs, and agents all support transactional authorization.

When using IG to protect your application, configure it for use with Identity Cloud.

Refer to the Identity Cloud pages in the IG documentation. These describe how to use IG as an OAuth 2.0 client of Identity Cloud and resource server, and how to use cross-domain single sign on (CDSSO) for applications that are not in your tenant’s domain.

Also refer to the IG documentation to configure IG as a policy enforcement point (PEP) when using CDSSO. IG as a PEP transparently manages redirection when AM policy requires transactional authorization.
When using a ForgeRock SDK, refer to Perform transactional authorization in the SDKs docs.
When using a ForgeRock agent to protect your application, refer to the Java agent page on enforcing Identity Cloud policy decisions or the web agent page on enforcing Identity Cloud policy decisions.

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 Identity Cloud in context:

Barbara Jensen browses her online bank at https://bank.example.com and signs on to access her account:
Barbara prepares to withdraw $100 from her account using the online bank application.

The application as PEP continues to contact AM in Identity Cloud for policy decisions as Barbara browses through the application.
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:
Barbara receives the money and a receipt page after the application finishes processing the transaction with AM.

The steps the application follows to perform transactional authorization are identical to those for session upgrade. For details, refer to Session upgrade.