Authentication in Organisation ID Service
Initiate authentication method
This method is used by a Relying Party to initiate an authentication request. The method is intended for authentication in online contexts where the access to the Relying Party's service or application is initiated by the end user. The authentications are therefore short-lived — from the point of initiation, the user has a maximum of two minutes to confirm the authentication through a Freja eID mobile application. Only one active authentication may exist for any given end user at any given time. An attempt to concurrently start a second authentication, by the same or a different Relying Party, will cancel both initiated authentication requests.
The method is called using HTTP POST through the URLs below:
System | Method endpoint |
---|---|
Test | https://services.test.frejaeid.com/organisation/authentication/1.0/init |
Production | https://services.prod.frejaeid.com/organisation/authentication/1.0/init |
The parameter of the method is a Base64 UTF8-encoded JSON payload according to the following:
Parameter name | Value | |
---|---|---|
initAuthRequest | { "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:
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. If userInfoType is EMAIL or PHONE, interpreted as a string value of the email or telephone number of the end user, respectively. If userInfoType is SSN, then it must be a Base64 encoding of the ssnuserinfo JSON structure described below. If userInfoType is INFERRED, then userInfo must be set to: "N/A" because there is no data for the user to enter (see example below).
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. Currently supported attribute types are:
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. | |
ssnuserinfo | { "country":"Country of SSN", "ssn":"Social security number of the end user" } country: string, mandatory. Contains the ISO-3166 two-alphanumeric country code of the country where the SSN is issued. In the current version of Freja eID, one of: ''SE'' (Sweden), ''NO'' (Norway), ''FI'' (Finland), ''DK'' (Danmark).
| |
organisationId | "organisationId": { "identifier":"User's organisation identifier", "issuerFriendlyName":{"EN":" Relying Party Friendly Name", "SV":"Relying Party Friendly Name"}, "issuerCode":"Organisational code", "additionalAttributes":["OrganisationIdAttribute":{ "key":"attribute_key", "value":"attribute_value", "displayText":"attribute_name"} ] } |
Example request with userInfoType set to ORG_ID: |
---|
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:
The HTTP body should be the following (compact format, line broken for clarity only): initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJPUkdfSUQiLCJ1c2VySW5mbyI6InZlam9ibGEiLC AiYXR0cmlidXRlc1RvUmV0dXJuIjpbeyJhdHRyaWJ1dGUiOiJCQVNJQ19VU0VSX0lORk8ifSx7ImF0 dHJpYnV0ZSI6IlNTTiJ9XX0= |
Example request with userInfoType set to EMAIL: |
---|
If you wish to initiate authentication request for a user with an email address joe.black@verisec.com and request their name, surname, SSN and organisation identifier, follow these steps:
The HTTP body should be the following (compact format, line broken for clarity only): initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJFTUFJTCIsInVzZXJJbmZvIjoiam9lLmJsYWNrQHZ lcmlzZWMuY29tIiwiYXR0cmlidXRlc1RvUmV0dXJuIjpbeyJhdHRyaWJ1dGUiOiJCQVNJQ19VU0VSX0 lORk8ifSx7ImF0dHJpYnV0ZSI6IlNTTiJ9LHsiYXR0cmlidXRlIjoiT1JHQU5JU0FUSU9OX0lEX0lER U5USUZJRVIifV19 |
Example request with userIntoType set to PHONE: |
---|
If you wish to initiate authentication request for a user with a phone number '+46731234567':
The HTTP body should be the following: initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJQSE9ORSIsInVzZXJJbmZvIjoiKzQ2NzMxMjM0NTY3In0= |
Example request with userIntoType set to SSN: |
---|
If you wish to initiate authentication request for a user with an SSN '198905218072' and country 'SE':
The HTTP body should be the following: initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJTU04iLCJ1c2VySW5mbyI6ImV5SmpiM1Z1ZEhKNUlq b2lVMFVpTENKemMyNGlPaUl4T1RnNU1EVXlNVGd3TnpJaWZRPT0ifQ== |
Example request with userIntoType set to INFERRED: |
---|
If you wish to authenticate a user via a QR code:
The HTTP body should be the following: initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJJTkZFUlJFRCIsInVzZXJJbmZvIjoiTi9BIn0= |
Possible errors returned by the method are the following:
Return code | Explanation |
---|---|
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. |
If HTTP 200 is returned from the method, the following return value will be present in the body of the response:
JSON Response Value in body |
---|
{ "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 (see Authentication in Organisation ID Service#Get authentication results method below). |
Methods for retrieving authentication results
There are two methods that can be used for fetching authentication results: one that returns a single result for a specified authentication reference (authRef returned from a call to Authentication in Organisation ID Service#Initiate authentication method), and one that returns multiple authentication results. The latter is the preferred way of fetching results in situations where a Relying Party has many concurrent authentications in progress, as it reduces the number of polling requests.
Get one authentication result method
The method is called using HTTP POST through the URLs below:
System | Method endpoint |
---|---|
Test | https://services.test.frejaeid.com/organisation/authentication/1.0/getOneResult |
Production | https://services.prod.frejaeid.com/organisation/authentication/1.0/getOneResult |
The parameter of the method is a Base64 UTF8-encoded JSON payload according to the following:
Parameter name | Value | |
---|---|---|
getOneAuthResultRequest | { "authRef":"Authentication reference" } authRef: string, mandatory . The value must be equal to an authentication reference previously returned from a call to the Authentication in Organisation ID Service#Initiate authentication method. As mentioned above, authentications are short-lived and, once initiated by a Relying Party, must be confirmed by an end user within two minutes. Consequently, fetching the result of an authentication for a given authentication reference is only possible within 10 minutes of the call to Authentication in Organisation ID Service#Initiate authentication method that returned the said reference. |
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:
The HTTP body should be the following (compact format, line broken for clarity only): getOneAuthResultRequest=eyJhdXRoUmVmIjoiR09IUHlKY29LTEorektDRXk0YWJpNmpPTytxNV ZLK1MxK1VPNU9YUm1PUHU0Mml4dlZuc1ZnczdBRFlVZkc4bSJ9 |
Possible errors returned by the method are the following:
Return code | 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 following return value will be present in the body of the response:
JSON Response Value in body | |
---|---|
Response Body | { "authRef":"Authentication reference", "status":"Authentication status", "requestedAttributes":{ "basicUserInfo":{ "name":"User's name", "surname":"User's surname" }, "emailAddress":"User's primary email address", "allEmailAddresses":[ { "emailAddress":"User's email address" }, { "emailAddress":"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", "photo":"User's photo", "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 RP", "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" }, "registrationLevel":"User's registration level in Freja eID", "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":["OrganisationIdAttribute":{ "key":"attribute_key", "value":"attribute_value", "displayText":"attribute_name"} ] }, "relyingPartyUserId":"Unique user ID reserved for Relying Parties", "integratorSpecificUserId":"Unique user ID reserved for Integrators", "details":"JWS signed data, see below" } authRef: string, mandatory. The authentication reference of the authentication. status: string, mandatory. One of:
requestedAttributes: JSON object (see below), optional. Provides additional attributes about a user if required in attributestToReturn parameter in related initAuthRequest and the status was equal to APPROVED. details: JWS signed object (see below), optional. Provides details and evidence of the authentication if status was equal to APPROVED. |
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 registration level of user", "requestedAttributes":{ JSON object, see below. }, "timestamp":"Time when authentication confirmed by end user" } authRef: See authRef above. status: See status above. userInfoType: See userInfoType as described in Authentication in Organisation ID Service#Initiate authentication method. userInfo: See userInfo as described in Authentication in Organisation ID Service#Initiate authentication method. minRegistrationLevel: Minimum registration level of a user required by the Relying Party when the Organisation ID was added. requestedAttributes: JSON object, optional. See requestedAttributes below. 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. |
requestedAttributes |
{ "basicUserInfo":{ "name":"User's name", "surname":"User's surname" }, "emailAddress":"User's email address", "allEmailAddresses":[ { "emailAddress":"User's email address" }, { "emailAddress":"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", "photo":"User's photo", "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" } ], "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" }, "registrationLevel":"User's registration level in Freja eID", "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":["OrganisationIdAttribute":{ "key":"attribute_key", "value":"attribute_value", "displayText":"attribute_name"} ] }, "relyingPartyUserId":"Unique user ID reserved for Relying Parties", "integratorSpecificUserId":"Unique user ID reserved for Integrators", "customIdentifier":"Custom identifier set by the RP" } basicUserInfo: JSON object which contains user's name and surname. emailAddress: String, representing the user's email address. allEmailAddresses: List of JSON objects which contains all end user's registered email addresses. The list will contain the primary email address and up to 2 other email addresses user might have connected to their account. Email addresses will be randomly sorted. If the user does not have any additional email addresses registered, the list will contain only the primary email address. allPhoneNumbers: List of JSON objects which contains all end user's registered phone numbers. This list will contain up to 3 phone numbers the user might have connected to their account. If no phone number is registered for a given user, an empty list will be returned. dateOfBirth: String, containing date of birth in format: YYYY-MM-DD. age: Integer, calculated based on the user's date of birth. photo: String, Base64 encoded PNG bytes. addresses: List of JSON objects which contains one or more end user's addresses. If no address is registered for a given user, an empty list will be returned. Each object will contain the following information: country: String. Contains the ISO-3166 two-alphanumeric country code of the country where the user's address resides. ssn: JSON object which contains social security number and country. document: JSON object with information about the user's document used in registration. The object will contain the following information:
registrationLevel: the user's registration level in Freja eID, can be (BASIC, EXTENDED or PLUS) 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. relyingPartyUserId: String, represents a unique, user-specific value that allows the Relying Party to identify the same user across multiple sessions. integratorSpecificUserId: String, represents a unique, user-specific value that allows Integrators to identify the same user across multiple sessions regardless of the Integrated Relying Party service that the user is using. For more info, see Integrator Relying Party Management. customIdentifier: String, a unique, Relying Party-specific, user identifier, set by the Relying Party itself through the Custom Identifier Management.
|
Example data for APPROVED response, JSON response body:
{ "authRef":"12345-67890-abcdef", "status":"APPROVED", "details":"JWS content as per below", "requestedAttributes":{ "basicUserInfo":{ "name":"Joe", "surname":"Black" }, "emailAddress":"joe.black@verisec.com", "allEmailAddresses":[ { "emailAddress":"joe.black@verisec.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" "organisationIdIdentifier":"vejobla", "organisationId":{ "identifier":"vejobla", "issuerFriendlyName":{ "EN":" Freja eID", "SV":"FREJA"}, "issuerCode": null, "additionalAttributes":["OrganisationIdAttribute":{ "key":"USER_ID", "value":"123456789", "displayText":"ID"} ] }, "relyingPartyUserId":"94039a98c8d", "integratorSpecificUserId":"54059a95c8d" }
Field | Value |
---|---|
Certificate info | See above. |
Header | See above. |
Payload | { "authRef":"12345-67890-abcdef", "status":"APPROVED", "userInfoType":"EMAIL", "userInfo":"joe.black@verisec.com", "requestedAttributes":{ "basicUserInfo":{ "name":"Joe", "surname":"Black" }, "emailAddress":"joe.black@verisec.com", "..." }, "timestamp":1584701027510 } |
Final JWS (compact format, line broken for clarity only) | eyAiYXV0aFJlZiI6IjEyMzQ1LTY3ODkwLWFiY2RlZiIsICJzdGF0dXMiOiJBUFBST1ZFRCIsICJ1c2VySW5mb1R5cGUiOiJFTUFJTCI sICJ1c2VySW5mbyI6ImpvZS5ibGFja0B2ZXJpc2VjLmNvbSIsICJyZXF1ZXN0ZWRBdHRyaWJ1dGVzIjp7ICJiYXNpY1VzZXJJbm ZvIjp7ICJuYW1lIjoiSm9lIiwgInN1cm5hbWUiOiJCbGFjayIgfSwgImVtYWlsQWRkcmVzcyI6ImpvZS5ibGFja0B2ZXJpc2VjLmNvbS IsICJhbGxFbWFpbEFkZHJlc3NlcyI6WyB7ICJlbWFpbEFkZHJlc3MiOiJqb2UuYmxhY2tAdmVyaXNlYy5jb20iIH0sIHsgImVtYWls QWRkcmVzcyI6ImpvZWJsQGRvbWFpbi5jb20iIH0gXSwgImFsbFBob25lTnVtYmVycyI6WyB7ICJwaG9uZU51bWJlciI6Iis0NjAw MDAwMDAwIiB9LCB7ICJwaG9uZU51bWJlciI6Iis0NjExMTExMTExIiB9IF0sICJkYXRlT2ZCaXJ0aCI6IjE5ODUtMTEtMTciLCAiYW dlIjozNiwgImFkZHJlc3NlcyI6WyB7ICJjb3VudHJ5IjoiU0UiLCAiY2l0eSI6IlN0b2NraG9sbSIsICJwb3N0Q29kZSI6IjExMTIwIiwgIm FkZHJlc3MxIjoiQy9PIEpvZSBCbGFjayIsICJhZGRyZXNzMiI6IlZpc2RvbXNnYXRhbiA1NSIsICJ2YWxpZEZyb20iOiIyMDIwLTAzLT E5IiwgInR5cGUiOiJSRVNJREVOVElBTCIsICJzb3VyY2VUeXBlIjoiR09WRVJOTUVOVF9SRUdJU1RSWSIgfSwgeyAiY291bnRyeS I6Ik5PIiwgImNpdHkiOiJPc2xvIiwgInBvc3RDb2RlIjoiMDAwMSIsICJhZGRyZXNzMSI6IlAuTy4gQm94IDQ1NiIsICJ2YWxpZEZyb2 0iOiIyMDIwLTAzLTE5IiwgInR5cGUiOiJQT1NUQUwiLCAic291cmNlVHlwZSI6IkdPVkVSTk1FTlRfUkVHSVNUUlkiIH0gXSwgInNzb iI6eyAic3NuIjoiMTk4NTExMTcwMDQwIiwgImNvdW50cnkiOiJTRSIgfSwgInJlZ2lzdHJhdGlvbkxldmVsIjoiUExVUyIsICJyZWx5aW 5nUGFydHlVc2VySWQiOiI5NDAzOWE5OGM4ZCIsICJpbnRlZ3JhdG9yU3BlY2lmaWNVc2VySWQiOiI1NDA1OWE5NWM4ZCIsIC JjdXN0b21JZGVudGlmaWVyIjoidmVqb2JsYSIsCsKgIMKgIMKgICJjb3ZpZENlcnRpZmljYXRlcyI6ewoidmFjY2luZXMiOiB7CiJjZX J0aWZpY2F0ZSI6ICJIQzE6TkNGT1hOJVRTTUFITi1IVk44SjdVUU1KNC8zUlpMTTUyWEdQMVdHMkQ1OCpJWEY1OTVUWFIzO FdBQlJNQjU3Ri84WCpHM005SlVQWTBCWlc0Oi5BNjNITk5WUipHMEM3UEhCTzMzUlcwNUxCUE9GIFFUWUYzNEhHT0lIIDh MKzZIMVNGKzVGLzNFMUpBRi43NSBKRFhJMDNMOVpJNFE1JUgwQU44Q0owUFpCSVRIUCtQUlJNSlZVTSBJL1BTTSVHQTh JTSVPJUtJKlcwIC5VUSpOIFJQLStSMllCVjQ0QyRCWEdETzk4OjBMUEhONkQ3TExLKjJIOS04OVVWLTBMLzpJUy1POlM5VVo0 K0ZKRSA0WTNMTC9JSSAwT0M5U1gwKypCODVUJTYyKjVQWkQ1Q0M5VDBIJTpLNVFOWC9HSlpJSTdKU1ROQjk1KzE2TEVU RjROLlNTLlBLSVhSLlVJQVlVSDJXVlFJMFRIWFpRLko5MSBGSSVCMkxHN1BHJSBCL1VJMllVNU1BWFNHK1czNFBJUUpBWkdB MjpVRyVVMkU0QVNOTUg4TS00MDVBMU9LLVVLVkNGQjNMQi42REpQSEJTMTVDL0tOS000JElJWCpCMUpTOUFDOTlORTd QSFRSTysySSo1QzZFQTJVJCA4QzJTVCBJRSVOMSsyNFY3TEQxTFpCQU1BUzMwNldETzEiCn0sCiJ0ZXN0cyI6IHsiY2VydGlm aWNhdGUiOiJIQzE6TkNGT1hOJVRTTUFITi1IM080OlBWSCBBSjJKJDlKMElJNllKIDQzU0xHL0VCTkcyTjRGQk9NJFY0Ok5RQSB NOlVDKkdQWFM0TVpLSFpBIEtFN0VDMSAzSzlMVDRENCVLKipJUjFMJTpLRVY0OTlURVc2M1pDRDdMVVoyMzRKVFBWRkhIQ lk0Ty1PMEcxM0hIMC1LJUlIN1k0L1g4Nk1PQiVSSERNLi1CNi9EMEpBUVRVOEQyJUgwQU44U0owNllCVVNNQUw4Oko1U0g2LU c5KkU5LiQwNUc5MEYzSFpJNVZBJTNLUVlKWDFKOk5LMkFEVlRBQVpJNjZKIE9LUU1JME9JU1ZCRk9KVlRBMUhBLVhJUkNJI E9LJUlKNVFCUDdKVTdCSllKKklKNU9JLVlJRTQ2TzkzWE1SOiBLUyROOUhTNS1RSitQQStRSSVLNCRON0JNSStRViVONCtPO CVNTUcyOUFGNkxGQjgxUU1LUStNTi9RMTlRRThRIFBPRE9GJDZSTlFRM1k3NFhMMS9MSk85VVVNIFFVUS9NTjo0MzU2KkJ XJCVMKy1KTi5OIExUQldPNTpRTitBMzFVS1hQUk9TTlBTK0RXR0RJOEVIJTJMVUkyTy9FR1lJWVMyR1NTJThTLzQwQVFDSTIif SwKInJlY292ZXJ5IjogeyAiY2VydGlmaWNhdGUiOiJIQzE6TkNGT1hOJVRTTUFITi1IRk40VFRDNCBTSldLWio5R0JILiBNVTk2NU hSTFg4M0xRNTVVVFNKVlFPSVZVSzFKWlpQUUEzRFA0T1c2MzFBWDVRTTlJRlkxT1NNTlYxTDhWTkY2QVlNRTBGOk5FM0tV RDoxM1pNNTo2RUw2RSU2MFQ5MzJRLlJUUkg5L1VQTkY2N0o2UVc2T1ZRT1I2K0c5MC5HLVI1NFcxLlVJMlBIVUlFICQ0WkpK KiVDTjFUVEI1Qy1PVEYxSiozVEZIMlY0MkYxQ09UJEhGQypJVVo0K0ZKRSA0WTNMTC9JSSAwSEpQN05WREVCMTJKRCoyRD BISDc4JFpKKkRKV1A0Mlc1OllQSEpVVFJNOE9JOVlPIExFM1VRNU1BMVRIOEwyQ1BJR1NVSFBNVStWQVdPMk84VStWSCpG WVpRIEg5OTJXICVKTVNHVVZQUVJISVkxKyBIMU8xNlAzKjdVRi5KSjhDN1hCL09JRkQ2NSpWMFdJKjlVVTNFSllSSlg1SDRVNjp WK1lUR1FGT1BFNlhWViVMVFVLSTdVUEZEQ1FVJEpWRjhDUTo1RThVT0hSJStWL0ZDOSo4IFdNOCRKVjIwTSRPODMiCiAgICA gICAgIH0sCiJhbGxvd2VkIjogdHJ1ZQp9CsKgIMKgfSwgInRpbWVzdGFtcCI6MTU4NDcwMTAyNzUxMCB9 |
Get authentication results method
The method allows a Relying Party to fetch the results of multiple outstanding authentications. It is our recommendation that relying parties generally use the aggregate method, as it is more efficient and reduces network traffic. This is the default behaviour of client libraries supplied by Freja eID.
The method is called using HTTP POST through the URLs below:
System | Method endpoint |
---|---|
Test | https://services.test.frejaeid.com/organisation/authentication/1.0/getResults |
Production | https://services.prod.frejaeid.com/organisation/authentication/1.0/getResults |
The parameter of the method is a Base64 UTF8-encoded JSON payload according to the following:
Parameter name | Value | |
---|---|---|
getAuthResultsRequest | { "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:
The HTTP body should be the following: getAuthResultsRequest=eyJpbmNsdWRlUHJldmlvdXMiOiJBTEwifQ== |
Possible errors returned by the method are the following:
Return code | Explanation |
---|---|
1004 | You are not allowed to call this method. |
1008 | Unknown Relying Party. |
1200 | Invalid or missing includePrevious parameter. |
If HTTP 200 is returned from the method, the following return value will be present in the body of the response:
JSON Response Value in body | |
---|---|
Response body | { "authenticationResults":[ { "authRef":"Authentication reference", "status":"Authentication status", "relyingPartyUserId":"Unique user ID reserved for Relying Parties", "details":"JWS signed data, see below", "requestedAttributes":{ "basicUserInfo":{ "name":"Joe", "surname":"Black" }, "emailAddress":"joe.black@verisec.com", "dateOfBirth":"1987-10-18", "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":"198710180040", "country":"SE" }, "document" : { "type":"PASS", "country":"SE", "serialNumber":"XA0000001", "expirationDate":"2027-01-01" }, "registrationLevel":"EXTENDED", "organisationIdIdentifier":"vejobla", "organisationId":{ "identifier":"vejobla", "issuerFriendlyName":{ "EN":" Freja eID", "SV":"FREJA"}, "issuerCode": null, "additionalAttributes":["OrganisationIdAttribute":{ "key":"USER_ID", "value":"123456", "displayText":"ID"} ] }, "relyingPartyUserId":"94039a98c8d", "integratorSpecificUserId":"54059a95c8d" { "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. One of:
details: JWS signed object (see details as described in the Authentication in Organisation ID Service#Get one authentication result method above), optional. requestedAttributes: JSON object (see details as described in the Authentication in Organisation ID Service#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:
System | Method endpoint |
---|---|
Test | https://services.test.frejaeid.com/organisation/authentication/1.0/cancel |
Production | https://services.prod.frejaeid.com/organisation/authentication/1.0/cancel |
The parameter of the method is a Base64 UTF8-encoded JSON payload according to the following:
Parameter name | Value | |
---|---|---|
cancelAuthRequest | { "authRef":"Authentication reference" } authRef: string, mandatory . The value must be equal to an authentication reference previously returned from a call to the Authentication in Organisation ID Service#Initiate authentication method. |
Example request: |
---|
If you wish to fetch multiple authentication results, follow these steps:
The HTTP body should be the following (line broken for clarity only): cancelAuthRequest=eyJhdXRoUmVmIjoiR09IUHlKY29LTEorektDRXk0YWJpNmpPTytxNVZLK1MxK1VP NU9YUm1PUHU0Mml4dlZuc1ZnczdBRFlVZkc4bSJ9 |
Possible errors returned by the method are the following:
Return code | 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.