Identity Cloud

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

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:

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

  2. The REST application, a resource server, contacts AM to evaluate the policies that apply.

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

  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 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
    }
  5. 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.

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

  10. AM verifies the transaction token and changes the state to COMPLETED.

  11. 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.

  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:

    {
        "resources" : ["https://bank.example.com:443/withdraw?amount=100.00"],
        "application" : "iPlanetAMWebAgentService",
        "subject" : {
            "ssoToken" : "AQIC5w....*AJTMQAA*"
        },
        "environment": {
            "TxId": ["7b8bfd4c-60fe-4271-928d-d09b94496f84"]
        }
    }
  13. AM verifies the transaction was authorized and that the transaction token is in the COMPLETED state.

  14. 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.

  15. 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.

  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 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:

Policy to approve withdrawls

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.

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:

  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
  2. 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.

  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
  4. 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.

Copyright © 2010-2022 ForgeRock, all rights reserved.