Signature Services Client

Overview

The Freja eID Signature Service allows you to securely deliver messages to users, and to prompt them to digitally sign data and documents. There are two important differences between transactions in the Authentication and Signature services.

Authentication transactions:

Only one transaction may be pending at any given time
They have a duration of up to 2 minutes

Signature transactions:

Multiple transactions may be pending simultaneously
They have a duration of up to 30 days (for transactions with INFERRED user info type maximum is 30 minutes)

For more detailed information about the Signature Service, please refer to our REST API Documentation.

Calling the Service

This section describes how to make calls to the Freja eID Signature Service API and process the response.

Initiate Sign

The Signature Service is able to send signature requests to users both when:

the user initiated an action in your system themselves
you wish to send a signature request to user(s) regardless of whether they are doing something in your system at the time

Signature requests have configurable longevity. From the moment that a user receives the signature request, they have between 2 minutes and 30 days to sign the request (for transactions with INFERRED user info type maximum is 30 minutes).

For Integrators/Integrator Relying Parties

Relying Parties which are Integrators must set relyingPartyId per request and that can be done only with a custom request. Read more about how Integrator and Integrated Relying Parties can integrate with Freja here.


/*
* Initiate sign request can be created with EMAIL and TITLE and TEXT to be signed.
* Change the values to match your setup.
*/

String email = "joe.black@verisec.com";
String title = "Title";
String text = "This text will be signed.";
InitiateSignRequest initiateSignRequest = 
    InitiateSignRequest.createDefaultWithEmail(EMAIL, title, text);
 
/*
* Initiate sign request can be created with SSN and TITLE and TEXT to be signed.
* Change the values to match your setup.
*/

String title = "Title";
String text = "This text will be signed.";
SsnUserInfo ssn = SsnUserInfo.create(Country.SWEDEN, "123456789001");
InitiateSignRequest initiateSignRequest = 
    InitiateSignRequest.createDefaultWithSsn(ssn, title, text);
 
/*
* In case of Initiate sign method, response type is String.
* The data in this response is the signature transaction reference.
*/

String transactionReference = signClient.initiate(initSignRequest);

/*
* Beside simple text that will be shown in the mobile application and
* signed by the end user, data to sign can be extended with binary data.
* This data is included in the signature but is not visible to the user.
* Create DataToSign object and set it by using the custom request builder.
*/

String dataToSignText = "Would you like to transfer 1000 EUR from account A to account B?”;
byte[] dataToSignBinaryData = "Binary data, not presented to the user.".getBytes(StandardCharsets.UTF_8);
DataToSign dataToSign = DataToSign.create(dataToSignText, binaryData);
 
/*
* Beside simple json signature that can sign text or binary data,
* advanced signature is supported for text.
*/

String dataToSignText = "Would you like to transfer 1000 EUR from account A to account B?”;
DataToSign dataToSign = DataToSign.create(dataToSignText, null);
String email = "joe.black@verisec.com";
InitiateSignRequest initSignRequest = 
    InitiateSignRequest.createCustom()
                       .setEmail(email)
                       .setDataToSign(dataToSign, SignatureType.XML_MINAMEDDELANDEN)
                       .build();
 
/*
* Initiate sign request can be created with phone number 
* by using the custom request builder.
* Change the phone number value ("+467123456789" in the example) 
* to match your setup. 
*/

String phoneNum = "+467123456789";
InitiateSignRequest initSignRequest = 
    InitiateSignRequest.createCustom()
                       .setPhoneNumber(phoneNum)
                       .setDataToSign(dataToSign)
                       .build();

/*
* Initiate sign request can be created as INFERRED
* by using the custom request builder.
* Inferred transactions are not bound to a specific user upon initiation, 
* they are bound to a user when a QR-code is scanned. That is, the first user that
* scans the QR-code of a pending inferred transaction gets bound to it. 
* As such you need to be aware of the privacy of the signature content: 
* if a signature content is sensitive and intended for a specific recipient 
* we strongly advise you to use one of the binding forms of the signature API.
*/

InitiateSignRequest initiateSignRequest = InitiateSignRequest.createCustom()
                    .setInferred()
                    .setDataToSign(dataToSign)
                    .build();

/*
* Parameter minRegistrationLevel, optional, describes the
* minimum required registration level of a user in order to
* approve/decline signing transaction. If not present, default level will be PLUS.
*/

RegistrationState minRegistrationLevel = 
    RegistrationState.EXTENDED;
  
/*
* Parameter title, optional, describes the title to display in the transaction
* if presented to the user on the mobile device. 
* The title will be presented regardless of the
* confidentiality setting. If not present, a default text 
* "Confirm action" will be presented.
*/

String title = "Transaction title";
 
