Freja eID Client - Developer's Guide

 

Copyright Statement

The specifications and information regarding the product in this manual are subject to change without prior notice. All statements, information, and recommendations in this manual are believed to be accurate but are presented without warranty of any kind, expressed or implied. Users must take full responsibility for their use of any products.

© 2017-2020 Verisec Freja eID AB. All rights reserved.

Introduction


Thank you for subscribing to Freja eID services.

Freja eID is an electronic identification (eID) solution that citizens and organisations can use for authentication and signing. The essential part of Freja eID service is a smartphone application used for login and signing to all the services that are connected to the user's eID. The second part is a web portal – My Pages – where the user can control how their eID is to be used and has a full record of user history. Freja eID offers three services to Relying Parties: Authentication, Signing and Organisation ID, which are exposed through RESTful APIs.

This document describes the client library - Freja eID Client - that simplifies coding against the Freja ID Relying Party API when it comes to using AuthenticationSignature and Organisation ID Services. Using this library will also make your code more robust, as the library provides error handling, parameter validation and other helpful features.

Our client libraries are written in Java programming language. The intended reader of this document is a Java developer aiming to utilise the Freja eID Client for integrating the Relying Party's back-end system with Freja eID’s mobile service. We, therefore, assume a degree of proficiency in object-oriented programming, as well as developing applications using web services and microservices.

You can find Java source code of our library on GitHub.

Versions

Documentation VersionClient library versionDateComment

2.0

2.0

2020-01-22

Added Initialising Freja eID Client.

1.0

1.0

2019-12-27

This document is a preliminary version. The content of this document is still under review and subject to change.

Get started

Freja eID Relying Party API Client is a client library aimed to ease integration of relying party back-end systems with Freja eID Relying Party API. The API requires JAVA 7 or higher version.

This client library provides a set of classes, interfaces and utility methods designed for accomplishing one of the following use cases:

    • Authentication Service Client
      • initiation of an authentication request
      • fetching a single authentication result based on authentication reference
      • fetching multiple authentication results
      • cancelling authentication request
    • Signature Service Client
      • initiation of a signature request
      • fetching a single signature result based on signature reference
      • fetching multiple signature results
      • cancelling signature request
    • Organisation ID Service Client
      • adding an organisation identifier for a user
      • deleting an organisation identifier for a user
      • fetching result of adding an organisation identifier for a user
      • cancelling adding organisation identifier for a user
    • Custom Identifier Management Client
      • setting a custom identifier for a user
      • deleting a custom identifier

Add Freja eID Client to your build

To add a dependency on Freja eID Client using Maven, use the following:

<dependency>
    <groupId>com.verisec.frejaeid</groupId>
    <artifactId>FrejaEidClient</artifactId>
    <version>2.0.0</version>
</dependency>

Initiate connection to API (test environment)

SslSettings sslSettings = SslSettings.create("/path/to/keystore.jks", "SuperSecretKeystorePassword", "/path/to/server/certificate.crt");

Initiate, monitor and cancel authentication request

Create an authentication client.

AuthenticationClientApi authenticationClient = AuthenticationClient.create(sslSettings, FrejaEnvironment.TEST).build();

Initiate an authentication request.

InitiateAuthenticationRequest request = InitiateAuthenticationRequest.createDefaultWithEmail("email@example.com");
String reference = authenticationClient.initiate(request);

Poll for results of your request.

int maxWaitingTimeInSeconds = 30;
AuthenticationResult result = authenticationClient.pollForResult(AuthenticationResultRequest.create(reference), maxWaitingTimeInSeconds);

Cancel the initiated request.

authenticationClient.cancel(CancelAuthenticationRequest.create(reference));

Initiate, monitor and cancel signature request

Create a signature client.

SignClientApi signClient = SignClient.create(sslSettings, FrejaEnvironment.TEST).build();

Initiate a signature request.

InitiateSignRequest request = InitiateSignRequest.createDefaultWithEmail("email@example.com", "Title", "Text to be signed");
String reference = signClient.initiate(request);

Poll for results of your request.

int maxWaitingTimeInSeconds = 60;
SignResult result = signClient.pollForResult(SignResultRequest.create(reference), maxWaitingTimeInSeconds);

Cancel the initiated request.

signClient.cancel(CancelSignRequest.create(reference));