--- tags: aca-py --- # Aries Cloudagent Web Application Integration Guidelines This document outlines best practices and guidelines to be considered and implemented when integrating an existing system with Aries Cloudagent. # Architecture Generally speaking, a web application that leverages Aries agents is structured as follows: * `Agent`: this service is used by the web application to interact with a Ledger and other agents connected to the same ledger. It is generally not controlled directly by the web application frontend, instead requests to the agent come from a `controller` service. * `Controller`: this service provides the business logic for the web application, and acts as bridge between the `frontend` and the `agent`. The `controller` usually exposes appropriate APIs that the `frontend` will use to perform common business tasks as well as agent-related tasks such as requesting the creation of a new connection, etc. The controller is also tasked with tracking and managing all of the information that is required for the business processes to be implemented and work successfully. * `Frontend`: this service is what the users see and interact with, commonly something that is displayed in a web browser. The above components may be at times partially consolidated or further split into separate services, the purpose of this overview is to explain the separation of concerns of these three macro-areas. ## Creating and Managing Connections A connection is a communication channel established between two Aries agents. It allows them to send and receive data and interact: issuing a credential or requesting/sending a proof request require, in most cases, a valid, active connection to be completed. The closest relative of a connection between Aries agents in the web application world is a session: for this reason the recommended way of tracking open connections in a web application is to use a session cookie. ### Implementation As discussed previously, to establish a new connection the `frontend` would call the appripriate `controller` API endpoint to create a new connection invitation. The controller would translate this request to the appropriate call to the admin APIs in the `agent` service, and return the data that will be displayed in a QR code for the mobile wallet to scan and use. A connection is identified within an agent by an id. This id is used when retrieving connection information as well as when instructing the agent to send/request something via a specific channel. When creating/requesting new connections, the web application should set and manage a session cookie whose payload corresponds to the UUID of the connection being targeted/used. **Important:** the session cookies shuld be set to `Secure` and `HttpOnly` to mitigate the risk of exposing its contents to the web, as well as the risk of cross-site scripting attacks. Connections do not expire, however they can be deleted by either agent involved in the protocol: the cookie should therefore not expire, or have an expiration date that is longer than the average lapse of time between interactions between the user and the service. 1. `First interaction`: the applications's `frontend` sends a request for a new connection to the `controller`. No cookie is being passed in the headers since no connection was yet established, therefore the `controller` proceeds to generate a new connection invitation with its `agent`, and sends a response to the frontend using the `Set-Cookie` header to create a new cookie with the connection's UUID as payload. 2. `Second interaction`: following the first interaction, both agents will have established a connection that can be reused for future protocol exchanges. When initiating a new agent interaction from the `frontend`'s UI, the client will send a request for a new connection to the `controller`, including the previously created cookie in the header. The `controller` will use that information to initiate the appropriate task on the specified channel. The `frontend` will not display a QR code to establish a new connection and will send a response setting the cookie, again, with the same value.. * i.if the `controller` has lost/removed the connection record specified in the cookie, it will proceed to generate a new connection invitation in a similar way to the first interaction. It will then send the response to the `frontend`, that will display a new QR code for the user to scan. The response will include a new `Set-Cookie` header, populated with the new connection UUID. * if the session cookie was removed from the `frontend`, the connection request would not include a value for the cookie and would therefore be considereed by default as a new connection request. * if the user has removed the connection from their wallet, the UI should display controls to establish a new connection. The `controller` will likely attempt to communicate on the existing connection, while the `frontend` should display a "get a new connection" control after a few seconds to allow users to recover from this state. **Note:** while it shoudn't be a problem to keep old "dead" connection records in the `agent`, it seems like good practice for the `controller` to instruct the agent to remove connections being replaced. The `controller` should be tracking the appropriate information to facilitate this process and no recommendation will therefore be made on how to implement/achieve this. # Interaction Diagram #### First Interaction Describes flow for first interaction (no previously established connection) and/or browser cookies cleared/absent. It lso applies to the - less likely - scenario where the connection was deleted on the controller/agent side. ```sequence participant Mobile Wallet participant Frontend participant Controller participant Agent Frontend-->Controller: Request Connection Controller-->Agent: /connections/create-invitation Agent-->>Controller: New Invitation\n ID: 12345 Controller-->>Frontend: New Invitation\n (Set-Cookie: 12345) Frontend->Frontend: Create QR code Mobile Wallet-->Frontend: Scan QR Code Agent-->>Mobile Wallet: Establish Connection Agent-->>Controller: Webhook: connection 12345 established Controller-->Agent: Do something\n (request proof, issue credential, etc.) Agent-->Mobile Wallet: Using connection ``` #### Following Interactions Describes flows for 2nd and following interactions, when a session cookie is available and the connection is present and active on both mobile wallet and agent. ```sequence participant Mobile Wallet participant Frontend participant Controller participant Agent Frontend-->Controller: Request Connection (Set-Cookie: 12345) Controller->Controller: Connection 12345 exists\n (may also check with agent) Controller-->Agent: Do something\n (request proof, issue credential, etc.) Controller-->>Frontend: Response\n (Set-Cookie: 12345) Agent-->Mobile Wallet: Using connection Frontend->Frontend: Display connection recovery\n button after 2s-3s Agent-->>Controller: Webhook updates ``` ##### Following Interactions - Recovery Describes the flow for 2nd and following interaction, in the scenario where the connection was removed from the mobile wallet, and a session cookie is available ```sequence participant Mobile Wallet participant Frontend participant Controller participant Agent Frontend-->Controller: Request Connection (Set-Cookie: 12345) Controller->Controller: Connection 12345 exists\n (may also check with agent) Controller-->Agent: Do something\n (request proof, issue credential, etc.) Controller-->>Frontend: Response\n (Set-Cookie: 12345) Agent-->Mobile Wallet: Using connection Frontend->Frontend: Display connection recovery\n button after 2s-3s Agent-->>Controller: Webhook updates Frontend->Frontend: Click recovery button Frontend-->Controller: Request Connection Controller-->Agent: /connections/create-invitation Agent-->>Controller: New Invitation\n ID: 56789 Controller-->>Frontend: New Invitation\n (Set-Cookie: 56789) Frontend->Frontend: Create QR code Mobile Wallet-->Frontend: Scan QR Code Agent-->>Mobile Wallet: Establish Connection Agent-->>Controller: Webhook: connection 56789 established Controller-->Agent: Do something\n (request proof, issue credential, etc.) Agent-->Mobile Wallet: Using connection ```
Last changed by  
 
