/
Authentication in Organisation ID Service

Authentication in Organisation ID Service

Initiate Authentication Method

This page covers authentication within Freja’s Organisation ID service. For a general guide on the Freja Authentication 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/authentication/1.0/init

PRODUCTION

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

Important!

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

JSON Example for initAuthRequest

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", "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 (end 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.

  • attributesToReturn: list of objects, optional. When retrieving results, additional information about the user can be returned based on the type of attributes required through this parameter. Each object should contain one attribute. For the full list of attributes, refer to https://frejaeid.atlassian.net/wiki/spaces/DOC/pages/2162802/Authentication+Service#JSON-Example-for-initAuthRequest , the following are specific to this service:

    • ORGANISATION_ID_IDENTIFIER (specific organisation identifier set for the end user by the Relying Party through the Organisation ID Service), 

    • ORGANISATION_ID (specific organisation identifier set for the end user by the Relying Party, relying party localised (EN and SV) friendly name, relying party organisation code and additional attributes),

  • 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.

organisationId

Below is the organisationId attribute.

"organisationId": { "identifier":"User's organisation identifier", "issuerFriendlyName":{"EN":" Relying Party Friendly Name", "SV":"Relying Party Friendly Name"}, "issuerCode":"Organisational code", "additionalAttributes":[ { "key":"attribute_key", "value":"attribute_value", "displayText":"attribute_name" } ] }

Example Request with ORG_ID userInfoType

If you wish to initiate authentication request for a user with the specific organisation identifier 'vejobla'  and request their name, surname and SSN, follow these steps:

  1. Create the JSON structure {"userInfoType":"ORG_ID","userInfo":"vejobla", "attributesToReturn":[{"attribute":"BASIC_USER_INFO"},{"attribute":"SSN"}]}

  2. Encode the JSON structure to Base64.

  3. Create the HTTP POST request with a POST parameter name initAuthRequest 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):

initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJPUkdfSUQiLCJ1c2VySW5mbyI6InZlam9ibGEiLC AiYXR0cmlidXRlc1RvUmV0dXJuIjpbeyJhdHRyaWJ1dGUiOiJCQVNJQ19VU0VSX0lORk8ifSx7ImF0 dHJpYnV0ZSI6IlNTTiJ9XX0=

Example Request with EMAIL userInfoType

If you wish to initiate authentication request for a user with an email address joe.black@freja.com and request their name, surname, SSN and organisation identifier, follow these steps:

  1. Create the JSON structure {"userInfoType":"EMAIL","userInfo":"joe.black@freja.com","attributesToReturn":[{"attribute":"BASIC_USER_INFO"},{"attribute":"SSN"},{"attribute":"ORGANISATION_ID_IDENTIFIER"}]}

  2. Encode the JSON structure to Base64.

  3. Create the HTTP POST request with a POST parameter name initAuthRequest 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):

initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJFTUFJTCIsInVzZXJJbmZvIjoiam9lLmJsYWNrQHZ lcmlzZWMuY29tIiwiYXR0cmlidXRlc1RvUmV0dXJuIjpbeyJhdHRyaWJ1dGUiOiJCQVNJQ19VU0VSX0 lORk8ifSx7ImF0dHJpYnV0ZSI6IlNTTiJ9LHsiYXR0cmlidXRlIjoiT1JHQU5JU0FUSU9OX0lEX0lER U5USUZJRVIifV19

Example Request with PHONE userInfoType

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

  1. Create the JSON structure {"userInfoType":"PHONE","userInfo":"+46731234567"}

  2. Encode the JSON structure to Base64.

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

The HTTP body should be the following:

initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJQSE9ORSIsInVzZXJJbmZvIjoiKzQ2NzMxMjM0NTY3In0=

Example Request with SSN userInfoType

If you wish to initiate authentication 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=="}

  4. Encode the JSON structure to Base64.

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

The HTTP body should be the following:

initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJTU04iLCJ1c2VySW5mbyI6ImV5SmpiM1Z1ZEhKNUlq b2lVMFVpTENKemMyNGlPaUl4T1RnNU1EVXlNVGd3TnpJaWZRPT0ifQ==

Example request with UPI userInfoType

If you wish to initiate authentication request for a user with unique personal identifier 5633-823597-7862 and request their name, surname, SSN and organisation identifier, follow these steps:

  1. Create the JSON structure {"userInfoType":"UPI","userInfo":"5633-823597-7862","attributesToReturn":[{"attribute":"BASIC_USER_INFO"},{"attribute":"SSN"},{"attribute":"ORGANISATION_ID_IDENTIFIER"}]}

  2. Encode the JSON structure to Base64.

  3. Create the HTTP POST request with a POST parameter name initAuthRequest 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):

initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJVUEkiLCJ1c2VySW5mbyI6IjU2MzMtODIzNTk3 LTc4NjIiLCJhdHRyaWJ1dGVzVG9SZXR1cm4iOlt7ImF0dHJpYnV0ZSI6IkJBU0lDX1VTRVJfSU5G TyJ9LHsiYXR0cmlidXRlIjoiU1NOIn0seyJhdHRyaWJ1dGUiOiJPUkdBTklTQVRJT05fSURfSURF TlRJRklFUiJ9XX0=

Example Request with INFERRED userInfoType

If you wish to authenticate a user via a QR code:

  1. Create the JSON structure {"userInfoType":"INFERRED","userInfo":"N/A"}

  2. Encode the JSON structure to Base64.

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

The HTTP body should be the following:

initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJJTkZFUlJFRCIsInVzZXJJbmZvIjoiTi9BIn0=

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.

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.

2000

Authentication request failed. Previous authentication request was rejected due to security reasons.

2002

Invalid attributesToReturn parameter.

2003

Custom identifier has to exist when it is requested.

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:

{ "authRef":"Reference to be submitted in getAuthResults method" }

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

Get One Authentication Result Method

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

Environment

Endpoint

Environment

Endpoint

TEST

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

PRODUCTION

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

JSON Example for getOneAuthResultRequest

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

{ "authRef":"Authentication reference" }

authRef: string, mandatory. The value must be equal to an authentication reference previously returned from a call to the Initiate Authentication Method. Because authentications are short-lived, fetching the result of a given authRef is only possible within 10 minutes from the time the initial authentication request was made.

Example Request

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

  1. Create the JSON structure {"authRef":"GOHPyJcoKLJ+zKCEy4abi6jOO+q5VK+S1+UO5OXRmOPu42ixvVnsVgs7ADYUfG8m"}

  2. Encode the JSON structure to Base64.

  3. Create the HTTP POST request with a POST parameter name getOneAuthResultRequest 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):

getOneAuthResultRequest=eyJhdXRoUmVmIjoiR09IUHlKY29LTEorektDRXk0YWJpNmpPTytxNV ZLK1MxK1VPNU9YUm1PUHU0Mml4dlZuc1ZnczdBRFlVZkc4bSJ9

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).

JSON Response Value

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

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

  • authRef: string, mandatory. The authentication reference of the authentication.

  • 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 authentication request),

    • RP_CANCELED (the authentication request was sent to the user but cancelled by the RP before the user could respond),

    • EXPIRED (the authentication request was not approved by the end user within the authentication validity limit of two minutes),

    • APPROVED (the authentication was successful) or

    • REJECTED (e.g. if you try to run more than one authentication transaction for the same user at the same time).

  • requestedAttributes: JSON object, optional. Provides additional attributes about a user if required in attributestToReturn parameter in related initAuthRequest and the status was equal to APPROVED. For more details see below.

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

requestedAttributes

Below is an example with requestedAttributes unique to this service. For the full list refer to https://frejaeid.atlassian.net/wiki/spaces/DOC/pages/2162802/Authentication+Service#requestedAttributes.

