didx.aries-cloudapi-dotnet-aspcore 1.2.7

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"

  }
}

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

"AriesCloudAPI": {
    "BaseUri": "http://localhost:8000",
    "OrganizationId": "your assigned aries cloud organization id",
    "GovernanceAdmin": {
      "ClientId": "{OAuthClientId}",
      "ClientSecret": "{OAuthClientSecret}"
    },
    "TenantAdmin": {
      "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.

• OrganizationId is your assigned organizationId in Aries Cloud API and is used for multi-tenancy segregation. This would be supplied to you for remote installations. Optional for localhost.

• TenantAdmin and/or GovernanceAdmin - the OAuth settings for the TenantAdmin 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 v2.

• 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.

• TenantTokenCacheType specifies the type of caching mechanism for tenant tokens. When set to a non-null value, tenant tokens will be cached using the specified caching strategy (MemoryCache or Redis). Tokens stored in the cache will be automatically rotated based on the specified rotation interval. This option helps in managing the lifecycle of tenant tokens efficiently, reducing the need for frequent token requests. If set to null, tenant token caching and rotation are disabled.

  Important: If you select MemoryCache or Redis as the caching mechanism, you must add and configure the corresponding service in your application during startup:

  • For MemoryCache, ensure that IMemoryCache is registered in your service collection.
  • For Redis, ensure that IConnectionMultiplexer is configured and registered in your service collection.

  The SDK will automatically check for the presence of either IMemoryCache or a configured IConnectionMultiplexer to manage tenant token caching appropriately.

• TenantTokenCacheRotationIntervalDays Defines the interval, in days, after which tenant tokens should be rotated (i.e., refreshed). This setting is applicable only if tenant token caching is enabled. It specifies how often the tokens are renewed in the cache, ensuring that tokens remain valid and secure.

• TenantTokenCacheEncryptionType specifies the type of encryption used for tenant tokens stored in the Redis cache. This setting ensures that sensitive data remains secure while being cached.

  Options:

  • DataProtection: Requires IDataProtectionProvider in the service collection.
  • Custom: Requires TenantTokenCacheEncryptionKey to be specified.
  • Null: No encryption is applied.

  Important: This setting applies only to Redis. The SDK will gracefully handle encryption configuration changes by discarding any failed decryption tokens, fetching new ones, encrypting them (if enabled), and caching them.

• TenantTokenCacheEncryptionKey specifies the encryption key used when TenantTokenCacheEncryptionType is set to Custom. This key must be a 32-byte key, Base64 encoded, to ensure secure encryption of tenant tokens.

  Example: To generate a 32-byte encryption key, you can use the following command:

  openssl rand -base64 32
  
  

Startup

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

        public IConfiguration Configuration { get; }

        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public void ConfigureServices(IServiceCollection services)
        {
            ...

            services.AddAriesCloudAPI(Configuration);
        }

        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.

• CreateTenantAdminClient()

  Creates a client under the context of the 'tenant-admin' role as defined in Aries Cloud API. See ITenantAdminClient.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.

• CreateTenantAdminWebSocketClient(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.

• CreateTenantAdminSSEClientSingleEvent(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.

• CreateTenantAdminSSEClientStream(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.GetIndyCredentialsAsync();

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