diff --git a/documentation/docs/atala-prism/infrastructure/hosted-instances.md b/documentation/docs/atala-prism/infrastructure/hosted-instances.md deleted file mode 100644 index 7022a1677..000000000 --- a/documentation/docs/atala-prism/infrastructure/hosted-instances.md +++ /dev/null @@ -1,99 +0,0 @@ -# Hosted Instances - -PRISM is designed as a cloud-native technology stack and is available to clients as a Software-as-a-Service (SaaS) offering. - -Clients and their developers can quickly begin interacting and building upon the SaaS offering without worrying about running an instance themselves. - -This section introduces the basics of hosted instances, some details on their architecture, and links to instructions for interacting with them. - -## Overview - -Instances of the PRISM offering are hosted in Amazon Web Services and run within a Kubernetes container execution layer. - -Each instance is single-tenant, has dedicated storage, and runs on shared infrastructure - all isolated. - -![Four single-tenant instances running isolated on shared infrastructure](/img/hosted-instances-overview-1.svg) - -### Ingress into a dedicated instance - -Each organization accesses its dedicated instance through an API Gateway that enforces authentication. - -![Each instance is in use by a different organization](/img/hosted-instances-overview-2.svg) - -Organizations cannot access any other instance apart from their own - -![Organisation 1 cannot ](/img/hosted-instances-overview-3.svg) - -Each instance has a dedicated domain name, and API tokens are issued to the organization to manage access. - -All ingress points are protected with TLS using strong ciphers and configuration parameters. - -### Accessing your dedicated instance - -The name of each PRISM instance is a unique, randomly generated, 12-digit alphanumeric code. - -A domain name is created for each instance using this instance-id. - -> Please note that these instance-ids have been shortened to the first five digits in the diagrams on this page for brevity. - -You can access your instance by prepending your instance-id to `atalaprism.io` - -For example, for an environment given the instance-id of `ei30m6d5368w`, its APIs will be available at `ei30m6d5368w.atalaprism.io` - -:::note - -Atala also prepends a `purpose` flag to instances. This flag indicates if they are development (d), test (t), staging (s), or production (p) instances. The purpose flag is not part of the domain. - -::: - -Atala will provide you with your instance-id and API tokens during onboarding. - -:::tip Getting more tokens - - Atala recommends that you request the creation of additional tokens for each integration/service or human user that you have. Please see [Getting Help](../getting-help) for instructions on how to get in touch with us to request additional API tokens. - -::: - -An API token must get added to every API call to non-public endpoints. The API token must be attached using a header in the HTTP requests under the key of `apikey` - -![Example Insomnia window showing `apikey` header being specified](/img/hosted-instances-apikey-header.png) - -:::info Public Endpoints - -Some endpoints must be unprotected in that they do not require authentication. These endpoints must be accessible by everyone for the agent to interact with the wider identity ecosystem which requires interoperability with common standards. A good example of a public endpoint is the DIDComm endpoint - which - must be able to receive messages from client devices with no fixed address and whose agents do not know of the PRISM authentication requirement. - -::: - -### What makes up a dedicated instance? - -Each dedicated instance contains - - a PRISM Cloud Agent, - - a PRISM Cloud Agent Enterprise, - - a Verifiable Data Registry - PRISM Node, - - and Dedicated Relational Storage - -PRISM Node speaks to Cardano through shared infrastructure - -![Each dedicated instance contains a PRISM Cloud Agent Enterprise, a PRISM Cloud Agent, a Verifiable Data Registry and Dedicated Relational Storage](/img/hosted-instances-overview-4.svg) - -Each instance exposes many HTTP routes, allowing an organization to consume the components' capabilities. - - **PRISM Cloud Agent**, which sits at the core of every PRISM instance, provides: - - a *DIDComm v2* endpoint for agent-to-agent communication - - endpoints to control the configuration and actions of the agent - - an endpoint that shows documentation in Open API Standard for all available endpoints - -**PRISM Node** does not provide endpoints that an organization can interact with - it gives internal only gRPC endpoints to the PRISM Cloud Agent for reading and writing to the distributed ledger - Cardano. Please see [PRISM Node](../prism-node) for further details on what this component does and how it works. - -Each instance has **Dedicated Relational Storage**, a dedicated instance of a Postgres database. This database is not shared and is accessible from within your tenant only. The database uses authentication with secrets your tenant generates during creation time. - - -### What else do I need to know about my instance? - -Each hosted dedicated instance within a Kubernetes cluster spans a single AWS region. This underlying shared infrastructure is highly resilient and self-healing. - -Atala operates a single AWS region based in US East (N. Virginia). - -Each region's Kubernetes cluster runs on EC2 instances spread amongst availability zones. The cluster runs an auto-scaler which creates additional nodes if a failure in one zone should occur. - -Your instance is observable around the clock; Atala collects metrics and logs from all running services and has pre-defined alerts for notifying operational support staff of issues. diff --git a/documentation/docs/atala-prism/infrastructure/running-agent-locally.md b/documentation/docs/atala-prism/infrastructure/running-agent-locally.md deleted file mode 100644 index 7c4cd92b5..000000000 --- a/documentation/docs/atala-prism/infrastructure/running-agent-locally.md +++ /dev/null @@ -1,214 +0,0 @@ -# Running Agent Locally - -The PRISM Cloud Agent can be downloaded and run in a self-hosted instance. It allows anyone to run an agent on their computer -or server to interact with other agents in the decentralized identity ecosystems. - -:::note - -The PRISM Cloud Agent Enterprise is only available in managed, hosted instances. Please -see [Hosted Instances](hosted-instances) for more details. - -::: - -This section describes how to get started with the PRISM Cloud Agent. - -:::caution - -PRISM Cloud Agent's default configuration is unsuitable for running a production instance. The setup of a production -instance is out of the scope of this section. - -::: - -## Quick Start - -The best way to start running the PRISM Cloud Agent is to use the utility scripts in the PRISM Playground project. - -These utility scripts run an instance of PRISM Cloud Agent using docker-compose and include all required components, -including a database and API Gateway. - -Run the following commands to start a single agent on port 80. - -``` -git clone https://github.com/lohanspies/prism_v2_playground & cd prism_v2_playground -./agent/run.sh -p 80 -``` - -An agent will be up and running on and accessible on `http://localhost/` - -:::info - -Detailed instructions on using the `run.sh` script are available in the PRISM Playground project within -the `agent/README.md` file. - -::: - -### Exposing PRISM Cloud Agent to the internet - -Interacting with other agents requires exposing your agent over the Internet. External parties must be able to connect -to your instance through a publicly available address without being blocked by security defenses like firewalls. - -Running applications on your computer or server using docker-compose will not expose ports/services to the internet - it -will only be available from the host itself and, potentially, the local area network. Additional configuration of your -networking layer is required to allow external systems to send messages to your agent. - -This guide does not detail the configuration needed to expose the agent to the internet via the management of the -networking layer. The networking design is an advanced topic and depends upon the computing environment in which you -operate your agent. - -As an alternative, for quickly getting up and running with a local PRISM Cloud Agent, we recommend using a tunneling -solution such as [ngrok](https://ngrok.com/). - -ngrok is a software package you can download and install that, when executed, creates an externally accessible tunnel to -your machine without the need for complex networking configuration such as firewall management or port forwarding. - -Ngrok assigns a unique domain name to each tunnel created with it, which lives for the duration that ngrok is running. -This domain is the externally accessible ingress point for other agents to communicate with your agent. - -Please visit the [ngrok website](https://ngrok.com/) and sign up for a free account. Once you have completed the sign-up -process, the ngrok website will take you through an installation guide that will help you configure a ngrok agent on -your machine. - -:::tip - -Please see the [ngrok getting started guide](https://dashboard.ngrok.com/get-started/setup) if you already have an -account or did not follow the installation guide when you first signed up. - -::: - -:::danger - -Ensuring that your systems are secure is your responsibility when you host your agent. Please see the -Atala [Hosted Instances](hosted-instances) offering for users who wish to avoid managing their systems. - -Running ngrok and exposing an agent will allow access to the agents' unprotected endpoints from anywhere on the -internet - for example - the DIDComm endpoint will be able to receive messages from any service that knows the address -of your agent. - -Endpoints that are administration or configuration capabilities that do not need to be publicly available have an API -key authentication mechanism applied. You must add an HTTP header with the key `apikey` to each HTTP request. The value -of this key must be a valid authentication token. - -When you run the agent from the playground repository without modification, you run it using the default authentication -key stored in plain text. - -** Please do not run the PRISM Cloud Agent without changing the default authentication key ** - -If you do not change the key, external parties who know this key and your agent address [exposed through ngrok] can -reconfigure your agent and potentially cause further damage or gain access to your systems. - -::: - -#### Changing the default authentication key - -Modify the `agent/apsix/conf/apisix.yaml` file and change line 9 - replace the `RANDOM KEY` text with a randomly -generated token. Atala generates 32 alphanumeric tokens for its hosted service. - -``` -plugins: - - name: proxy-rewrite - - name: key-auth - -consumers: - - username: default - plugins: - key-auth: - key: "RANDOM KEY" <---Change to new token before starting the agent -``` - -#### Running the agent with Ngrok - -The PRISM Cloud Agent `run.sh` script has a command line argument for telling it that you are using ngrok - it will -attempt to configure itself to use the publicly available ngrok URL for the tunnel it creates when running it. - -:::caution - -The `run.sh` requires `jq` - a json manipulation tool - to be installed alongside ngrok. `jq` is -available [here](https://stedolan.github.io/jq/). Please see the installation guide for your platform on the jq website -and complete the installation. - -Please complete the installation of ngrok and jq and create a tunnel per the ngrok getting started guide before -executing the run.sh script - -::: - -After you have created a tunnel - run the PRISM Cloud Agent using the following command: - -``` -run.sh --ngrok -``` - -The `DIDComm Service Endpoint` in your agent must be the ngrok tunnel address. Interactions with other agents -will result in communication flowing back into your agent. - -#### Additional information - -The free account tier of ngrok will provision a random domain every time you start a ngrok tunnel. A tunnel may be -interrupted by network failures and restarts of your system, resulting in the domain name changing. - -As the domain name changes, the location of your agent changes, and other agents may send messages to the wrong place. - -**Please consider subscribing to a commercial plan with ngrok for persistent domain -names [or configure your networking layer manually to allow ingress] if you need the agent to always be accessible in -one place. -** - -:::tip - -The status of an active ngrok tunnel is shown in the ngrok web interface accessible by default from within a web browser -on [http://localhost:4040](http://localhost:4040) - -::: - -The PRISM Cloud Agent docker-compose files include running and configuring an API Gateway - APISIX. An API Gateway is -required when running the PRISM Cloud Agent, as it is built as a microservice architecture and comprises multiple -services running on different network ports. - -The API Gateway unifies these different services into a single ingress plane where a single port is exposed rather than -many. We use APISIX as an API Gateway that provides security and protection to prevent unauthorized access. - -### Running the agent with the Keycloak - -The PRISM Cloud Agent relies on a running Keycloak instance to provide essential authentication and authorization -services. The Keycloak instance handles user authentication and issues access tokens to the Agent for utilization in API -calls. - -To seamlessly run the Agent with a locally deployed Keycloak instance, follow the steps outlined below: - -- enable the Keycloak configuration in the Agent configuration or environment variables -- run docker-compose with the Keycloak configuration located in `infrastructure/shared/docker-compose-mt-keycloak.yml` -- configure the Keycloak instance with the authentication flow and users - -The following section in the Agent application.conf file is for integrating the Agent with the Keycloak: - -```hocon -keycloak { - enabled=false - enabled=${?KEYCLOAK_ENABLED} - - keycloakUrl = "http://localhost:9980" - keycloakUrl = ${?KEYCLOAK_URL} - - realmName = "atala-demo" - realmName = ${?KEYCLOAK_REALM} - - clientId = "prism-agent" - clientId = ${?KEYCLOAK_CLIENT_ID} - - clientSecret = "prism-agent-demo-secret" - clientSecret = ${?KEYCLOAK_CLIENT_SECRET} - - # autoUpgradeToRPT is used to enable the auto RPT (requesting party token) logic. - # if enabled, normal accessToken can be used to perform permission checks by obtaining RPT from accessToken. - # if disabled, accessToken must be RPT which already include the permission claims. - autoUpgradeToRPT = true - autoUpgradeToRPT = ${?KEYCLOAK_UMA_AUTO_UPGRADE_RPT} -} -``` - -When the topology runs, access the Keycloak instance -on [http://localhost:9980](http://localhost:9980) -You must configure the Authentication flow in Keycloak. -The simplest way to start is to create the users with passwords in the Keycloak admin console and use the `Direct Grant.` - -This setup ensures a seamless integration between the PRISM Cloud Agent and Keycloak, providing a secure and efficient -authentication and authorization mechanism. diff --git a/documentation/docs/quick-start.md b/documentation/docs/quick-start.md index bbfad6ea9..3f031ccd7 100644 --- a/documentation/docs/quick-start.md +++ b/documentation/docs/quick-start.md @@ -29,7 +29,7 @@ The diagram details how the concepts fit alongside the PRISM components in a typ ## An overview of Atala PRISM components -Atala PRISM consists of core libraries that facilitate typical SSI interactions between [Issuers](/docs/concepts/glossary/#issuer), [Holders](/docs/concepts/glossary/#holder), and [Verifiers](/docs/concepts/glossary/#verifier). +Atala PRISM consists of core libraries that facilitate typical SSI interactions between [Issuers](/docs/concepts/glossary/#issuer), [Holders](/docs/concepts/glossary/#holder), and [Verifiers](/docs/concepts/glossary/#verifier). ### A Cloud Agent A Cloud Agent can issue, hold, and verify [verifiable credentials (VCs)](/docs/concepts/glossary/#verifiable-credentials) for any entity and manage [decentralized identifiers (DIDs)](/docs/concepts/glossary/#decentralized-identifier) and DID-based connections. The Cloud Agent has an easy-to-use REST API to enable easy integration into any solution and uses [DIDComm V2](/docs/concepts/glossary/#didcomm) as a messaging protocol for agent-to-agent communication. @@ -39,7 +39,7 @@ It is maintained as an open source lab through the [Hyperledger Foundation: Open More in depth documentation about Cloud Agent can be found [here](/docs/atala-prism/prism-cloud-agent/overview). ### Wallet SDKs -Wallet SDKs for web and mobile (iOS, Android, TypeScript) enable identity holders to store credentials and respond to proof requests. They are typically used in applications that allow identity holders to interact with issuers and verifiers. +Wallet SDKs for web and mobile (iOS, Android, TypeScript) enable identity holders to store credentials and respond to proof requests. They are typically used in applications that allow identity holders to interact with issuers and verifiers. More in-depth documentation about the different Wallet SDKs can be found here ([TypeScript](https://input-output-hk.github.io/atala-prism-wallet-sdk-ts/), [Swift](https://input-output-hk.github.io/atala-prism-wallet-sdk-swift/), [KMM](https://input-output-hk.github.io/atala-prism-wallet-sdk-kmm/)) @@ -56,7 +56,7 @@ To issue and verify VCs to and from DIDs, we need a [Verifiable Data Registry (V ## PRE-REQUISITES ### Agent Deployment -This guide will demonstrate a single-tenant deployment with API Key authentication disabled and an in-memory ledger for published DID storage, which is the simplest configuration to get started as a developer. More advanced configuration options can be found in [Multi-Tenancy Management](/tutorials/multitenancy/tenant-onboarding) and associated [Environment Variables](/docs/atala-prism/prism-cloud-agent/environment-variables) configuration options. +This guide will demonstrate a single-tenant deployment with API Key authentication disabled and an in-memory ledger for published DID storage, which is the simplest configuration to get started as a developer. More advanced configuration options can be found in [Multi-Tenancy Management](/tutorials/multitenancy/tenant-onboarding) and associated [Environment Variables](/docs/atala-prism/prism-cloud-agent/environment-variables) configuration options. We develop on modern machines equipped with either Intel based x64 processors or Apple ARM processors with a minimum of four cores, 16 GB of memory and 128GB+ of SSD-type storage. @@ -70,10 +70,10 @@ git clone https://github.com/hyperledger-labs/open-enterprise-agent ``` -Once cloned, create a new environment variable configuration file named __./open-enterprise-agent/infrastructure/local/.env-issuer__ to define the Issuer Agent with the following content: +Once cloned, create a new environment variable configuration file named __./open-enterprise-agent/infrastructure/local/.env-issuer__ to define the Issuer Agent with the following content: ``` -API_KEY_ENABLED=false +API_KEY_ENABLED=false PRISM_AGENT_VERSION=1.12.0 PRISM_NODE_VERSION=2.2.1 PORT=8000 @@ -81,10 +81,10 @@ NETWORK=prism VAULT_DEV_ROOT_TOKEN_ID=root ``` -Create a new environment variable configuration file named __./open-enterprise-agent/infrastructure/local/.env-verifier__ to define the Verifier Agent with the following content: +Create a new environment variable configuration file named __./open-enterprise-agent/infrastructure/local/.env-verifier__ to define the Verifier Agent with the following content: ``` -API_KEY_ENABLED=false +API_KEY_ENABLED=false PRISM_AGENT_VERSION=1.12.0 PRISM_NODE_VERSION=2.2.1 PORT=9000 @@ -100,7 +100,7 @@ API_KEY_ENABLED disables API Key authentication. This should **not** be used bey ::: -3. Start the `issuer` and `verifier` Cloud Agents by copy paste the below two lines in the command tool. +3. Start the `issuer` and `verifier` Cloud Agents by copy paste the below two lines in the command tool. Issuer Cloud Agent command: ```bash @@ -119,7 +119,7 @@ The Verifier [API endpoint](http://localhost:9000/prism-agent/) will be accessib ### Agent configuration -#### Creating LongForm PrismDID +#### Creating LongForm PrismDID Run the following API request against your Issuer API to create a PRISM DID: ```bash @@ -135,7 +135,7 @@ curl --location \ }, { "id": "issue-1", - "purpose": "assertionMethod" + "purpose": "assertionMethod" } ], "services": [] @@ -226,8 +226,6 @@ curl -X 'POST' \ }' ``` -More in-depth documentation can be found here [PRISM Infrastructure](/docs/category/infrastructure) - ### Starting Sample App All wallet SDK's come bundled with a sample application, that cover all the PRISM flows, including establishing connections, issuance, and verification flows. @@ -245,14 +243,14 @@ Run the following commands: ```bash cd atala-prism-wallet-sdk-ts -npm i +npm i npm run build ``` 2. Start the React demo: ```bash cd demos/browser -npm i +npm i npm run start ``` @@ -317,7 +315,7 @@ MEDIATOR_VERSION=0.10.0 docker-compose up `MEDIATOR_ENDPOINT` is then set to [http://localhost:8080](http://localhost:8080). -More advanced documentation and configuration options can be found [here](https://github.com/input-output-hk/atala-prism-mediator). +More advanced documentation and configuration options can be found [here](https://github.com/input-output-hk/atala-prism-mediator). Now you need to capture the Mediator's Peer DID in order to start DIDCOMM V2 Mediation protocol, you can do so by opening you browser at the mediators endpoint. @@ -393,8 +391,8 @@ The following code examples represent establishing mediation and instantiating t seed.seed ); /** - * This internally will attempt to load an existing mediator from the - * database. If it does not exist it will try to achieve mediation + * This internally will attempt to load an existing mediator from the + * database. If it does not exist it will try to achieve mediation * automatically, by creating a PeerDID and sending a MediationRequest. * After this step the mediator starts capturing messages for the PeerDID we specied. */ @@ -511,7 +509,7 @@ The application will react when the connection gets established correctly and sh -1. Go back to the Application: +1. Go back to the Application: 2. Click the floating button at the bottom right corner of the Contacts tab. 3. On the dialog, paste the invitation URL we generated into the `PrismAgent` connection section and click **Validate**. @@ -583,7 +581,7 @@ curl --location --request POST 'http://localhost:8000/prism-agent/issue-credenti Because this credential Offer was created with the `automaticIssuance` true, as soon as the `PrismAgent` receives this `credentialRequest` it will respond with the `IssuedCredential` message and send this back to the holder. -:::info +:::info automaticIssuance is optional. It can also be manually triggered and confirmed by the Holder.``` @@ -610,7 +608,7 @@ As soon as the CredentialOffer message reaches the Android mobile a
Code examples -The exchange between CredentialOffer and CredentialRequest is demonstrated through more advanced code samples below, showcasing how different platforms handle it. +The exchange between CredentialOffer and CredentialRequest is demonstrated through more advanced code samples below, showcasing how different platforms handle it. @@ -647,7 +645,7 @@ agent message.direction == .received, let msgType = ProtocolTypes(rawValue: message.piuri) else { return } - + Task.detached { [weak self] in do { switch msgType { @@ -733,7 +731,7 @@ agent message.direction == .received, let msgType = ProtocolTypes(rawValue: message.piuri) else { return } - + Task.detached { [weak self] in do { switch msgType { @@ -783,7 +781,7 @@ In the example, we show a verification flow that assumes a connection between Ho To run this section, we will use [the connection](/docs/quick-start#establish-connection-on-the-verifier-agent) we created between the Holder and the Verifier. ```bash -curl --location \ +curl --location \ --request POST 'http://localhost:9000/prism-agent/present-proof/presentations' \ --header 'Content-Type: application/json' \ --data-raw '{ @@ -806,7 +804,7 @@ curl --location \ This API request will return a `presentationRequestId,` which the verifier can use later to check the request's current status. -### Holder: Receives the Presentation proof-request +### Holder: Receives the Presentation proof-request The Holder needs an Edge Agent running with the message listener active. It will receive the presentation proof request from the Verifier Cloud Agent for the correct type of messages as detailed below: @@ -851,7 +849,7 @@ agent message.direction == .received, let msgType = ProtocolTypes(rawValue: message.piuri) else { return } - + Task.detached { [weak self] in do { switch msgType { diff --git a/documentation/docs/sidebars.js b/documentation/docs/sidebars.js index d2675d8b1..a9e519469 100644 --- a/documentation/docs/sidebars.js +++ b/documentation/docs/sidebars.js @@ -69,20 +69,6 @@ const sidebars = { }, 'atala-prism/prism-node', 'atala-prism/prism-mediator', - { - type: 'category', - label: 'Infrastructure', - collapsed: true, - link: { - type: 'generated-index', - title: 'PRISM Infrastructure', - description: 'Learn about the Atala PRISM Infrastructure!' - }, - items: [ - 'atala-prism/infrastructure/hosted-instances', - 'atala-prism/infrastructure/running-agent-locally' - ] - }, 'atala-prism/getting-help' ], },