/*
* Parameters pushNotificationTitle and pushNotificationText, optional, describe
* the title and the text of the notification sent to the mobile
* device to alert the user of a signature request.
* If not present, a default title 
* "Sign" and text "You have an action to sign in Freja eID"
* will be presented.
*/

String pushNotificationTitle = "Sign notification title";
String pushNotificationText = "Sign notification text";
PushNotification pushNotification = 
    PushNotification.create(pushNotificationTitle, pushNotificationText);
 
/*
* Parameter expiry, optional, describes the time until which the Relying Party
* is ready to wait for the user to confirm the signature request.
* Expressed in milliseconds since January 1, 1970, 00:00 UTC.
* Min value is current time +2 minutes, max value is current
* time +30 days. If not present, defaults to current time +2 minutes.
*/

Long expiry = Instant.now().plus(3,ChronoUnit.MINUTES).getEpochSecond() * 1000;
 
/*
* Parameter attributesToReturn is used to request additional information about the user.
* Interpreted as a set of attributes that represent that extra information is required.
* The requested information is returned when fetching signature results.
*/

AttributeToReturn[] attributes = {AttributeToReturn.BASIC_USER_INFO,
                                  AttributeToReturn.EMAIL_ADDRESS,
                                  AttributeToReturn.ALL_EMAIL_ADDRESSES,
                                  AttributeToReturn.ALL_PHONE_NUMBERS,
                                  AttributeToReturn.DATE_OF_BIRTH,
                                  AttributeToReturn.AGE,
                                  AttributeToReturn.PHOTO,
                                  AttributeToReturn.ADDRESSES,
                                  AttributeToReturn.SSN,
                                  AttributeToReturn.DOCUMENT,
                                  AttributeToReturn.DOCUMENT_PHOTO,
                                  AttributeToReturn.RELYING_PARTY_USER_ID,
                                  AttributeToReturn.CUSTOM_IDENTIFIER,
                                  AttributeToReturn.REGISTRATION_LEVEL,
                                  AttributeToReturn.COVID_CERTIFICATES
};

/*
* For the custom initiate sign request with all parameters, see the example below.
*/

String email = "joe.black@verisec.com";
InitiateSignRequest initSignRequest = 
    InitiateSignRequest.createCustom()
                .setEmail(email)
                .setDataToSign(dataToSign)
                .setExpiry(expiry)
                .setMinRegistrationLevel(minRegistrationLevel)
                .setAttributesToReturn(attributes)
                .setPushNotification(pushNotification)
                .setTitle(title)
                .build();
 
/*
* In case of Initiate sign method, response type is String.
* The data in this response is the signature transaction reference.
*/

String transactionReference = 
    signClient.initiate(initSignRequest);

User confirmation method

User confirmation method defines how the user needs to confirm the transaction. Possible values for this parameter are DEFAULT and DEFAULT_AND_FACE.
By default, the user confirmation method is DEFAULT, which means that the user confirms transactions by using PIN or device biometrics.
Value DEFAULT_AND_FACE will request from user to perform face authentication in addition to PIN or device biometrics.

/*
* Parameter relyingPartyId represents a unique ID of the Relying Party
* for which the authentication request should be initiated.
*/

String relyingPartyId = "relying_party_id";
 
InitiateSignRequest initiateSignRequest =
    InitiateSignRequest
        .createCustom()
        .setEmail(email)
        .setRelyingPartyId(relyingPartyId)
        .setUserConfirmationMethod(UserConfirmationMethod.DEFAULT_AND_FACE)
        .build();

Concerning Integrators/Integrated Relying Parties

For each Integrated Relying Party, as well as the Integrator themselves, Freja eID generates a unique identifier called relyingPartyId. The Integrator needs to pass this identifier in each request. Read more about Integrator Relying Parties here.

Integrator-specific User ID

This section will only be relevant to you if you are an Integrator acting on behalf of Integrated Relying Parties.

If you are a Partner/Relying Party acting only on your own behalf, feel free to skip this section.

Besides the above-mentioned attributes, Integrator Relying Parties can ask for an additional user attribute called INTEGRATOR_SPECIFIC_USER_ID. This is a unique, user-specific value that allows the Integrator to identify the same user across multiple sessions regardless of the Integrated Relying Party service that the user is using.

Get One Signature Result

This method is used to fetch a single result for a specified signature transaction reference (signRef returned from a call to Initiate Sign method).

You can request the integratorSpecificUserId attribute only if you are an Integrator, and you must pass relyingPartyId in the request.

Get Final Signature Result

This is a blocking method and is used to fetch a single result with a final status (can be one of: rejected, approved, cancelled or expired) for a specified signature reference. The method keeps polling until it receives the final status of the signature request. If the maximum polling time expires before the action is completed, the method will throw an exception.

Get Signature Results

This method is used to fetch the results of multiple signature requests.

Cancel Signature

This method is used to cancel an initiated signature request.

Go to: