README.md

What this library does?

This is official iSHARE library which provides core functionality for service consumers. In other words it encapsulates HTTP request calls towards iSHARE endpoints, JWT response validation and mapping business logic.

How do I get started?

First, register iSHARE settings and services to your application.

appsettings.json file should contain the following values at root level:

{
  "SchemeOwnerUrl": "https://scheme.isharetest.net", // production env value should be different
  "Eori": "EU.EORI.NL000000001" // your party's identifier
}

then register default settings and services:

public override void ConfigureServices(IServiceCollection services)
{
    services.RegisterDefaultSettings(Configuration);
    services.AddIShareServices(); // for testing make sure to pass isProduction: false
}

If you prefer to have custom settings instead of our predefined (default), make sure to register your own implementation of IShareSettings before adding iSHARE services.

What API is inside?

IAccessTokenAccessor.GetAsync(...)

Retrieves the access token from cache or makes a HTTP request and caches the access token for request URI. This method is suitable to retrieve access tokens from any iSHARE compliant party. It does not generate client_assertion, so it must be passed as a parameter. For caching IDistributedMemoryCache was used and default Microsoft's implementation of memory cache is registered by invoking services.AddIShareServices() method. However, if in memory cache is not suitable for your party feel free to register your own implementation. To understand how to do that please read Distributed caching in ASP.NET Core.

ICapabilitiesQueryService.GetAsync(...)

Retrieves party's capabilities. This method is suitable to retrieve capabilities from any iSHARE compliant party.

IIdentityProvidersQueryService.GetAsync(...)

Retrieves all identity providers (names and URLs) that exist in iSHARE scheme from Scheme Owner. You will need to append /authorize, /token and /userinfo in order to make requests towards them.

IPartiesQueryService.GetAsync(...)

Retries all parties that exist in iSHARE scheme from Scheme Owner. This method accepts different parameters that allows to filter out parties according to your needs.

ITrustedListQueryService.GetAsync(...)

Retrieves a trusted list of certificate authorities from Scheme Owner.

TokenConvert.DeserializeClaim<T>(...)

Extracts claim from JWT security token and deserializes it to your desired object.

CertificateUtilities.FromPemFormat(...)

Converts input string of PEM certificate into X509Certificate2 object.

CertificateUtilities.FromBase64Der(...)

Converts input string of base64 encoded certificate into X509Certificate2 object.

CertificateUtilities.GetSha256(...)

X509Certificate2 extension method. Gets SHA256 hash of certificate. Scheme Owner's trusted list endpoint returns a list of CAs and their SHA256 hash of certificates, so this method is useful for verification.

IJwtTokenParser.Parse(...)

Parses input string of JWT token into assertion model which is going to be used for validation.

IJwtTokenResponseValidator.IsValidAsync(...)

Validates if token is iSHARE compliant and belongs to the party.

Where can I get it?

First, install NuGet. Then, install iSHARE from the package manager console:

PM> Install-Package iSHARE

Do you have an issue?

First check if you're using the latest version because the issue might have been fixed.

If you have any questions about the usage of library, feel free to browse the existing threads or create your own at our forum.

If you're still running into problems and believe there might be a bug or the library lacks functionality you need, file an issue above.

License, etc.

iSHARE library is Copyright © 2020 iSHARE foundation under the MIT license.