Findy Agency related documentation to get started with the development.
Note: This documentation does not intend to teach readers theoretical background or other aspects of SSI technology. We expect readers to be familiar with basic concepts of SSI. For self-studying SSI and the technology, we recommend excellent material crafed by other authors:
Findy Agency provides a Hyperledger Aries compatible identity agent service. It includes a web wallet for individuals and an API for organizations to utilize functionality related to verified data exchange: issuing, holding, verifying, and proving credentials. The agents hosted by the agency operate using DIDComm messaging and Hyperledger Aries protocols. Thus it is interoperable with other Hyperledger Aries compatible agents. The supported verified credential format is currently Hyperledger Indy “Anoncreds” that work with Hyperledger Indy distributed ledger.
You should check out Findy Agency if
you are looking for a fully open-sourced, performant Aries compatible identity agency that you can easily run in your local computer
you are a web service developer planning to use verified data in your application
you would like to build or use a web wallet for individuals instead of mobile application in your use case
you want to do experiments quickly without the need to setup or join actual Indy ledger
you have experimental attitude and are interested how things can be done differently
However…
There are other great solutions you should definitely check out if
you expect to find ready-made product with full support and complete documentation
you are not interested in running your own agency
you are busy to get to production and would rather buy services than craft it yourself.
The backend server of Findy Agency consists of three services:
core/findy-agent that handles all agent functionality including credential handling and Aries protocols
vault/findy-agent-vault that maintains a database of agents’ data. Currently vault has only GraphQL-interface for data queries, that is intended mainly for browser web wallet use.
auth/findy-agent-auth that registers and authenticates all agency users.
Reference web wallet implementation is a React app that utilizes standard WebAuthn protocol and browser capabilities to authenticate to backend. Web wallet uses GraphQL to fetch and update agency data.
Wallet login screen.
Service agents are applications that handle verified data on behalf of organizations.
Service agents utilize Findy Agency through headless authentication and
gRPC API. Samples and reference implementations
can be found in agency gRPC helper libraries for go,
Typescript or
Kotlin.
Agents can be also operated through a CLI, findy-agent-cli, that provides most of the functionality needed for agent and agency manipulation.
2 - Getting Started
Getting started with Findy Agency
2.1 - First Steps with Findy Agency
Instructions how get started with Findy Agency.
Full Agency Setup
Agency services can be setup easily locally using Docker.
Check further instructions here.
The instructions describe how to launch all the needed backend services in Docker containers
together with a simulated ledger. There is also a native development setup instructions
for web wallet application which will be needed in order to run web wallet application together
with other agents.
Once you have the services running on your computer,
Findy agent cli tool
Usage:
findy-agent-cli [command]Available Commands:
agency Manage Agency
agent Work with the Cloud Agent
authn WebAuthn commands
bot Manage Bot
completion Generate shell completion scripts
connection Manage connections
help Help about any command new-key Create a new key for the authenticator
tree Prints the findy-agent-cli command structure
Flags:
--config string configuration file, FCLI_CONFIG
-n, --dry-run perform a trial run with no changes made, FCLI_DRY_RUN
-h, --help helpfor findy-agent-cli
--logging string logging startup arguments, FCLI_LOGGING (default "-logtostderr=true -v=0") --server string gRPC server addr:port, FCLI_SERVER (default "localhost:50051") --tls-path string TLS cert path, FCLI_TLS_PATH
-v, --version version for findy-agent-cli
Use "findy-agent-cli [command] --help"for more information about a command.
Check out the dedicated guide for CLI commands to get familiar with the usage.
Note:
before CLI usage, you need to have a working Findy Agency installation
findy-agent-cli is also a reference on how to use the Agency gRPC API with golang. Check the sources for more details.
before UI-tool usage, you need to have a working Findy Agency installation
findy-issuer-tool works also as a sample implementation for a Findy Agency service agent implemented with JavaScript.
2.2 - Service Agents
Instructions how to get started with service agents.
Service agents i.e. organization agents utilize Findy Agency through its gRPC API.
The agent creation and authentication is handled through the headless authenticator, acator,
that implements the FIDO2 protocol. Once authenticated, all agent functionality is available
to service agents via the core gRPC API, findy-agent-api.
Read more about getting started with service agents from the blog:
Service Agent onboarding and connecting to another agent by creating a connection invitation.
Service Agent (SA) registers with acator tool/library to agency. SA should use a unique user name and the selected authenticator key should be kept secret. Note: the registration needs to be done only once. After the first registration, authentication is done using the same user name and authenticator key.
SA does login with acator tool/library. After successful login, a JWT token is returned to SA.
SA starts listening to agent status events with gRPC API.
SA creates connection invitation using gRPC API.
SA displays/sends/etc. invitation json to another Aries compatible agent (invitee).
Invitee sends connection request to the core agency, that handles the connection protocol on behalf of SA.
Core agency notifies SA when the connection is established. SA can query core agency for the needed connection details and continue with e.g. issuing or verifying data with the new connection.
3 - Agency Deployment
Instructions how to deploy Agency.
The documentation present an overview of Agency deployment architecture and configuration.
Nginx, AWS load balancer etc. can work as a reverse proxy. It is recommended to use single domain for request routing to avoid hassle with FIDO2 origin requirements and CORS.
Port 443
Path
Target
Note
/
pwa
Static html
/query
vault
GQL queries from PWA. Websocket support needed.
/register, /login
auth
Webauthn requires HTTPS. Domain needs to match with PWA.
/a2a
agency
Endpoint can be set with the agency’s start up flag.
Port 50051
Agency gRPC interface communication.
Note: Currently also all internal microservices assume gRPC SSL/TLS communication. Unencrypted communication should be enabled within private network in the future.
findy-agent
Sources and more documentation in repository findy-agent
*Cert path is the root. Both server and client certificates needs be in this folder in their own separated folders named accordingly: server and client.
Configuration files
Steward wallet
Genesis transactions
gRPC client certificate + key (if TLS termination not handled by reverse proxy)
gRPC server certificate + key (if TLS termination not handled by reverse proxy)
Data storage (file system)
Handshake register (has backup capability): Text file (JSON) for onboarded agent ids
PSM database: Bolt db for protocol state machine data
Enclave (has backup capability): Bolt db for wallet key data
Indy wallets (has backup capability): SQLite db for wallet data
in backup recovery wallet must be imported to system with indy SDK API call
Findy Agency is an identity agent service for individuals and organisations.
–
It provides functionality and APIs to identity holders for utilizing verified data networks.
–
Verified data exchange is based on asymmetric cryptography and Decentralized Public Key Infrastructure (DPKI).
???
Findy development team at OP Lab has been researching self-sovereign identity and verified data networks for almost three years now.
Findy Agency project has been born as a side product of the research work, multiple PoCs, and demos around this technology.
The project codes were published fully as open-source in summer 2021.
Identity Wallet
–
Credentials, i.e., facts signed by different issuers, are stored in digital wallets.
–
Using their digital wallet, identity holders can cryptographically prove that the credential data is valid and that they, in fact, own the credential.
–
Proofs are zero-knowledge and support selective disclosure.
???
Identity holder can be any entity that needs to prove facts about themselves. For example, an individual, an organization or an IoT device can be an identity holder.
Zero-knowledge methods allow keeping the issuer signature and parts of the signed message secret. Thus it is possible to:
Prove that the attribute exists in the credential, but do not reveal its value.
Reveal the value of an attribute without revealing any other attributes.
Findy Agency provides the digital wallet service together with needed communication capabilities to identity holders.
layout: false
Verified Data
.img-fill[]
???
The idea of verified data networks is to utilize cryptography so that different identities can hold and prove facts about themselves digitally.
The main concepts in verified data handling are
Issuing credentials: signing facts and storing those in one’s digital wallet
Prooving credentials: generating proofs from the signed facts and presenting those to counterparties
A public permissioned blockchain stores the shared data, such as the public keys of the credential issuers. Each network has a set of rules, how this data is maintained and updated.
In Finland, we have a joint public-private effort, the Findy cooperative, aiming to run the national Findy network and to maintain the verifiable data registry in the future.
Many countries have similar initiatives, such as Germany, Spain and, Canada. EU is also steering legislation in the direction of identity wallets.
template: network
Trust Layer on top of Internet
–
Founded on trust and security
–
Increased privacy
–
Decoupled services
–
The next step of digitalization
???
Verified data networks make the internet a more secure place.
Privacy increases as end-users become the owners of their own data, and they may select which data they want to share.
The need for custom integrations between organizations decreases as they can handle the needed data exchange through the network.
User and his digital wallet becomes the integration point between services.
The use of verified data networks will enable the digitalization of use cases traditionally cumbersome to implement. It will also allow entirely new use cases.
The technology is new and it is evolving rapidly. Some of these tools have likely been replaced when first use cases start in production.
DIDComm-messaging is the foundation of all verified data communication. The DIDComm-connection is a secure messaging channel created by exchanging DIDs (identifiers for decentralized, digital identity).
Indy-sdk provides the needed cryptographic functionality. It supports the Indy “AnonCreds” credential format.
Digital identities are rooted in Hyperledger Indy blockchain, which works together with the indy-sdk-tools.
Hyperledger Aries defines the protocol by how identity agents communicate with each other.
class: middle
Used Technologies
.img-fill[]
???
Each identity holder owns an agent that can handle the credentials and the needed communication with other agents.
Depending on the implementation approach, agent functionality can be included in the service as a framework, or agent/agency can run as a separate service.
Findy Agency is a multitenant service, i.e., a single installation can host multiple identity agents.
At the time Findy Agency development was started, there were no open-source alternatives to choose from. Nowadays, the situation is better, and there are multiple open source frameworks and agencies that support the Aries protocol.
class: img-fill middle center
Architecture Overview
???
Multitenant agency serving both individuals and organizations
Exceptional cloud-first approach: credential data is stored and handled only in the server-side
Secure passwordless authentication via WebAuthn
GraphQL for browser, gRPC for API clients
Performant microservice architecture implemented with GoLang and gRPC
Contanerized microservice images are built with GitHub Actions
Initially the technology was implemented by crypto-specialists coming from the academic world, and most of the examples were written in Python. As software professionals we knew that building an agency for this purpose would need more performant tools.
We thought that Go was the best choice of modern languages when the target is to make network intensive microservices.
Our approach using Go is pragmatic. We are not “Go-purists”.
Test 1: Findy Agency based issuer/verifier with Lissi Wallet
A Findy Agency utilizing issuer tool invites Lissi Wallet to form a pairwise connection. Issuer tool sends and verifies a credential with Lissi Wallet.
Test 2: Findy Agency Web Wallet with Trinsic Wallet
Findy Agency Web Wallet user forms a pairwise connection with Trinsic Wallet user. Wallet applications send Aries basic messages to each other.
Test 3: ACA-Py based issuer/verifier with Findy Agency Web Wallet
Aries Test Harness runs ACA-Py-based agents that issue and verify credentials with Findy Agency Web Wallet.
7.9 - SSI-Empowered Identity Provider
Demo of SSI-Empowered OIDC Identity Provider
Open ID Connect (OIDC) is a popular identity protocol for authenticating users and providing identity
data for access control. It allows web services to externalize the authentication of end-users by
securely signing users in using a third-party identity provider. Findy Agency team has experimented
with integrating SSI (self-sovereign identity) agent capabilities to a sample OIDC provider,
thus enabling verified data usage in the login flow. The proof-of-concept shows that this approach
would allow numerous web applications to switch to SSI-based login with minimal changes.
A shortcut for SSI adoption
is to use existing APIs when issuing credentials and build so-called self-service issuers.
In this demo, we showcase how to implement a service for issuing credentials
for Finnish Trust Network data.
]
]
]
.center.small[
]
