Consumer Account Access

Author: simonredfern

obp-api/src/main/scala/bootstrap/liftweb/Boot.scala

@@ -1159,6 +1159,7 @@ object ToSchemify extends MdcLoggable {
     code.glossaryitem.DynamicGlossaryItem,
     code.platformapp.PlatformApp,
     code.platformapp.PlatformAppRequiredScope,
+    code.consumeraccountaccess.ConsumerAccountAccess,
     code.domainapi.DomainApi,
     code.dynamicentitywebhook.DynamicEntityWebhook,
     code.accountcreation.AccountCreation,

obp-api/src/main/scala/code/api/util/APIUtil.scala

@@ -3651,6 +3651,7 @@ object APIUtil extends MdcLoggable with CustomJsonFormats{
         case Some(u) if hasAccountFirehoseAccessAtBank(view,u, bankIdAccountId.bankId)  => Full(true) //Login User and Firehose access
         case Some(u) if hasAccountFirehoseAccess(view,u)  => Full(true)//Login User and Firehose access
         case Some(u) if u.hasAccountAccess(view, bankIdAccountId, callContext)=> Full(true)     // Login User and check view access
+        case Some(u) if hasConsumerAccountAccess(view, bankIdAccountId, u, callContext) => Full(true) // An application acting as itself, on its own grant
         case Some(u) =>
           // Normal checks failed — try ABAC as fallback
           checkAbacAccountAccess(u, view, bankIdAccountId, callContext)
@@ -3659,6 +3660,28 @@ object APIUtil extends MdcLoggable with CustomJsonFormats{
       }
   }
 
+  /**
+   * Account access granted to a Consumer (code.consumeraccountaccess): true when the caller is an application
+   * acting as itself, its Consumer holds a grant for this view of this account, and the endpoint opts in.
+   *
+   * - Acting as itself means the caller is the Consumer's own client-credentials User (provider obp-oidc#client,
+   *   named after the Consumer's key). A person calling through the same Consumer never picks up its grants,
+   *   and neither does a caller identified by a Consumer Key alone: the token proves the client secret.
+   * - The endpoint opts in through its auth mode: only ApplicationOnly and UserXORApplication endpoints admit
+   *   an application acting as itself, so every other endpoint of the view keeps needing a User's access.
+   */
+  def hasConsumerAccountAccess(view: View, bankIdAccountId: BankIdAccountId, user: User, callContext: Option[CallContext]): Boolean =
+    (for {
+      cc <- callContext
+      doc <- cc.resourceDocument
+      if doc.authMode == ApplicationOnly || doc.authMode == UserXORApplication
+      consumer <- cc.consumer.toOption
+      if isApplicationsOwnUser(user, consumer)
+    } yield code.consumeraccountaccess.ConsumerAccountAccesses.consumerAccountAccessProvider.vend
+      .find(consumer.consumerId.get, bankIdAccountId.bankId, bankIdAccountId.accountId, view.viewId)
+      .isDefined
+    ).getOrElse(false)
+
   private def checkAbacAccountAccess(
     user: User,
     view: View,

obp-api/src/main/scala/code/api/util/ErrorMessages.scala

@@ -651,6 +651,9 @@ object ErrorMessages {
   val RetentionHoldAlreadyReleased = "OBP-30621: This retention hold has already been released."
   val InvalidRetentionRunApproval = "OBP-30622: Invalid approval. decision must be approve or reject."
   val InvalidRetentionRun = "OBP-30623: Invalid retention run. mode must be preview or execute."
+  val ConsumerAccountAccessAlreadyExists = "OBP-30627: This Consumer already has access to this view of this account."
+  val ConsumerAccountAccessNotFound = "OBP-30628: Consumer account access not found by CONSUMER_ACCOUNT_ACCESS_ID on this account."
+  val CannotGrantConsumerAccountAccessToView = "OBP-30629: A Consumer cannot be given access to this view. The owner view and public views are for Users: give the Consumer a view with only the permissions it needs."
 
   // Routing Scheme registry (OBP-30514 .. OBP-30525)
   val RoutingSchemeNotFound = "OBP-30514: Routing Scheme not found. Please specify a valid value for SCHEME."

obp-api/src/main/scala/code/api/util/Glossary.scala

@@ -7428,6 +7428,39 @@ object Glossary extends MdcLoggable  {
 				 |- [Update Current Consumer Platform App](${apiExplorerUrl}/resource-docs/OBPv7.0.0?operationid=OBPv7.0.0-updateCurrentConsumerPlatformApp): `PUT /obp/v7.0.0/consumers/current/platform-app`, for an app to declare the Scopes it needs.
 				 |- [Get Current Consumer Scopes](${apiExplorerUrl}/resource-docs/OBPv7.0.0?operationid=OBPv7.0.0-getCurrentConsumerScopes): `GET /obp/v7.0.0/consumers/current/scopes`, for an app to read the Scopes its Consumer holds.
 				 |- [Create Scope for a Consumer](${apiExplorerUrl}/resource-docs/OBPv7.0.0?operationid=OBPv7.0.0-addScope): `POST /obp/v7.0.0/consumers/CONSUMER_ID/scopes`, to grant a missing Scope.
+				 |
+				 |A Scope says which endpoints an app may call. An app that also acts on an account through a view, such as initiating payments from it, needs access to that view of the account as well: see ${getGlossaryItemLink("Consumer Account Access")}.
+				 |""".stripMargin)
+
+	glossaryItems += GlossaryItem(
+		title = "Consumer Account Access",
+		description =
+			s"""
+				 |# Consumer Account Access
+				 |
+				 |OBP has two layers of permission. **Roles** say which endpoints may be called; they are granted to a User as Entitlements and to a Consumer as Scopes. **Account access** says which accounts may be used, and through which view; it is granted to a User, and with Consumer Account Access also to a Consumer.
+				 |
+				 |It is for an application that acts on an account as itself, with its own application token (OAuth2 client credentials), when no person is involved: for example a bank's service that initiates payments from the bank's own account for customers whose payments it relays. Without it, such a service has to log in as a stand-in User who holds the account access.
+				 |
+				 |## How it works
+				 |
+				 |1. Someone who may grant views of the account (their view lists the target view in `can_grant_access_to_views`, or has `can_grant_access_to_custom_views` for a custom view) gives the Consumer access to a view. The grant records who gave it.
+				 |2. The application calls an endpoint of that view with its client-credentials token. Its User is then the Consumer's own (provider `obp-oidc#client`, named after the Consumer's key), and OBP finds the Consumer's grant.
+				 |3. The grant counts only on endpoints that admit an application acting as itself (auth mode ApplicationOnly or UserXORApplication). On every other endpoint the view still needs a User's account access.
+				 |
+				 |A person who logs in through the same Consumer does not get the Consumer's account access, and a caller identified by the Consumer Key alone does not either: only the client-credentials token proves the application is calling as itself.
+				 |
+				 |## Which view
+				 |
+				 |The owner view and public views can't be granted to a Consumer. Holding an account is for people. Give the Consumer a view with only the permissions it needs, for example a custom view with `can_add_transaction_request_to_any_account` for initiating payments: create it with Create Custom View (Management), `POST /obp/v6.0.0/management/banks/BANK_ID/accounts/ACCOUNT_ID/views` (Role CanCreateCustomView), and grant it through the ManageCustomViews system view, which has `can_grant_access_to_custom_views` and which the account holder can give through owner. The Transaction Requests the Consumer creates record it.
+				 |
+				 |## Endpoints
+				 |
+				 |- [Grant Consumer access to View](${apiExplorerUrl}/resource-docs/OBPv7.0.0?operationid=OBPv7.0.0-grantConsumerAccessToView): `POST /obp/v7.0.0/banks/BANK_ID/accounts/ACCOUNT_ID/views/VIEW_ID/consumer-account-access`
+				 |- [Get Consumer access to Account](${apiExplorerUrl}/resource-docs/OBPv7.0.0?operationid=OBPv7.0.0-getConsumerAccountAccess): `GET /obp/v7.0.0/banks/BANK_ID/accounts/ACCOUNT_ID/views/VIEW_ID/consumer-account-access`
+				 |- [Revoke Consumer access to View](${apiExplorerUrl}/resource-docs/OBPv7.0.0?operationid=OBPv7.0.0-revokeConsumerAccessToView): `DELETE /obp/v7.0.0/banks/BANK_ID/accounts/ACCOUNT_ID/views/VIEW_ID/consumer-account-access/CONSUMER_ACCOUNT_ACCESS_ID`
+				 |
+				 |See also ${getGlossaryItemLink("Platform Apps")}.
 				 |""".stripMargin)
 
 	glossaryItems += GlossaryItem(

obp-api/src/main/scala/code/api/v7_0_0/Http4s700.scala

@@ -4764,6 +4764,8 @@ object Http4s700 {
         |
         |Requires `open_corridor_enabled=true` on this instance. Whether it is on shows in GET /banks/BANK_ID/transaction-request-types, which lists OPEN_CORRIDOR_PROMISE exactly when it is.
         |
+        |The caller is either a User with account access to VIEW_ID, or an application acting as itself (OAuth2 client credentials) whose Consumer has been given access to VIEW_ID of this account (see Consumer Account Access). The view needs `can_add_transaction_request_to_any_account` or `can_add_transaction_request_to_beneficiary`. The Transaction Request records the Consumer that created it.
+        |
         |Authentication is Required.""".stripMargin,
       openCorridorBodyExample,
       JSONFactory700.TransactionRequestWithChargeOpenCorridorJsonV700(
@@ -4800,6 +4802,7 @@ object Http4s700 {
            InsufficientAuthorisationToCreateTransactionRequest, UnknownError),
       apiTagTransactionRequest :: Nil,
       None,
+      authMode = UserXORApplication,
       http4sPartialFunction = Some(createTransactionRequestOpenCorridor)
     )
 
@@ -7722,6 +7725,9 @@ object Http4s700 {
     // Data retention: retention policies, runs and their approval, the disposal register, legal holds and the archive.
     resourceDocs ++= Http4s700Retention.resourceDocs
 
+    // Consumer account access: a view of an account granted to a Consumer, for an application acting as itself.
+    resourceDocs ++= Http4s700ConsumerAccountAccess.resourceDocs
+
     // The order in which the routes are tried. ResourceDocMiddleware selects the doc of the first
     // route that serves a request, so it is given this same list: the doc that validates a request
     // is the doc of the route that runs it.