.NET

Installation

Install the ITSME® NuGet package to your project to get started.

$ dotnet add <myproject> itsme

Import the ITSME® project into your code.

$ using Itsme

Configuration

Initialize the ITSME® client with your configuration. Replace my_private_jwks.json with your actual key file by reading the content or adding it as a string.

var jwks = File.ReadAllText("jwks_private.json");
var settings = new ItsmeSettings();
settings.ClientId = "my_client_id";
settings.RedirectUri = "https://i/redirect";
settings.PrivateJwkSet = jwks;
var itsmeClient = new Client(settings);

Crafting an ITSME® redirect URL:

var urlConfig = new UrlConfiguration();
urlConfig.Scopes = new string[] { "email", "profile" };
urlConfig.ServiceCode = "my_service_code";
urlConfig.RequestUri = "";
var url = itsmeClient.GetAuthenticationURL(urlConfig);

Once generated, you can use this to redirect to itsme. After succesful authentication by the user, ITSME® will redirect to your configured backend url with an authorization code.

Using the different ITSME® services

To change the service you want to use (login, approval, share), you need to add the corresponding service code as provided by ITSME® during the onboarding of your integration.

Specific to the approval service, you need to add the request uri parameter while setting up the redirect URL so that ITSME® knows what to ask the user. The actual data which needs to be found when ITSME calls your provided endpoint is based on the following sample JSON object:

{
    "aud": "https://merchant.itsme.be/oidc/authorization",
    "scope": "openid service:my_service_code profile email",
    "redirect_uri": "https://i/redirect",
    "response_type":"code",
    "client_id":"my_client_id",
    "acr_values":"tag:sixdots.be,2016-06:acr_advanced",
    "iss":"my_client_id",
    "nonce":"a_valid_nonce",
    "state":"a_valid_state",
    "claims":{
        "userinfo":{
            "tag:sixdots.be,2016-06:claim_eid":null,
            "tag:sixdots.be,2016-06:claim_city_of_birth":null,
            "sub":{ "value":"the_end_user_already_known_user_code" },
            "tag:sixdots.be,2016-08:claim_approval_template_name":{ "essential": true, "value": "free_text" },
            "tag:sixdots.be,2016-08:claim_approval_text_key": { "essential": true, "value": "This text will be shown to the user in the ISTME® app" }
        }
    }
}

The templates you can use in the tag:sixdots.be,2016-08:claim_approval_template_name are the following:

• free_text

If you want to provide some more information to the user about the approval request, you can provide this using the tag:sixdots.be,2016-08:claim_approval_text_key claim. The text can be HTML formatted as the ISTME® app can handle and display that to some extend (bold, italic, break lines).

Exchanging the authorization_code

var user = itsmeClient.GetUserDetails("authorization_code");

The returned user contains all the information requested by you. Make sure to only use the sub identifier to link or reference an ITSME® user from your data as all other parameters can be subject to change.

As an extra means of flexibility, allow the update of the sub identifier for existing users as well. Due to security reasons, it can happen existing users are migrated to a new identifier, so for logged in users allow to update their ITSME® linked account.