Poort8.Ishare.Core

This .NET library can be used to add iSHARE functionality to your applications. It is used by Poort8 in its applications, undependently reviewed and open sourced under the MPL-2.0 license.

The most common use cases for the use of this package are for Service (Data) Consumers and Service (Data) Providers.

Installation

dotnet add package Poort8.Ishare.Core

An extension method is available to register the services in, for example, a ASP.NET application:

builder.Services.AddIshareCoreServices(builder.Configuration);

Configuration

Add this configuration to the application environment:

• ClientId: Your EORI (for example, EU.EORI.NL000000002).
• SatelliteId: The EORI of the dataspace satellite (for example, EU.EORI.NL000000001).
• SatelliteUrl: URL of the dataspace satellite.
• AuthorizationRegistryId: Optional. EORI of the authorization registry (for example, EU.EORI.NL000000001).
• AuthorizationRegistryUrl: Optional. URL of the authorization registry.

Choose either Azure Key Vault or certificates from configuration.

Azure Key Vault:

• AzureKeyVaultUrl: URL of your Azure Key Vault.
• CertificateName: Name of the certificate stored in Azure Key Vault.

From configuration:

• Certificate: The pfx or p12 certificate file as a base64 encoded string.
• CertificatePassword: The password for your certificate, if applicable.
• CertificateChain: The full chain of your iSHARE certificate, excluding the certificate boundaries, as a comma separated base64 encoded string.
• CertificateChainPassword: The password for your certificate chain, if applicable.

Usage

This section provides a brief overview of how to use the main interfaces in the Poort8.Ishare.Core library. Each example demonstrates a key functionality provided by the interfaces.

Access Token Service

string token = await accessTokenService.GetAccessTokenAtParty("eori", "connectTokenUrl");

Authentication Service

await authenticationService.ValidateClientAssertion("clientAssertion", "clientIdHeader");

await authenticationService.ValidateToken("token", "validIssuer");

Authorization Registry Service

DelegationEvidence evidence = await authorizationRegistryService.GetDelegationEvidence(new DelegationMask());

bool isPermitted = authorizationRegistryService.VerifyDelegationEvidencePermit(
	delegationEvidence,
	"validPolicyIssuer",
	"validAccessSubject",
	"validServiceProvider",
	"validResourceType",
	"validResourceIdentifier",
	"validAction");

bool isPermitted = authorizationRegistryService.VerifyDelegationTokenPermit(
	"delegationToken",
	"validtokenIssuer",
	["validPolicyIssuer"],
	["validAccessSubject"],
	["validServiceProvider"],
	["validResourceType"],
	["validResourceIdentifier"],
	["validAction"]);

Client Assertion Creator

string clientAssertion = clientAssertionCreator.CreateClientAssertion("eori");

var claims = new List<Claim> { new Claim(ClaimTypes.Name, "exampleName") };
string token = clientAssertionCreator.CreateToken("eori", claims);

Satellite Service

PartyInfo partyInfo = await satelliteService.VerifyParty("eori", "certificateThumbprint");

PartyInfo partyInfo = await satelliteService.VerifyPartyWithClientAssertion("eori", "clientAssertion");

IEnumerable<TrustedListAuthority> trustedList = await satelliteService.GetValidTrustedList();

Service Providers

Create an API project with the following endpoints:

Token endpoint

/connect/token: iSHARE docs

In this endpoint await authenticationService.ValidateClientAssertion(request.ClientAssertion, request.ClientId); can be used to validate the client assertion. This method validates the token and does party and certificate checks using the dataspace satellite.

This endpoint should create an opaque access token to the consumer.

Capabilities endpoint

/capabilities: iSHARE docs

Required endpoint which provides service information.

Service (Data) endpoint(s)

/[service]: iSHARE docs

The access token should be validated first, this is not part of this library.

The optional delegation envidence can be validated using bool isPermitted = authorizationRegistryService.VerifyDelegationEvidencePermit(delegationEvidence, "validPolicyIssuer", "validAccessSubject", "validServiceProvider", "validResourceType", "validResourceIdentifier", "validAction");.

Service Consumers

TODO

License

This project is licensed under the MPL-2.0 license - see the LICENSE file for details.