Table of contents
Other clients:
Overview
Freja eID Signature Service allows Relying Parties to securely deliver messages to a user, as well as to prompt Freja eID end users to digitally sign data and documents. The key difference between the Authentication Service and the Signature Service in terms of flow is that, whereas a user can only have one authentication transaction active at any given time and the duration of authentication transactions is limited to two minutes, multiple signatures can be pending for a user's approval and each individual signature transaction can be open for up to 30 days.
For more detailed information about the Signature Service, please refer to Freja eID Relying Party Developers' Documentation.
Calling a Service
This section describes how to make calls to the Freja eID Signature Service API and process the response.
Initiate Sign
This method is used by a Relying party to initiate a signing request. As opposed to authentication requests, multiple signature requests may be active at any given time, from the same or different Relying Parties.
Signatures can be created both in online contexts, where the access to the Relying Party's service or application is initiated by the end user, as in offline contexts, where the signature request is initiated by the Relying Party's service in its own right. Signature transactions, therefore, have configurable longevity — from the point of initiation, the user has between two minutes and 30 days to confirm the signature request.
Relying Parties that 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 eID here.
/* * Initiate sign request can be created with EMAIL and TITLE and TEXT to be signed. * Change the values to match your setup. * See the example below. */ 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. * See the example below. */ 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); /* * 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. * See the example below. */ String phoneNum = "+467123456789"; InitiateSignRequest initSignRequest = InitiateSignRequest.createCustom() .setPhoneNumber(phoneNum) .setDataToSign(dataToSign) .build(); /* * Parameter minRegistrationLevel, optional, describes * 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.DATE_OF_BIRTH, AttributeToReturn.RELYING_PARTY_USER_ID, AttributeToReturn.SSN, AttributeToReturn.CUSTOM_IDENTIFIER}; /* * 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);
For each Integrated Relying Party, as well for the Integrator Relying Party itself, Freja eID generates a unique identifier called relyingPartyId. The Integrator Relying Party needs to pass this identifier in each request.
/* * Parameter relyingPartyId represents a unique ID of the Relying Party * for which the signing request should be initiated. */ String relyingPartyId = "relying_party_id"; InitiateSignRequest initSignRequest = InitiateSignRequest.createCustom() .setEmail(email) .setDataToSign(dataToSign) .setRelyingPartyId(relyingPartyId) .build();
Integrator specific user id
An Integrated Relying Party can ask for additional information about the user in the same way as the other Relying Parties, but can also ask for INTEGRATOR_SPECIFIC_USER_ID - 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.
/* * Parameter relyingPartyId represents a unique ID of the Relying Party * for which the signing request should be initiated. */ String relyingPartyId = "relying_party_id"; /* * When initiating signature, you have to set relyingPartyId for every request. * See the example below. */ String email = "joe.black@verisec.com"; AttributeToReturn[] attributes = {AttributeToReturn.INTEGRATOR_SPECIFIC_USER_ID}; InitiateSignRequest initSignRequest = InitiateSignRequest.createCustom() .setEmail(email) .setDataToSign(dataToSign) .setAttributesToReturn(attributes) .setRelyingPartyId(relyingPartyId) .build(); String transactionReference = signClient.initiate(initSignRequest);
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).
Only Integrator Relying Parties can request integratorSpecificUserId and relyingPartyId has to be passed as a part of the request.
/* * A reference unique to the transaction that can be used to query the result of a transaction. */ String signRef ="reference"; /* * In case of getResult method, response type is SignResult. * Response contains signature transaction reference of the signing request, * the status of the action and details (can be used for extra validation of response). * Response contains additional attributes (basicUserInfo - user's name and surname, * emailAddress - user's email address, dateOfBirth - user's date of birth, * relyingPartyUserId, customIdentifier, ssn - country and ssn or integratorSpecificUserId). */ SignResultRequest signResultRequest = SignResultRequest.create(signRef); SignResult response = signClient.getResult(signResultRequest); String receivedSignRef = response.getSignRef(); ActionStatus status = response.getStatus(); String details = response.getDetails(); RequestedAttributes requestedAttributes = response.getRequestedAttributes(); BasicUserInfo basicUserInfo = requestedAttributes.getBasicUserInfo(); String emailAddress = requestedAttributes.getEmailAddress(); SsnUserInfo ssn = requestedAttributes.getSsn(); String relyingPartyUserId = requestedAttributes.getRelyingPartyUserId(); String dateOfBirth = requestedAttributes.getDateOfBirth(); String customIdentifier = requestedAttributes.getCustomIdentifier(); String integratorSpecificUserId = requestedAttributes.getIntegratorSpecificUserId();
Get Final Signature Result
This is a blocking method and is used by a Relying Party 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 signing action. If the maximum polling time expires before the action is completed, the method will throw an exception.
Only Integrator Relying Parties can request integratorSpecificUserId and relyingPartyId has to be passed as a part of the request.
/* * A reference unique to the transaction that can be used to query the result of that transaction. */ String signRef ="reference"; /* * A maximum time in seconds to wait for a final status of action * (to be approved, cancelled, rejected or expired). */ int maxWaitingTimeInSec = 120; /* * In case of pollForResult method, response type is SignResult. * Response contains signature transaction reference of the signing request, * the status of the action and details (can be used for extra validation of response). * Response contains additional attributes (basicUserInfo - user's name and surname, * emailAddress - user's email address, dateOfBirth - user's date of birth, * relyingPartyUserId, customIdentifier, ssn - country and ssn or integratorSpecificUserId). * If maxWaitingTimeInSec passes and signature action is not completed with one of the final statuses, * this method will throw FrejaEidClientPollingException. */ SignResultRequest signResultRequest = SignResultRequest.create(signRef); SignResult response = signClient.pollForResult(signResultRequest, maxWaitingTimeInSec); String receivedSignRef = response.getSignRef(); ActionStatus status = response.getStatus(); String details = response.getDetails(); RequestedAttributes requestedAttributes = response.getRequestedAttributes(); BasicUserInfo basicUserInfo = requestedAttributes.getBasicUserInfo(); String emailAddress = requestedAttributes.getEmailAddress(); SsnUserInfo ssn = requestedAttributes.getSsn(); String relyingPartyUserId = requestedAttributes.getRelyingPartyUserId(); String dateOfBirth = requestedAttributes.getDateOfBirth(); String customIdentifier = requestedAttributes.getCustomIdentifier(); String integratorSpecificUserId = requestedAttributes.getIntegratorSpecificUserId();
Get Signature Results
This method is used to fetch the results of multiple outstanding signature requests.
Integrator Relying Parties have to pass relyingPartyId as part of the request.
/* * Response type is list of sign result. * The response will contain a complete list of signature requests * successfully initiated by the Relying Party. * The time period during which a specific signature reference is available for checking will depend on * the longevity of the signature operation (see the expiry parameter in the Initiate sign method) * and is calculated as expiry time plus 3 days. */ SignResultsRequest signResultsRequest = SignResultsRequest.create(); List<SignResult> response = signClient.getResults(signResultsRequest);
Cancel Signature
This method is used to cancel an initiated signature request.
Integrator Relying Parties have to pass relyingPartyId as a part of the request.
/* * A reference unique to the transaction that can be used to query the result of the transaction. */ String signRef ="reference"; CancelSignRequest cancelSignRequest = CancelSignRequest.create(signRef); signClient.cancel(cancelSignRequest);
Logging and Error Handling
Details for logging and introduction to client exception can be found in the Logging and Error Handling.