Suomi.fi-e-Authorizations – Commissioning e-Authorizations service: Developer’s guide – WebAPI connection

Print Friendly, PDF & Email
 


This document is intended for a software engineer who is about to develop a connection between Service Provider’s digital service and Suomi.fi e-Authorizations WebAPI interface. Interface description document contains all necessary information, but this document has additional information and tips that might be useful.

Developing a connection to this interface should include at least the following sub tasks:

1. Familiarize yourself with WebAPI interface description document.

2. Verify network communication link in customer testing environment.

3. Accessing interface with sample implementation.

4. Accessing interface from program code.

5. Verify code implementation in customer testing environment.

6. Verify network communication link in production environment.

7. Verify code implementation in production environment.

Concepts

Customer organisation  is a owner organization of the Service Provider / Suomi.fi e-Authorizations service utilizer.

Data Exchange Layer, also Suomi.fi Data Exchange Layer, is an alternative method to WebAPI interface for using e-Authorizations. Suitable interface is chosen by the Population Register Centre e-Authorization commissioning team.

Service Provider is a Service channel for end users and it utilizes Suomi.fi e-Authorizations service to check different on behalf authorizations.

e-Authorizations, also Suomi.fi e-Authorizations, is a service for reliable verification of a person’s or organization’s authorization and right to use digital services on behalf of another person or organization regardless of time or place. Registry based checking includes the following registers: National Register of Authorizations, Population Information System (VTJ), Trade Register and The Business Information System (YTJ).

WebAPI-interface is Web based application programming interface for e-Authorizations using OAuth protocol.

Requirements

  • Population Register Centre e-Authorization commissioning project manager has provided to Customer all three necessary interface authorization parameters, which are: WebAPI client ID, API key and OAuth password.
  • Customer has provided redirect URL to Population Register Centre e-Authorization commissioning project manager. URL must use HTTPS protocol.
  • Implementation developer is acquainted with WebAPI interface description document.

Interface description

Suomi.fi Digital Authorizations WebAPI provides a user interface for selecting a principal for end users to act on behalf of and REST query interfaces for backend services for making authorization queries based on end user selections. WebAPI can be accessed through REST / JSON interfaces, protected by API key or OAuth2 + API key authentication.

Working in test environment

Verify network communication link in customer testing environment

It is recommended to verify network communication between Service Provider and e-Authorization service WebAPI interface before developing implementation.

Service address in customer testing environment (integration testing)

Endpoint (rova_host): https://asiointivaltuustarkastus.qa.suomi.fi/

E.g. HPA (acting on behalf of another person)
https://asiointivaltuustarkastus.qa.suomi.fi/service/hpa/user/register/ed4b7ae7/080297-915A?requestId=02fd35dc-99e6-477b-b6e2-03f02cbf3666

Service interface requires that all necessary authorization parameters are populated in the request header. Network communication link can be verified on a very basic level by using internet browser or command line tools to access e.g. address above. Without necessary header parameters request response should be “Http Error 403 Forbidden”.
How to verify network communication link in customer testing environment

How to verify network communication link in customer testing environme

$ wget https://asiointivaltuustarkastus.qa.suomi.fi/service/hpa/user/register/ed4b7ae7/080297-915A?requestId=02fd35dc-99e6-477b-b6e2-03f02cbf3666--2017-03-03 09:53:15-- https://asiointivaltuustarkastus.qa.suomi.fi/service/hpa/user/register/ed4b7ae7/080297-915A?requestId=02fd35dc-99e6-477b-b6e2-03f02cbf3666
Resolving asiointivaltuustarkastus.qa.suomi.fi (asiointivaltuustarkastus.qa.suomi.fi)... 131.207.22.80
Connecting to asiointivaltuustarkastus.qa.suomi.fi (asiointivaltuustarkastus.qa.suomi.fi)|131.207.22.80|:443... connected.
HTTP request sent, awaiting response... 403 Forbidden
2017-03-03 09:53:15 ERROR 403: Forbidden.

If establishing connection is successful, command line tool wget will print out:

131.207.22.80|:443… connected.

For a better response, one must generate request message which includes all necessary authorization parameters. Calculated checksum and there for the whole message is valid only a short period.

Accessing WebAPI interface using sample implementations

Using sample implementations is not necessary but it can help testing and development of the interface connection.

Source code for two different programming language of the sample implementation for accessing WebAPI interface can be found in VRK Github.

  • Node.js: WebAPI Node Client: https://github.com/vrk-kpa/roles-auths-web-api-node-client
  • Java: Roles auths client: https://github.com/vrk-kpa/roles-auths-client

Using Node.js client for testing

WebAPI Node Client is a complete Service Provider client side implementation and it is designed for testing and demo purposes to aid in development. It is not designed for production use and it must be not be used as is in production environment.

1 Install Node.js (version 6.6.0)

2. Download Node Client project from Github

3. Add SSL certificates to project (See below for an example on how to create test certificates)

4. Create config.json file to project root and populate it with authorization parameters received from Population Register Centre e-Authorization commissioning project manager.

5. Run `npm install` and `node WebApiClient.js` on command prompt.

6. Open internet browser and go to address `/register/hpa/[Personal identity code]`. E.g. https://localhost:8904/register/hpa/010180-9026

7. Authorization request sequence will start and it will redirect user to principal selection user interface in e-Authorization service. User is then redirected back to Node Client and the result of the authorization query is printed to the browser window, e.g.:

SSL test certificates for Node Client can be created like this:

openssl req -new > cert.csr
openssl rsa -in privkey.pem -out key.pem
openssl x509 -in cert.csr -out cert.pem -req -signkey key.pem -days 1001
cat key.pem>>cert.pem

Debugging Node.js client

It might be useful to debug Node.js client to better understand the logic.

Starting Node.js client in debug mode can be done like this:

> node --inspect --debug-brk WebApiClient.js
Debugger listening on port 9229.
Warning: This is an experimental feature and could change at any time.
To start debugging, open the following URL in Chrome:
chrome-devtools://devtools/bundled/inspector.html?experiments=true&v8only=true&ws=127.0.0.1:9229/2746fa2b-704a-4a88-acdc-166f60e183d4
Debugger attached.

You will get a url starting with “chrome-devtools://..” to copy/paste into Chrome. After dropping it in, you’ll have all the Chrome DevTools features available. After that you can start authorization sequence like described above.

Accessing WebAPI interface from program code

Acting on behalf of another person (HPA)

Below is a description of the authorization request sequence when accessing HPA interface (acting on behalf of another person). Example lists necessary input and output variables. Additionally, some constants have to be included in request. These are described in detail in interface description document.

1. (GET) Register WebAPI session: {rova_host}/service/hpa/user/register/{client_id}/{hetu}?requestId={requestId}

  • request header: X-AsiointivaltuudetAuthorization (checksum)
  • extract sessionId from response
  • extract userId from response

2. (GET) Redirect user to principal selection user interface on e-Authorization service: {rova_host}/oauth/authorize?client_id={client_id}&response_type=code&redirect_uri={redirect_uri}&user={user}&lang={lang}

  • relay userId as URL paramer user value
  • user us redirected to a URL with parameter code
  • extract authorization_code from response

3. (POST) Exchange authorization_code for access token: {rova_host}/oauth/token?grant_type=authorization_code&redirect_uri={redirect_uri}&code={code}

  • relay authorization_code in URL as parameter code value
  • include HTTP Basic Authorization header
  • extract access_token from response

4. (GET) Get sekected principal or principals: {rova_host}/service/hpa/api/delegate/{sessionId}?requestId={requestId}

  • calculate and include checksum in request header (see below for an example on how to calculate checksum)
  • include header: X-AsiointivaltuudetAuthorization (checksum)
  • relay access_token in request header
  • relay sessionId in request URL
  • extract principal list from response

5. (GET) Send authorization request: {rova_host}/service/hpa/api/authorization/{sessionId}/{personId}?requestId={requestId}&issues={issues}

  • calculate and include checksum in request header (see below for an example on how to calculate checksum)
  • include header: X-AsiointivaltuudetAuthorization (checksum)
  • relay access_token in request header
  • relay sessionId in request URL
  • if authorization request is related to a specific issue or issues, use issues parameter and add issues as URI value. URI is a unique identifier for an issue.
  • extract ALLOWED/DISALLOWED string from response

Sample response:

[{"result":"ALLOWED","reasons":[],"principal":{"personId":"120508A950F","name":"Kumpulainen Anni Emilia"}}]

Authorization request sequence with HPA interface:

Registration (1), delegate (4) and authorization (5) requests are abit different when using YPA interface (person to act on behalf of a company). Check interface description document for details.

Acting on behalf of an organization (YPA)

Below is a description of the authorization request sequence when accessing YPA interface (acting on behalf of an organization). Example lists necessary input and output variables. Additionally, some constants have to be included in request. These are described in detail in interface description document.

1. (GET) Register WebAPI session: {rova_host}/service/ypa/user/register/{service_id}/{hetu}?requestId={requestId}

  • request header: X-AsiointivaltuudetAuthorization (checksum)
  • extract sessionId from response
  • extract userId from response

2. (GET) Redirect user to principal (organization) selection user interface on e-Authorization service: {rova_host}/oauth/authorize&client_id=web-api-client&response_type=code&redirect_uri={redirect_uri}&user={user}&lang={lang}

  • relay userId as URL parameter user value
  • user is redirected to an URL with parameter code
  • extract authorization_code from response

3. (POST) Exchange authorization_code for access_token: {rova_host}/oauth/token?grant_type=authorization_code&redirect_uri={redirect_uri}&code={code}

  • relay authorization_code in URL as parameter code value
  • include HTTP Basic Authorization header
  • extract access_token from response

4. (GET) Getting a list of organizations and roles from the organization the user has selected: {rova_host}/service/ypa/api/organizationRoles/{sessionId}?requestId={requestId}

  • calculate and include checksum in request header (see below for an example on how to calculate checksum)
  • include header: X-AsiointivaltuudetAuthorization (checksum)
  • relay access_token in request header
  • relay sessionId in request URL
  • extract organizationList from the response

Sample response:

[{"name":"Asunto Oy Tampereen Ratinanpuisto","identifier":"2305162-8","complete":true,"roles":["IS"]}]

Calculating checksum

