/
Signature in Organisation ID Service

Signature in Organisation ID Service

Initiate Sign Method

This page covers signing within Freja’s Organisation ID service. For a general guide on the Freja Signature Service, check this page.

The method is called using HTTP POST through the URLs below:

Environment

Endpoint

Environment

Endpoint

TEST

https://services.test.frejaeid.com/organisation/sign/1.0/init

PRODUCTION

https://services.prod.frejaeid.com/organisation/sign/1.0/init

Important!

You need to have an Organisation ID set for a user to be able to initiate signature requests using these URLs. If that is not the case, please refer to Organisation ID Service.

JSON Example for initSignRequest

The parameter of the method is a Base64 UTF8-encoded JSON payload according to the following:

{ "userInfoType":"User info type", "userInfo":"User information corresponding to user info type", "minRegistrationLevel":"Minimum required registration level of a user", "userConfirmationMethod":"Method used to confirm user's identity", "useDynamicQrCode":"Flag to enable dynamic QR code", "title":"Title to display in transaction list", "pushNotification":{ "title":"Title to display in push notification to user", "text":"Text to display in push notification to user" }, "expiry":"Expiry time for the request", "dataToSignType":"Type of data to sign", "dataToSign":"The data to be signed", "signatureType":"Signature type", "attributesToReturn":[ { "attribute":"Type of attribute to be returned" } ] "orgIdIssuer":"Optional, should be ANY if requested organisation ID is set by another Relying Party" }

  • userInfoType: string, mandatory. Describes the type of user information supplied to identify the end user. Currently one of:

    • ORG_ID (specific organisation identifier),

    • PHONE (end user's telephone number),

    • EMAIL (end user's email),

    • SSN (end user's social security number),

    • UPI (user’s unique personal identifier in Freja),

    • INFERRED  (the user need not enter any identifier, their identity will be determined as a result of the authentication process). The INFERRED method is typically used in conjunction with QR codes.

  • userInfo: string, mandatory, 256 characters maximum.

    • If the userInfoType is ORG_ID, interpreted as a string value of the specific organisation identifier set for the end user.

For more information on userInfo refer to https://frejaeid.atlassian.net/wiki/spaces/DOC/pages/2162814/Signature+Service#JSON-Example-for-initSignRequest

  • orgIdIssuer: ORGANISATION_ID_IDENTIFIER  or ORGANISATION_ID can be requested even if it is set by another Relying Party. Do this by setting the orgIdIssuer parameter to ANY.

In order to be able to request organisation ID set by another Relying Party, you must first get in touch with partnersupport@frejaeid.com.

For more information about the rest of the parameters refer to https://frejaeid.atlassian.net/wiki/spaces/DOC/pages/2162814/Signature+Service#JSON-Example-for-initSignRequest

Example Request with ORG_ID userInfoType

If you wish to initiate a signature request for a user with the specific organisation identifier 'vejobla', follow these steps:

  1. Create the JSON structure {"userInfoType":"ORG_ID","userInfo":"vejobla","title":"Sign transaction","expiry":1517526000000,"dataToSignType":"SIMPLE_UTF8_TEXT",
    "dataToSign":{"text":"VGhpcyBpcyBhIHRleHQgZm9yIHNpZ24gdHJhbnNhY3Rpb24u"},"signatureType":"SIMPLE","attributesToReturn":[{"attribute":"BASIC_USER_INFO"}]}

  2. Encode the JSON structure to Base64.

  3. Create the HTTP POST request with a POST parameter name initSignRequest and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following (compact format, line broken for clarity only):

initSignRequest=eyJ1c2VySW5mb1R5cGUiOiJPUkdfSUQiLCJ1c2VySW5mbyI6InZlam9ibGEiLC J0aXRsZSI6IlNpZ24gdHJhbnNhY3Rpb24iLCJleHBpcnkiOjE1MTc1MjYwMDAwMDAsImRhdGFUb1Np Z25UeXBlIjoiU0lNUExFX1VURjhfVEVYVCIsImRhdGFUb1NpZ24iOnsidGV4dCI6IlZHaHBjeUJwY3 lCaElIUmxlSFFnWm05eUlITnBaMjRnZEhKaGJuTmhZM1JwYjI0dSJ9LCJzaWduYXR1cmVUeXBlIjoi U0lNUExFIiwiYXR0cmlidXRlc1RvUmV0dXJuIjpbeyJhdHRyaWJ1dGUiOiJCQVNJQ19VU0VSX0lORk 8ifV19

Example Request with EMAIL userInfoType

If you wish to initiate a signature request for a user with an email address joe.black@freja.com, follow these steps:

  1. Create the JSON structure {"userInfoType":"EMAIL","userInfo":"joe.black@freja.com","title":"Sign transaction","expiry":1517526000000,"dataToSignType":"SIMPLE_UTF8_TEXT",
    "dataToSign":{"text":"VGhpcyBpcyBhIHRleHQgZm9yIHNpZ24gdHJhbnNhY3Rpb24u"},"signatureType":"SIMPLE","attributesToReturn":[{"attribute":"ORGANISATION_ID_IDENTIFIER"}]}

  2. Encode the JSON structure to Base64.

  3. Create the HTTP POST request with a POST parameter name initSignRequest and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following (compact format, line broken for clarity only):

initSignRequest=eyJ1c2VySW5mb1R5cGUiOiJFTUFJTCIsInVzZXJJbmZvIjoiam9lLmJsYWNrQH ZlcmlzZWMuY29tIiwidGl0bGUiOiJTaWduIHRyYW5zYWN0aW9uIiwiZXhwaXJ5IjoxNTE3NTI2MDAw MDAwLCJkYXRhVG9TaWduVHlwZSI6IlNJTVBMRV9VVEY4X1RFWFQiLAoiZGF0YVRvU2lnbiI6eyJ0ZX h0IjoiVkdocGN5QnBjeUJoSUhSbGVIUWdabTl5SUhOcFoyNGdkSEpoYm5OaFkzUnBiMjR1In0sInNp Z25hdHVyZVR5cGUiOiJTSU1QTEUiLCJhdHRyaWJ1dGVzVG9SZXR1cm4iOlt7ImF0dHJpYnV0ZSI6Ik 9SR0FOSVNBVElPTl9JRF9JREVOVElGSUVSIn1dfQ==

Example Request with PHONE userInfoType

If you wish to initiate a sign request for a user with a phone number '+46731234567':

  1. Create the JSON structure {"userInfoType":"PHONE","userInfo":"+46731234567","title":"Sign transaction","confidential":false,"expiry":1517526000000,"dataToSignType":"SIMPLE_UTF8_TEXT","dataToSign":{"text":"VGhpcyBpcyBhIHRleHQgZm9yIHNpZ24gdHJhbnNhY3Rpb24u"},"signatureType":"SIMPLE"}

  2. Encode the JSON structure to Base64.

  3. Create the HTTP POST request with a POST parameter name initSignRequest and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following:

initSignRequest=eyJ1c2VySW5mb1R5cGUiOiJQSE9ORSIsInVzZXJJbmZvIjoiKzQ2NzMxMjM0NTY 3IiwidGl0bGUiOiJTaWduIHRyYW5zYWN0aW9uIiwiY29uZmlkZW50aWFsIjpmYWxzZSwiZXhwaXJ5Ij oxNTE3NTI2MDAwMDAwLCJkYXRhVG9TaWduVHlwZSI6IlNJTVBMRV9VVEY4X1RFWFQiLCJkYXRhVG9Ta WduIjp7InRleHQiOiJWR2hwY3lCcGN5QmhJSFJsZUhRZ1ptOXlJSE5wWjI0Z2RISmhibk5oWTNScGIy NHUifSwic2lnbmF0dXJlVHlwZSI6IlNJTVBMRSJ9

Example Request with SSN userInfoType

If you wish to initiate a sign request for a user with an SSN '198905218072' and country 'SE':

  1. Create the JSON structure {"country":"SE","ssn":"198905218072"}, then do the base64 of this JSON.

  2. This is the Base64 of step 1:   'eyJjb3VudHJ5IjoiU0UiLCJzc24iOiIxOTg5MDUyMTgwNzIifQ==' , which is the userInfo value in our request.

  3. Create the JSON structure {"userInfoType":"SSN","userInfo":"eyJjb3VudHJ5IjoiU0UiLCJzc24iOiIxOTg5MDUyMTgwNzIifQ==","title":"Sign transaction","expiry":1517526000000,"dataToSignType":"SIMPLE_UTF8_TEXT","dataToSign":{"text":"VGhpcyBpcyBhIHRleHQgZm9yIHNpZ24gdHJhbnNhY3Rpb24u"},"signatureType":"SIMPLE"}

  4. Encode the JSON structure to Base64.

  5. Create the HTTP POST request with a POST parameter name initSignRequest and the Base64 encoded JSON structure from the step 4 as its value.

The HTTP body should be the following:

initSignRequest=eyJ1c2VySW5mb1R5cGUiOiJTU04iLCJ1c2VySW5mbyI6ImV5SmpiM1Z1ZEhKNU lqb2lVMFVpTENKemMyNGlPaUl4T1RnNU1EVXlNVGd3TnpJaWZRPT0iLCJ0aXRsZSI6IlNpZ24gdHJh bnNhY3Rpb24iLCJleHBpcnkiOjE1MTc1MjYwMDAwMDAsImRhdGFUb1NpZ25UeXBlIjoiU0lNUExFX1 VURjhfVEVYVCIsImRhdGFUb1NpZ24iOnsidGV4dCI6IlZHaHBjeUJwY3lCaElIUmxlSFFnWm05eUlI TnBaMjRnZEhKaGJuTmhZM1JwYjI0dSJ9LCJzaWduYXR1cmVUeXBlIjoiU0lNUExFIn0=

Example request with UPI userInfoType

If you wish to initiate a signature request for a user with unique personal identifier 5633-823597-7862, follow these steps:

  1. Create the JSON structure {"userInfoType":"UPI","userInfo":"5633-823597-7862","title":"Sign transaction","expiry":1517526000000,"dataToSignType":"SIMPLE_UTF8_TEXT", "dataToSign":{"text":"VGhpcyBpcyBhIHRleHQgZm9yIHNpZ24gdHJhbnNhY3Rpb24u"},"signatureType":"SIMPLE","attributesToReturn":[{"attribute":"ORGANISATION_ID_IDENTIFIER"}]}

  2. Encode the JSON structure to Base64.

  3. Create the HTTP POST request with a POST parameter name initSignRequest and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following (compact format, line broken for clarity only):

initSignRequest=eyJ1c2VySW5mb1R5cGUiOiJVUEkiLCJ1c2VySW5mbyI6IjU2MzMtODIzNTk3LTc 4NjIiLCJ0aXRsZSI6IlNpZ24gdHJhbnNhY3Rpb24iLCJleHBpcnkiOjE1MTc1MjYwMDAwMDAsImRhdG FUb1NpZ25UeXBlIjoiU0lNUExFX1VURjhfVEVYVCIsCiJkYXRhVG9TaWduIjp7InRleHQiOiJWR2hwY 3lCcGN5QmhJSFJsZUhRZ1ptOXlJSE5wWjI0Z2RISmhibk5oWTNScGIyNHUifSwic2lnbmF0dXJlVHlw ZSI6IlNJTVBMRSIsImF0dHJpYnV0ZXNUb1JldHVybiI6W3siYXR0cmlidXRlIjoiT1JHQU5JU0FUSU9 OX0lEX0lERU5USUZJRVIifV19

Possible Errors

Code Returned

Explanation

Code Returned

Explanation

0

Internal error.

1001

Invalid or missing userInfoType.

1002

Invalid or missing userInfo.

1004

You are not allowed to call this method.

1005

User has disabled your service.

1006

Invalid confidential.

1008

Unknown Relying Party.

1009

You are not allowed to request integratorSpecificUserId parameter.

1010

JSON request cannot be parsed.

1012

User with the specified userInfo does not exist in Freja eID database.

3000

Invalid or missing dataToSignType.

3001

Invalid or missing dataToSign.

3002

Invalid or missing signatureType.

3003

Invalid expiry time.

3004

Invalid push notification.

3005

Invalid attributesToReturn parameter.

3006

Custom identifier has to exist when it is requested.

3007

Invalid title.

4001

In order to use organisational transactions, user must have an Organisation ID set. 

4007

Invalid organisation ID issuer.

JSON Response Value

If HTTP 200 is returned from the method, the following return value will be present in the body of the response:

{ "signRef":"Reference to be submitted in getOneResult method" }

  • signRef: string, mandatory. A reference unique to the transaction that can be used to query the result of a specific transaction.

Methods for Retrieving Signature Results

There are two methods that can be used for fetching digital signature results:

  1. one that returns a single result for a specified signature reference (signRef returned from a call to Initiate Sign Method), and

  2. one that returns multiple signature results.

The second is the preferred way of fetching results in situations where a Relying Party has many concurrent signatures in progress, as it reduces the number of polling requests.

Get One Signature Result Method

The method is called using HTTP POST through the URLs below:

Environment

Endpoint

Environment

Endpoint

TEST

https://services.test.frejaeid.com/organisation/sign/1.0/getOneResult

PRODUCTION

https://services.prod.frejaeid.com/organisation/sign/1.0/getOneResult

JSON Example for getOneSignResultRequest

The parameter of the method is a Base64 UTF8-encoded JSON payload according to the following:

{ "signRef":"Signature reference" }

signRef: string, mandatory. The value must be equal to a signature reference previously returned from a call to the Initiate Sign Method. 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.

Example Request

If you wish to fetch a single signature result with the signature reference previously returned from a call to initSignRequest (for a user with specific organisation identifier 'vejobla'), follow these steps:

  1. Create the JSON structure {"signRef":"TrLA9zdxCBlNOQNvkdhAM14mJmlL20digC7+QgEVRwmE7SH8Qm0swWIc6whfKm4Y"}

  2. Encode the JSON structure to Base64.

  3. Create the HTTP POST request with a POST parameter name getOneSignResultRequest and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following (compact format, line broken for clarity only):

getOneSignResultRequest=eyJzaWduUmVmIjoiVHJMQTl6ZHhDQmxOT1FOdmtkaEFNM TRtSm1sTDIwZGlnQzcrUWdFVlJ3bUU3U0g4UW0wc3dXSWM2d2hmS200WSJ9

Possible Errors

Code Returned

Explanation

Code Returned

Explanation

1008

Unknown Relying Party.

1100

Invalid reference (for example, nonexistent or expired).

JSON Response Value

If HTTP 200 is returned from the method, the following return value will be present in the body of the response:

{ "signRef":"Signature reference", "status":"Signature status", "details":"JWS signed data", "requestedAttributes":"Additional attributes about the user" }

  • signRef: string, mandatory . The signature reference of the signing request.

  • status: string, mandatory. One of:

    • STARTED (the transaction has been started but not yet delivered to Freja eID application associated with the end user),

    • DELIVERED_TO_MOBILE (the Freja eID app has downloaded the transaction),

    • CANCELED (the end user declined the signature request), 

    • RP_CANCELED (the sign request was sent to the user but canceled by the Relying Party before the user could respond),

    • EXPIRED (the signature request was not approved by the end user within the signature validity limit as requested when the signature was initialised),

    • APPROVED (the signature was successful).

  • details: A signed object, optional. Provides details and evidence of the signing if status was equal to APPROVED. For more details see below.

  • requestedAttributes: JSON object, optional. Provides additional attributes about a user if required in attributestToReturn parameter in related initSignRequest and the status was equal to APPROVED. For more details see here: https://frejaeid.atlassian.net/wiki/spaces/DOC/pages/2162802.

details

The content of this response element will depend on the signatureType requested when the signature was initiated.

Simple Signature Type

JWS in compact serialised form as following:

BASE64URL(UTF8(JWS Protected Header)) || ’.’ || BASE64URL(JWS Payload) || ’.’ || BASE64URL(JWS Signature)

JWS Protected Header

{ "x5t":"SHA-1 digest of the signing certificate", "alg":"algorithm used to secure the JWS" }

  • x5t: mandatory, Base64URL encoding of the certificate's SHA-1 digest.

  • alg: mandatory, the value shall be RS256 which corresponds to 'RSA PKCS#1 signature with SHA-256'.

JWS Payload

{ "signRef":"Signature reference", "status":"Signature status", "userInfoType":"User info type", "userInfo":"User information corresponding to user info type", "minRegistrationLevel":"Minimum required registration level of a user", "timestamp":"Time when signature was confirmed by end user", "signatureType":"Signature type", "signatureData": { "userSignature":"The signature produced by the end user", "certificateStatus":"Evidence of end-users certificate status", "advancedSignature" : "If requested, the advanced signature" }, "requestedAttributes":{ "JSON object" }, }

  • signRef: See signRef as described in the Get One Signature Result Method above.

  • status: See status as described in the Get One Signature Result Method above.

  • userInfoType: As described in Initiate Sign Method.

  • userInfo: As described in Initiate Sign Method.

  • minRegistrationLevel: As described in Initiate Sign Method.

  • timestamp: Long, mandatory. Describes the time when the confirmation by the end user was validated on Freja eID server side. Expressed in milliseconds, since January 1, 1970, 00:00 UTC.

  • signatureType: As described in Initiate Sign Method.

  • signatureData: See fields below, mandatory.

    • userSignature: The produced signature, string, mandatory. Contains the end user's signature in the requested format. The end user's signature will implicitly contain the dataToSign as requested in the Initiate Sign method as within its payload.

    • certificateStatus: Base64 string, mandatory. Contains the OCSP response regarding the state of the end-user certificate at the time of validating the signature.

    • advancedSignature: Base64 string, mandatory for advanced signature types. Contains signed data in requested format.

  • requestedAttributes: As described in Initiate Sign Method.

Get Signature Results Method

The method is called using HTTP POST through the URLs below:

Environment

Endpoint

Environment

Endpoint

TEST

https://services.test.frejaeid.com/organisation/sign/1.0/getResults

PRODUCTION

https://services.prod.frejaeid.com/organisation/sign/1.0/getResults

JSON Example for getSignResultsRequest

The parameter of the method is a Base64 UTF8-encoded JSON payload according to the following:

{ "includePrevious":"Include previously returned results" }

  • includePrevious: string, mandatory. Must be equal to ALL. Indicates that the complete list of signature requests is 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.

Example Request

If you wish to fetch multiple signature results, follow these steps:

  1. Create the JSON structure {"includePrevious":"ALL"}

  2. Encode the JSON structure to Base64.

  3. Create the HTTP POST request with a POST parameter name getSignResultsRequest and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following:

getSignResultsRequest=eyJpbmNsdWRlUHJldmlvdXMiOiJBTEwifQ==

Possible Errors

Code Returned

Explanation

Code Returned

Explanation

1008

Unknown Relying Party.

1100

Invalid reference (for example, nonexistent or expired).

JSON Response Value

If HTTP 200 is returned from the method, the following return value will be present in the body of the response:

{ "signatureResults":[ { "signRef":"Signature reference", "status":"Signature status", "details":"Signed data", "requestedAttributes":{ "basicUserInfo":{ "name":"User's name", "surname":"User's surname" }, "emailAddress":"User's primary email address", "allEmailAddresses"[ { "emailAddress":"User's primary email address" }, { "emailAddress":"Other user's email address" }, ], "allPhoneNumbers":[ { "phoneNumber":"User's phone number" }, { "phoneNumber":"User's phone number" }, ], "dateOfBirth":"User's date of birth", "age":"User's age", "gender":"User's gender", "photo":"User's photo, Base64 encoded JPEG bytes", "nfcIdPhoto":"User's photo from ID document, Base64 encoded JPEG bytes", "addresses":[ { "country":"Country", "city":"City", "postCode":"Postal code", "address1":"Street, number or equivalent", "address2":"Street, number or equivalent", "address3":"Street, number or equivalent", "validFrom":"Date from which the address is valid", "type":"Type of user's address", "sourceType":"Source from which the address is obtained" } ], "customIdentifier":"Custom identifier set by the Relying Party", "ssn":{ "ssn":"Social security number of the end user", "country":"Country of SSN" }, "document":{ "type":"Type of document used for registration e.g. passport", "country":"Document issuing country", "serialNumber":"Document serial number", "expirationDate":"Document expiration date" }, "documentPhoto":"Document photo, Base64 encoded JPEG bytes", "registrationLevel":"User's registration level in Freja", "uniquePersonalIdentifier":"User's unique personal identifier in Freja", "loaLevel":"User's level of assurance (LOA) in Freja", "relyingPartyUserId":"Unique user ID reserved for Relying Parties", "integratorSpecificUserId":"Unique user ID reserved for Integrators" } }, { "signRef":"...", } ] }

  • signatureResults: an array of JSON objects, mandatory. An array of signature result objects (if the signatureRef parameter was passed, the array will always be of length 1).

  • signRef: See signRef as described in the Get One Signature Result Method above.

  • status: See status as described in the Get One Signature Result Method above.

  • details: See details as described in the Get One Signature Result Method above.

  • requestedAttributes: As described in Initiate Sign Method.

Cancel Sign Method

This method is used by a Relying Party to cancel a signature request. The method is called using HTTP POST through the URLs below:

Environment

Endpoint

Environment

Endpoint

TEST

https://services.test.frejaeid.com/organisation/sign/1.0/cancel

PRODUCTION

https://services.prod.frejaeid.com/organisation/sign/1.0/cancel

JSON Example for cancelSignRequest

The parameter of the method is a Base64 UTF8-encoded JSON payload according to the following:

{ "signRef":"Authentication reference" }

  • signRef: string, mandatory . The value must be equal to a signature reference previously returned from a call to the Initiate Sign method.

Example Request

If you wish to cancel a sign request, follow these steps:

  1. Create the JSON structure {"signRef":"TrLA9zdxCBlNOQNvkdhAM14mJmlL20digC7+QgEVRwmE7SH8Qm0swWIc6whfKm4Y"}

  2. Encode the JSON structure to Base64.

  3. Create the HTTP POST request with a POST parameter name cancelSign and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following:

cancelSignRequest=eyJzaWduUmVmIjoiVHJMQTl6ZHhDQmxOT1FOdmtkaEFNMTRtSm1sTDIwZGln QzcrUWdFVlJ3bUU3U0g4UW0wc3dXSWM2d2hmS200WSJ9

Possible Errors

Code Returned

Explanation

Code Returned

Explanation

1004

You are not allowed to call this method.

1008

Unknown Relying Party.

1100

Invalid reference (for example, nonexistent or expired).

If HTTP 200 is returned from the method, the request was successfully fulfilled.