Emiliano Suñé
722

Read more

Aries BPA + Aries VCR: Onboarding Scenario

Current State When onboarding a new standalone Issuer to an Aries VCR instance (e.g.: OrgBook), an out-of-band step is required to establish the connection between the Issuer agent and the Aries VCR agent that will receive the credentials. This task needs to be completed by a developer with access to the administrative API for the Aries VCR agent, and one with access to the administrative API for the Issuer agent. Either developer will initiate the process by manually generating a new connection invitation on the agent they manage, and send the resulting payload to their counterpart, who will manually submit a request to their agent to accept the connection invitation. The invitation payload is transmitted using a method (e.g.: email, chat client) that might have some degree of risk involved with a third party malicious actor intercepting it and connecting to either agent instead of the expected party. Proposed Solution The use of a Business Partner Agent as base for both the Aries VCR and Issuer will mitigate the issues present in the current state as: either agent will be able to initiate a connection invitation by finding the target agent on a public/authorized list of connections (like in a directory)

3/29/2022
Aries Cloudagent Python: simplifying the endorser and revocation workflows

Background Aries Cloudagent Python recently introduced the ability for non-privileged agents (from here on: author) to request endorsement of transactions that need to be written to the ledger by an agent (from here on: endorser) with ledger write privileges. A common use case for this functionality is for an organization running an agency of authors (that can be created/destroyed without needing any write interaction with the ledger) and a single instance of an endorser agent that acts as a gateway for all write needs: registering the author's DID on the ledger endorse writing a new schema to the ledger endorse writing a new credential definition to the ledger endorse writing a new revocation registry definition to the ledger

3/29/2022
Connection-Less Proof Requests with ACA-Py

When using Aries Cloudagent Python (ACA-Py) most of the interactions with other agents occur on a connection, established beforehand and persisted across interactions. There are, however, scenarios where a connection-less interaction is useful, if not preferable. With ACA-Py the only type of connection-less interaction supported "out-of-the-box" is submitting proof requests. Service Decorator When utilizing a connection-less proof request, the verifier is identified by the presence of a service decorator section in the received proof request, rather than a connection identifier. The end result, however, is the same: the prover/holder knows where to send the proof, even if a connection with the verifier was not established ahead of time. See this link for reference. Structure of the Request

3/29/2022
Read more from Emiliano Suñé
Published on HackMD