Link Electronic ID to email

Visma Connect can link electronic IDs with email address. Applications that wants this feature can enable it in Developer Portal, and Visma Connect will require users that sign in with electronic ID to link it to an email address.

Some applications might require the user to link e-ID to a specific email address. Visma Connect supports an API lookup feature that will request email address based on e-ID and present this to user for linking.

Contact Visma Connect to set this up.

Sequence diagram

title Link electronic ID and email
 
User->Application: Enter application as\nnot authenticated
Application->Visma Connect: Request authentication\n/connect/authorize
Visma Connect->e-ID Idp: Request authentication
e-ID Idp->e-ID Idp: Authenticates user
e-ID Idp->Visma Connect: User authenticated\nwith e-ID
alt Application require e-ID linked to email and user is not linked to an email
    alt Application has link email lookup enabled
        Visma Connect->Application API: Which email does e-ID have?
        alt Success response
            Application API->Visma Connect: Return email address
            Visma Connect->Visma Connect: Ask user to link e-ID to email address
        else Error response
            Visma Connect->Visma Connect: User have to enter email address to link to e-ID
        end
    else Application does not have lookup enabled
        Visma Connect->Visma Connect: User have to enter email address to link to e-ID
    end
    Visma Connect->Visma Connect: Send email to user to verify\nemail with security code
    Visma Connect->Visma Connect: Link email to NIN
end
Visma Connect->Application: Authentication completed
Application->User: Allow user into application

API implementation

You must implement your applications Link Electronic ID API method in a Public REST API endpoint that supports HTTP POST on the method.

This API must be exposed as a non-interactive API in the Developer Portal that you make Private shared only with the team called Identity (Connect).

For Authorization it must use Visma Connect OAuth 2.0 tokens. See: Visma Connect OAuth 2.0 Bearer Token Authentication

Your API base URI, e.g. https://api.yourapplication.com/v1.0 must be registered in Visma Developer Portal and this is the aud (audience) you must check in OAuth.

The POST endpoint must be exposed as a single method named specifically LinkElectronicIdEmail and be directly hosted under the base URI of your API.

E.g.  if your API base URI is https://api.yourapplication.com/v1.0 then the method must be located at https://api.yourapplication.com/v1.0/LinkElectronicIdEmail.

Request

The bearer token (client_credentials) will contain the following information:

• aud: your APIs base URL

• client_id: connectidp

• scope: <your_api_id>:linkelectronicid → You need to register this scope beforehand in Developer Portal in order for Visma Connect’s backend to be able to integrate with your API.

POST https://api.yourapplication.com/v1.0/LinkElectronicIdEmail

HTTP Headers

• Authorization: Bearer <client_credentials access token>

• Content-Type: application/json

HTTP POST body

{
  "national_identity_number": "12345678",
  "state": "abc123"
}

Response

{
  "email": "user@example.com"
}

You must also in the Visma Developer Portal register an API scope which must be: <resourceid>:linkelectronicid where resourceid is the unique API ID you register in Visma Developer Portal; e.g. it will be named myauthapi:linkelectronicid. Ensure your API checks for presence of this scope in the access token.

After you have setup everything accordingly in Developer Portal, enabling this feature is still a manual process on Connect side.

You need to register a Jira ticket on the CONNECT components and specify 3 things:

1. The API ID → ID of the API that acts as the Link Electronic ID API on which Connect will call the /LinkElectronicIdEmail endpoint

2. The Application ID → the application for which Electronic ID linking should be activated on.

3. The environment where you want this activated (staging or production).

API performance

Be sure you performance test your API to ensure it can take the onboarding volume caused by first-time sign in to your application by each user. If a call takes more than 5 seconds, we will timeout the connection and consider it as an unsuccessful operation.

Note that the electronic ID linking will only take place from your own sign in page registered with Visma Connect, so ensure all your users onboard from there.

E.g. A user signing in from https://connect.visma.com, Visma Home landing page http://home.visma.com or any other Application registered with Connect WILL NOT call your API and other authentication flows will be applied according to that application’s settings.

Registering your API in Visma Developer Portal

Sign into Visma Developer Portal to register your API; then get in touch with the Identity team to have them enable this feature for your Application towards your API.

Give them the "client_id" (Application ID) and "resource_id" (API ID) from the Visma Developer Portal.