{    "organisationIdIdentifier":"Specific organisation identifier",    "organisationId":{          "identifier":"User's organisation identifier",          "issuerFriendlyName":{                     "EN":" Relying Party Friendly Name",                                              "SV":"Relying Party Friendly Name"},          "issuerCode":"Organisational code",          "additionalAttributes":[                                   {                                     "key":"attribute_key",                                     "value":"attribute_value",                                     "displayText":"attribute_name"                                   }                                 ]        }, }

  • organisationIdIdentifier: String, the specific organisation identifier set for the end user. Must be unique within the requesting Relying Party system inside the Freja eID service.

  • organisationId: JSON object which contains specific organisation id identifier, map of localised issuer friendly name (EN and SV), organisation code and additional attributes.

details

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

{ "authRef":"Authentication reference", "status":"Authentication status", "userInfoType":"User info type", "userInfo":"User information corresponding to user info type", "minRegistrationLevel":"Minimum required registration level of a user", "requestedAttributes":{ JSON object, see below. }, "timestamp":"Time when authentication is confirmed by end user" }

  • authRef: See authRef as described in the Get One Authentication Result Method above).

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

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

  • userInfo: Depends on userInfoType.

  • minRegistrationLevel: See minRegistrationLevel as described in Initiate Authentication Method.

  • requestedAttributes: JSON object, optional. See requestedAttributes as described in the Get One Authentication Result Method above).

  • 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.

JSON Response Body with Mock Data for an APPROVED Response

