didx.aries-cloudapi-dotnet-aspcore 1.0.1

didx-aries-cloudapi-dotnet

This repository contains the core functionality needed to implement Self-Sovereign Identity (SSI) flows in .NET applications using the DIDx Aries Cloud API.

SSI Flows

See the DIDx Aries Cloud API Documentation for more information on the SSI flows.

The following SSI flows are supported by the .NET SDK:

Connection Invitations (CI)

Out-of-band (OOB)

Install

Package source

nuget.org (https://api.nuget.org/v3/index.json)

Install package

Install-Package didx.aries-cloudapi-dotnet-aspcore

Configuration

Add the following configuration to your appsettings.json

This is the minimal configuration for a localhost installation:

{
  ...
  "AriesCloudAPI": {
    "BaseUri": "http://localhost:8000",
    "GroupId": "your assigned aries cloud group id",
  }
}

For production/remote installations, the OAuth settings are required for either the Customer or GovernanceAdmin roles (see clients below).

"AriesCloudAPI": {
    "BaseUri": "http://localhost:8000",
    "GroupId": "your assigned aries cloud group id",
    "GovernanceAdmin": {
      "ClientId": "{OAuthClientId}",
      "ClientSecret": "{OAuthClientSecret}"
    },
    "Customer": {
      "ClientId": "{OAuthClientId}",
      "ClientSecret": "{OAuthClientSecret}"
    }
  }

Here are the available options:

• BaseUri is the url of the Aries Cloud API. This can be localhost or a remote installation. Required.

• GroupId is your assigned groupId in Aries Cloud API and is used for multi-tenancy segregation. This would be supplied to you for remote installations. Required.

• Customer and/or GovernanceAdmin - the OAuth settings for the Customer and/or GovernanceAdmin roles as defined in Aries Cloud API. Optional for localhost. Required for production/remote urls.

• {OAuthClientId} & {OAuthClientSecret} are the OAuth configuration. This would be supplied to you for remote installation.

• ProtocolVersion the hand-shake protocol to use i.e. v1 or v2. Default is v1.

• SSETimeoutInSeconds SSE connection timeout in seconds. Default is 120.

• DebugOutput is a boolean value that determines whether the SDK will output debug information to the console. This is useful for debugging purposes. Optional. Not recommended for production environments.

Startup

Add the following to your application startup (Startup.cs):

        public void ConfigureServices(IServiceCollection services)
        {
            ...

            services.AddAriesCloudAPI();
        }


        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            ...

            app.ApplicationServices.UseAriesCloudAPI();
        }

Usage

To use the Aries Cloud API, a client-proxy must first be created via the ClientFactory class.

This is supplied by the Dependency Injection in .NET and provides the following methods to create clients for the respective contexts:

• CreatePublicClient()

  Creates a client for anonymous or public access to the Trust Registry. See IPublicClient.cs for available operations.

• CreateGovernanceClient()

  Creates a client under the context of the 'governance' role as defined in Aries Cloud API. See IGovernanceClient.cs for available operations.

• CreateCustomerClient()

  Creates a client under the context of the 'tenant-admin' role as defined in Aries Cloud API. See ICustomerClient.cs for available operations.

• CreateTenantClient(string tenantId)

  Creates a client under the context of the 'tenant' role as defined in Aries Cloud API. An access-token will automatically be obtained for the specified tenantId. See ITenantClient.cs for available operations.

• CreateTenantClientWithAccessToken(string access_token)

  Creates a client under the context of the 'tenant' role as defined in Aries Cloud API. The specified access-token will be used to authenticate the client. See ITenantClient.cs for available operations.

• CreateCustomerWebSocketClient(Topic[] topics, string? tenantId, CancellationToken cancellationToken)

  Creates an open websocket client under the context of the 'tenant-admin' role as defined in Aries Cloud API. It automatically issues the subscribe request and returns a connected client ready for use. See ClientWebSocket for more info.

• CreateCustomerSSEClientSingleEvent(string tenantId, Topic topic, string desiredState, string? fieldName = null, string? fieldValue = null)

  Returns an open Stream to receive Server-Side Events (SSE). The stream will close after the first event is received.

• CreateCustomerSSEClientStream(string tenantId, Topic? topic = null, string? fieldName = null, string? fieldValue = null)

  Returns an open Stream to receive Server-Side Events (SSE). The stream will remain open for the duration of the connection.

Example:

    public class ValuesController : ControllerBase
    {
        private ClientFactory _clientFactory;

        public ValuesController(ClientFactory clientFactory)
        {
            _clientFactory = clientFactory;
        }

        [HttpGet]
        public async Task<IEnumerable<string>> GetAsync()
        {
            // create client
            var client = _clientFactory.CreateGovernanceClient();

            // example usage
            var credentials = await client.GetCredentialsAsync();

            return credentials?.Select(x => x.ToString());
        }
    }

• See Aries.CloudAPI.DotnetSDK.AspCore.IntegrationTests for more examples.

• See the Blazor Sample for more examples.

Blazor Sample

The Blazor Sample project is an example implementation of the above SSI flows.

It supports OAuth PKCE Authorization Code Flow (with Cookies) and was created from the following template: https://github.com/damienbod/Blazor.BFF.OpenIDConnect.Template

High-level architecture

Storage

To implement an end-to-end example, the client application needs to persist some state. For example, a Connection Invitation which needs to "delivered" to the recipient. For the purposes of this sample, SQLLite is used as a database provider. The following state is stored for caching & delivery purposes:

• Tenant info & access tokens
• Invitations
• Webhook events
• Governance Schemas

Webhook Events

There are two options available to receive the webhook events i.e. Websockets & Server-Side Events (SSE). This can be configured in the Blazor Sample App Settings.

For example:

"BlazorSample": {
  "WebhookEventStreamType": "SSE" // or "WebSockets"
},

Server-Side Events (SSE) is recommended for production systems.

SignalR

SignalR is used to delivery webhook events to the client in real-time. These SignalR connections are cached in-memory and is not persisted in the database. This is not recommended for production systems.