Freja eID Relying Party API Client (DEPRECATED) - Developer's Guide

 

Table of contents

Clients:

End-of-Life Announcement
Freja eID Relying Party API Client library as described in this document is now deprecated as it has been replaced with a new library called Freja eID Client. The old library will be available for usage until the 30th of June, but as of version 3.9.0 will no longer be maintained. If you have any questions, please contact us at partnersupport@frejaeid.com

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 two services to Relying Parties:  Authentication and Signing, which are   exposed through RESTful APIs.

This document describes the client library - Freja eID Relying Party API Client - that simplifies coding against the Freja ID Relying Party API when it comes to using Authentication and Signature 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 Relying Party API Client for integrating 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.

Versions

Documentation VersionClient library versionDateComment
3.73.9.02019-02-06End-of-Life Announcement for the existing client library. Added links to the new library: Freja eID Client.
3.63.8.02019-01-10
  1. Added INFERRED UserInfoType
  2. Added EMAIL_ADDRESS as AttributeToReturn and user's email address is returned as part of RequestedAttributes
3.53.5.22018-11-20
  1. Added support for EXTENDED registration state.
  2. HTTP requests sent to the Freja eID service are complemented with the User-Agent header whose value contains:
    • library version
    • Java version
  3. Updated URL address of Freja eID REST service. Instead of https://auth.prod.frejaeid.com authentication requests are directed to https://services.test.frejaeid.com (although it still works, the old address is to be abandoned in the future.)
  4. MOBILE_NOTIFIED status of login or sign transaction is marked as deprecated. Status DELIVERED_TO_MOBILE shall be used instead.
  5. AttributeToReturn class is extended with constants for easier creation of attributes to return set (e.g. AttributeToReturn.DATE_OF_BIRTH_ATTR, AttributeToReturn.SSN_ATTR etc.)
3.43.4.02018-09-10Added option to request RELYING_PARTY_USER_ID and DATE_OF_BIRTH in attributesToReturn
3.33.3.02018-08-30Added support for HTTPS proxy host and port using JVM proxy arguments.
3.23.2.02018-07-17

Added support for usage of PHONE as UserInfoType

3.13.1.02018-06-15Added Cancel Login and Cancel Sign methods. Adjusted Authentication Services API Client to support more user attributes which can be returned with authentication results.
Added Integrator Relying Party Management API Client.
3.0

3.0.0, 3.0.1, 3.0.2

2018-03-05

Adjusted Authentication Services API Client and Signature Services API Client. Removed EmailLoginClient and SsnLoginClient. Included Custom Identifier Management.
Resolved bug causing default SSLContext to be overriden.

2.0

2.0

2018-02-14

Added Signature Services API Client to the library. Adjusted examples for SSL initialisation in Authentication Services API Client.

1.0

1.0

2017-12-22

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:

Logging

Freja eID Relying Party API Client provides a logger you can include in your application. Once included, this logger will record all requests sent to Freja eID Relying Party API and the responses received from it. The root logger of the library is named ''com.verisec.frejaeid''.This client library uses slf4j library/facade. You may configure it with any of the popular Java logging frameworks, such as log4j, logback, JULI, etc. In case you are using log4j, below is an example of a simple log4j descriptor (log4j.xml configuration descriptor needs to be in the root of the classpath). With the given configuration, all logs end up in a console with the level TRACE.


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
   
    <appender name="console" class="org.apache.log4j.ConsoleAppender">
        <param name="Target" value="System.out"/>
        <layout class="org.apache.log4j.EnhancedPatternLayout">
           <param
             name="ConversionPattern"
             value="%d{ISO8601}{GMT+0} UTC %-5p %c{1} - [id=%X{id} user=%X{user} IP=%X{IP}] %m%n"
           />
        </layout>
    </appender>
 
    <logger name="com.verisec.frejaeid">
        <appender-ref ref="console"/>
    </logger>
     
    <root>
        <priority value="trace"></priority>
    </root>
</log4j:configuration>