{ "authRef":"12345-67890-abcdef", "status":"APPROVED", "details":"JWS content as per below", "requestedAttributes":{ "basicUserInfo":{ "name":"Joe", "surname":"Black" }, "emailAddress":"joe.black@freja.com", "allEmailAddresses":[ { "emailAddress":"joe.black@freja.com" }, { "emailAddress":"joebl@domain.com" } ], "allPhoneNumbers":[ { "phoneNumber":"+4600000000" }, { "phoneNumber":"+4611111111" } ], "dateOfBirth":"1985-11-17", "age":"36", "photo":"iVBORw0KGgoAAAANSUhEUgAAAhwAAANgCAIAAADoCyYlAAAAAXNSR0IArs4c6QAAAARnQU1BAACx jwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAACAhSURBVHhe7d2xdSJL3sbhm83mQA5KA1chfI48OciRJ+cGgKkk CEEJbBb7wWhmEFUNdHW/0EA/5zzOnYWGQmf/P7oaiX/+93//AYAIUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJE BYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEg RlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEV AGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYA...", "addresses":[ { "country":"SE", "city":"Stockholm", "postCode":"11120", "address1":"C/O Joe Black", "address2":"Visdomsgatan 55", "validFrom":"2020-03-19", "type":"RESIDENTIAL", "sourceType":"GOVERNMENT_REGISTRY" }, { "country":"NO", "city":"Oslo", "postCode":"0001", "address1":"P.O. Box 456", "validFrom":"2020-03-19", "type":"POSTAL", "sourceType":"GOVERNMENT_REGISTRY" } ], "ssn":{ "ssn":"198511170040", "country":"SE" }, "document" : { "type":"PASS", "country":"SE", "serialNumber":"XA0000001", "expirationDate":"2027-01-01" }, "registrationLevel":"EXTENDED", "uniquePersonalIdentifier":"5753-979204-7861, "loaLevel":"LOA3", "organisationIdIdentifier":"vejobla", "organisationId":{ "identifier":"vejobla", "issuerFriendlyName":{ "EN":" Freja eID", "SV":"FREJA"}, "issuerCode": null, "additionalAttributes":[ { "key":"USER_ID", "value":"123456789", "displayText":"ID" } ] }, "relyingPartyUserId":"94039a98c8d", "integratorSpecificUserId":"54059a95c8d" }

JWS Payload with Mock Data for an APPROVED Response

Certificate Info: for more information refer to https://frejaeid.atlassian.net/wiki/spaces/DOC/pages/2162826/REST+API+Documentation#%5BinlineExtension%5DCertificates-in-Freja-eID

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

{ "authRef":"12345-67890-abcdef", "status":"APPROVED", "userInfoType":"EMAIL", "userInfo":"joe.black@freja.com", "requestedAttributes":{ "basicUserInfo":{ "name":"Joe", "surname":"Black" }, "emailAddress":"joe.black@freja.com", "..." }, "timestamp":1584701027510 }

Final JWS

eyAiYXV0aFJlZiI6IjEyMzQ1LTY3ODkwLWFiY2RlZiIsICJzdGF0dXMiOiJBUFBST1ZFRCIsICJ1c2VySW5mb1R5cGUiOiJFTUF JTCIsICJ1c2VySW5mbyI6ImpvZS5ibGFja0B2ZXJpc2VjLmNvbSIsICJyZXF1ZXN0ZWRBdHRyaWJ1dGVzIjp7ICJiYXNpY1VzZX JJbmZvIjp7ICJuYW1lIjoiSm9lIiwgInN1cm5hbWUiOiJCbGFjayIgfSwgImVtYWlsQWRkcmVzcyI6ImpvZS5ibGFja0B2ZXJpc 2VjLmNvbSIsICJhbGxFbWFpbEFkZHJlc3NlcyI6WyB7ICJlbWFpbEFkZHJlc3MiOiJqb2UuYmxhY2tAdmVyaXNlYy5jb20iIH0s IHsgImVtYWlsQWRkcmVzcyI6ImpvZWJsQGRvbWFpbi5jb20iIH0gXSwgImFsbFBob25lTnVtYmVycyI6WyB7ICJwaG9uZU51bWJ lciI6Iis0NjAwMDAwMDAwIiB9LCB7ICJwaG9uZU51bWJlciI6Iis0NjExMTExMTExIiB9IF0sICJkYXRlT2ZCaXJ0aCI6IjE5OD UtMTEtMTciLCAiYWdlIjozNiwgImFkZHJlc3NlcyI6WyB7ICJjb3VudHJ5IjoiU0UiLCAiY2l0eSI6IlN0b2NraG9sbSIsICJwb 3N0Q29kZSI6IjExMTIwIiwgImFkZHJlc3MxIjoiQy9PIEpvZSBCbGFjayIsICJhZGRyZXNzMiI6IlZpc2RvbXNnYXRhbiA1NSIs ICJ2YWxpZEZyb20iOiIyMDIwLTAzLTE5IiwgInR5cGUiOiJSRVNJREVOVElBTCIsICJzb3VyY2VUeXBlIjoiR09WRVJOTUVOVF9 SRUdJU1RSWSIgfSwgeyAiY291bnRyeSI6Ik5PIiwgImNpdHkiOiJPc2xvIiwgInBvc3RDb2RlIjoiMDAwMSIsICJhZGRyZXNzMS I6IlAuTy4gQm94IDQ1NiIsICJ2YWxpZEZyb20iOiIyMDIwLTAzLTE5IiwgInR5cGUiOiJQT1NUQUwiLCAic291cmNlVHlwZSI6I kdPVkVSTk1FTlRfUkVHSVNUUlkiIH0gXSwgInNzbiI6eyAic3NuIjoiMTk4NTExMTcwMDQwIiwgImNvdW50cnkiOiJTRSIgfSwg InJlZ2lzdHJhdGlvbkxldmVsIjoiUExVUyIsICJyZWx5aW5nUGFydHlVc2VySWQiOiI5NDAzOWE5OGM4ZCIsICJpbnRlZ3JhdG9 yU3BlY2lmaWNVc2VySWQiOiI1NDA1OWE5NWM4ZCIsICJjdXN0b21JZGVudGlmaWVyIjoidmVqb2JsYSIsCsKgIMKgIMKgICJjb3 ZpZENlcnRpZmljYXRlcyI6ewoidmFjY2luZXMiOiB7CiJjZXJ0aWZpY2F0ZSI6ICJIQzE6TkNGT1hOJVRTTUFITi1IVk44SjdVU U1KNC8zUlpMTTUyWEdQMVdHMkQ1OCpJWEY1OTVUWFIzOFdBQlJNQjU3Ri84WCpHM005SlVQWTBCWlc0Oi5BNjNITk5WUipHMEM3 UEhCTzMzUlcwNUxCUE9GIFFUWUYzNEhHT0lIIDhMKzZIMVNGKzVGLzNFMUpBRi43NSBKRFhJMDNMOVpJNFE1JUgwQU44Q0owUFp CSVRIUCtQUlJNSlZVTSBJL1BTTSVHQThJTSVPJUtJKlcwIC5VUSpOIFJQLStSMllCVjQ0QyRCWEdETzk4OjBMUEhONkQ3TExLKj JIOS04OVVWLTBMLzpJUy1POlM5VVo0K0ZKRSA0WTNMTC9JSSAwT0M5U1gwKypCODVUJTYyKjVQWkQ1Q0M5VDBIJTpLNVFOWC9HS lpJSTdKU1ROQjk1KzE2TEVURjROLlNTLlBLSVhSLlVJQVlVSDJXVlFJMFRIWFpRLko5MSBGSSVCMkxHN1BHJSBCL1VJMllVNU1B WFNHK1czNFBJUUpBWkdBMjpVRyVVMkU0QVNOTUg4TS00MDVBMU9LLVVLVkNGQjNMQi42REpQSEJTMTVDL0tOS000JElJWCpCMUp TOUFDOTlORTdQSFRSTysySSo1QzZFQTJVJCA4QzJTVCBJRSVOMSsyNFY3TEQxTFpCQU1BUzMwNldETzEiCn0sCiJ0ZXN0cyI6IH siY2VydGlmaWNhdGUiOiJIQzE6TkNGT1hOJVRTTUFITi1IM080OlBWSCBBSjJKJDlKMElJNllKIDQzU0xHL0VCTkcyTjRGQk9NJ FY0Ok5RQSBNOlVDKkdQWFM0TVpLSFpBIEtFN0VDMSAzSzlMVDRENCVLKipJUjFMJTpLRVY0OTlURVc2M1pDRDdMVVoyMzRKVFBW RkhIQlk0Ty1PMEcxM0hIMC1LJUlIN1k0L1g4Nk1PQiVSSERNLi1CNi9EMEpBUVRVOEQyJUgwQU44U0owNllCVVNNQUw4Oko1U0g 2LUc5KkU5LiQwNUc5MEYzSFpJNVZBJTNLUVlKWDFKOk5LMkFEVlRBQVpJNjZKIE9LUU1JME9JU1ZCRk9KVlRBMUhBLVhJUkNJIE 9LJUlKNVFCUDdKVTdCSllKKklKNU9JLVlJRTQ2TzkzWE1SOiBLUyROOUhTNS1RSitQQStRSSVLNCRON0JNSStRViVONCtPOCVNT UcyOUFGNkxGQjgxUU1LUStNTi9RMTlRRThRIFBPRE9GJDZSTlFRM1k3NFhMMS9MSk85VVVNIFFVUS9NTjo0MzU2KkJXJCVMKy1K Ti5OIExUQldPNTpRTitBMzFVS1hQUk9TTlBTK0RXR0RJOEVIJTJMVUkyTy9FR1lJWVMyR1NTJThTLzQwQVFDSTIifSwKInJlY29 2ZXJ5IjogeyAiY2VydGlmaWNhdGUiOiJIQzE6TkNGT1hOJVRTTUFITi1IRk40VFRDNCBTSldLWio5R0JILiBNVTk2NUhSTFg4M0 xRNTVVVFNKVlFPSVZVSzFKWlpQUUEzRFA0T1c2MzFBWDVRTTlJRlkxT1NNTlYxTDhWTkY2QVlNRTBGOk5FM0tVRDoxM1pNNTo2R Uw2RSU2MFQ5MzJRLlJUUkg5L1VQTkY2N0o2UVc2T1ZRT1I2K0c5MC5HLVI1NFcxLlVJMlBIVUlFICQ0WkpKKiVDTjFUVEI1Qy1P VEYxSiozVEZIMlY0MkYxQ09UJEhGQypJVVo0K0ZKRSA0WTNMTC9JSSAwSEpQN05WREVCMTJKRCoyRDBISDc4JFpKKkRKV1A0Mlc 1OllQSEpVVFJNOE9JOVlPIExFM1VRNU1BMVRIOEwyQ1BJR1NVSFBNVStWQVdPMk84VStWSCpGWVpRIEg5OTJXICVKTVNHVVZQUV JISVkxKyBIMU8xNlAzKjdVRi5KSjhDN1hCL09JRkQ2NSpWMFdJKjlVVTNFSllSSlg1SDRVNjpWK1lUR1FGT1BFNlhWViVMVFVLS TdVUEZEQ1FVJEpWRjhDUTo1RThVT0hSJStWL0ZDOSo4IFdNOCRKVjIwTSRPODMiCiAgICAgICAgIH0sCiJhbGxvd2VkIjogdHJ1 ZQp9CsKgIMKgfSwgInRpbWVzdGFtcCI6MTU4NDcwMTAyNzUxMCB9

Get Authentication Results Method

The method allows a relying party to fetch the results of multiple outstanding authentications. It is our recommendation that you generally use the aggregate method, as it is more efficient and reduces network traffic. This is the default behaviour of the client library supplied by Freja eID. 

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

Environment

Endpoint

Environment

Endpoint

TEST

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

PRODUCTION

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

JSON Example for getAuthResultsRequest

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 authentications successfully initiated by the relying party within the last 10 minutes will be returned, including results for previously completed authentication results that have been reported through an earlier call to one of the methods for getting authentication results.

Example Request

If you wish to fetch multiple authentication 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 getAuthResultsRequest and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following:

getAuthResultsRequest=eyJpbmNsdWRlUHJldmlvdXMiOiJBTEwifQ==

Possible Errors

Code Returned

Explanation

Code Returned

Explanation

1004

You are not allowed to call this method.

1008

Unknown Relying Party.

1200

Invalid or missing includePrevious parameter.

JSON Response Value

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

{ "authenticationResults":[ { "authRef":"Authentication reference", "status":"Authentication status", "details":"JWS signed data, see below", "requestedAttributes":"Additional attributes about the user" } { "authRef":"..." } ] }

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

  • authRef: string, mandatory. The authentication reference of the authentication.

  • status: string, mandatory (see details as described in the Get One Authentication Result Method above).

  • details: JWS signed object (see details as described in the Get One Authentication Result Method above), optional.

  • requestedAttributes: JSON object (see details as described in the Get One Authentication Result Method above), optional.

Cancel Authentication Method

This method is used by a relying party to cancel an authentication request. The method is called using HTTP POST through the URLs below:

Environment

Endpoint

Environment

Endpoint

TEST

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

PRODUCTION

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

JSON Example for cancelAuthRequest

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

{ "authRef":"Authentication reference" }

  • authRef: string, mandatory . The value must be equal to an authentication reference previously returned from a call to the Initiate Authentication Method.

Example Request

If you wish to cancel an authentication request, follow these steps:

  1. Create the JSON structure {"authRef":"GOHPyJcoKLJ+zKCEy4abi6jOO+q5VK+S1+UO5OXRmOPu42ixvVnsVgs7ADYUfG8m"}

  2. Encode the JSON structure to Base64.

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

The HTTP body should be the following:

cancelAuthRequest=eyJhdXRoUmVmIjoiR09IUHlKY29LTEorektDRXk0YWJpNmpPTytxNVZLK1MxK1VPNU9YUm1PUHU0Mml4dlZuc1ZnczdBRFlVZkc4bSJ9

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.