Example with Java code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
protected String getAuthorizationValue(String path) throws IOException {
    String timestamp = ZonedDateTime.now(ZoneOffset.UTC).format(DateTimeFormatter.ISO_DATE_TIME);
    return config.getClientId() + " " + timestamp + " " + hash(path + " " + timestamp, config.getApiKey());
}
private String hash(String data, String key) throws IOException {
    try {
        Mac mac = Mac.getInstance(HMAC_ALGORITHM);
        SecretKeySpec signingKey = new SecretKeySpec(key.getBytes(), HMAC_ALGORITHM);
        mac.init(signingKey);
        byte[] rawHmac = mac.doFinal(data.getBytes());
        String result = new String(Base64.getEncoder().encode(rawHmac));
        return result;
    catch (NoSuchAlgorithmException | InvalidKeyException | IllegalStateException e) {
        throw new IOException("Cannot create hash", e);
    }
}

Complete example:

https://github.com/vrk-kpa/roles-auths-client/blob/master/src/main/java/fi/vm/kapa/rova/client/webapi/impl/AbstractWebApiRiClient.java

Example with Node.js code

1
2
3
4
5
6
7
 function xAuthorizationHeader(path) {
    var timestamp = moment().format();
    var checksum = crypto.createHmac('sha256', CLIENT_SECRET)
        .update(path + ' ' + timestamp)
        .digest('base64');
    return CLIENT_ID + ' ' + timestamp + ' ' + checksum;
}

Complete example:

https://github.com/vrk-kpa/roles-auths-web-api-node-client/blob/master/WebApiClient.js

Verifying checksum calculation

Below is sample calculation of the checksum which can be used to verify that developed function produces correct output. Using the same inputs, you should get the same output as in the example.

Sample checksum input and output:

Path = “/service/hpa/user/register/ed4b7ae7/080297-915A?requestId=02fd35dc-99e6-477b-b6e2-03f02cbf3666”
ClientId = “ed4b7ae7”
ApiKey = “3ba56df8-88b8-4805-9b04-2f8e7a61”
TimeStamp = “2017-02-09T10:29:42.09Z”
__________________
Result:
ed4b7ae7 2017-02-09T10:29:42.09Z z7X+xWtrvth1L7Ql6B/4xZ0iQ1VjToWX4TnHVLo8RGo=

Issue based e-Authorization requests (HPA) – mandate in the National Mandate Register

e-Authorization request can be targeted to a specific mandate (issue or issues) by adding a parameter &issues={issues}.
More: 4.3. Authorization: http://esuomi.fi/palveluntarjoajille/valtuudet/tekninen-aineisto/web-api-rajapinta-ja-valintakayttoliittyma/

It is impossible to know which issue provides DISSALLOWED response if you provide multiple issues as a parameter value. At the moment only solution is to make a requests for each issue if you want to know which issue produces ALLOWED/DISSALLOWED answer.

Basic use case:

1. Person A grants mandate for Person B to act on behalf on a issue C. Mandate is saved in the National mandate register (Production environment: https://valtuusrekisteri.suomi.fi/, Testing environment: https://valtuusrekisteri.qa.suomi.fi/).

2. VRK has set up a Service E for Customer Service D.

3. Service E has been configured to utilize mandate C.

4. Person B signs in to Customer Service D and chooses to act on issue C.

5. Person B is redirected to principal user interface and chooses to act on behalf of person A.

6. Customer Service D system creates authorization request which checks if Person B has the right to act on behalf of person A on issue C.

YPA interface example when National mandate register has a mandate:

Example company with identifier 2036583-2 has created a mandate named “Työperäinen maahanmuutto” for a person. Person signs in and chooses company 2036583-2 from the principal user interface.

Response:

[{"name":"Maanrakennus Ari Eerola T:mi","identifier":"2036583-2","complete":true,"roles":["http://valtuusrekisteri.suomi.fi/tyoperainen_maahanmuutto"]}]

Test and verify implementation during development

Test environment created for you can be used freely during development for testing and to verify that implementation works as it should. Test service is usable also during production to verify possible code changes you might need to implement.

Test service can be used with attached personal and company identification codes

YPA:

Testitapaukset_YPA

HPA:

VTJ_taulukko

Working in production environment

Verify network communication link in production environment

Endpoint (rova_host): https://asiointivaltuustarkastus.suomi.fi/

E.g. HPA regiser request:

https://asiointivaltuustarkastus.suomi.fi/service/hpa/user/register/ed4b7ae7/080297-915A?requestId=02fd35dc-99e6-477b-b6e2-03f02cbf3666

 How to verify network communication link in production environment

$ wget https://asiointivaltuustarkastus.suomi.fi/service/hpa/user/register/ed4b7ae7/080297-915A?requestId=02fd35dc-99e6-477b-b6e2-03f02cbf3666
--2017-03-03 09:55:57-- https://asiointivaltuustarkastus.suomi.fi/service/hpa/user/register/ed4b7ae7/080297-915A?requestId=02fd35dc-99e6-477b-b6e2-03f02cbf3666
Resolving asiointivaltuustarkastus.suomi.fi (asiointivaltuustarkastus.suomi.fi)... 131.207.22.78
Connecting to asiointivaltuustarkastus.suomi.fi (asiointivaltuustarkastus.suomi.fi)|131.207.22.78|:443... connected.
HTTP request sent, awaiting response... 403 Forbidden
2017-03-03 09:55:57 ERROR 403: Forbidden.

If establishing connection is successful, command line tool wget will print out:

131.207.22.78|:443… connected.

Test and verify in production environment

Production environment should not be used for testing but basic operation can be verified by using real personal identity codes as request parameters. Personal identity codes from testing environment will not work in production. Use caution and careful consideration when testing in production environment.

 


 Document history

Version Action Date / Author
 1.0 Document published on eSuomi 20.07.17 / NP