for businessplayground
openid
eapi
rp management api

EAPI v3.4

Overview

EAPI is a protocol for delegating user authentication. Messages are passed between the Relying Party and Idfyed Server (hereafter "DServ") by redirects using GET or POST using end-user's browser as a proxy.

The protocol is signed to avoid tampering.

Authentication is initiated by the Relying Party sending an authentication request message, which DServ responds to after successful authentication or failure.

The protocol is authentication-method agnostic.

Getting Started

Before starting integration, the following information must be acquired from Idfyed:

  • The RP name for the application that is integrated. This is used as auth_companyname in the request. See section AuthnRequest below.
  • The RP MAC key. See section MAC computation below.

DServ is hosted at idfyed.com. The following integration URLs are used:

  • https://test.idfyed.com/main-eapi/begin: Test system used for integration and test.
  • https://login.idfyed.com/main-eapi/begin: Production system used for the production application.

User experience

EAPI redirection must not be done within an HTML frame, due to several reasons:

  1. The user must always be able to see the padlock in the address bar showing that the communication with DServ is encrypted and that the server can be trusted.
  2. Some browsers do not handle sessions well when run within frames.

Never use frames, idfyed.com should never be hidden within another site. DServ will always redirect the user back to the RP site after an authentication attempt, even though the user might have aborted the flow.

Flow

  1. The Relying Party web application (hereafter "application") generates a unique id, called "request ID", used to identify this authentication request.
  2. The application creates the other request parameters and computes the MAC using the secret key.
  3. The application redirects the user (AuthnRequest) to DServ, using GET or POST.
  4. DServ validates the request using the MAC.
  5. The user is authenticated by DServ.
  6. DServ redirects the AuthnResponse back to the application:
    • Successful authentication: The application receives a POST with the AuthnResponse to the return-url as described in the AuthnResponse chapter. The message must be validated according to Response message validation chapter.
    • Cancelled authentication: The application receives a GET with request ID to the cancel-url as described in the CancelResponse chapter.
    • Failed authentication: The application receives a GET with the failure message and request ID to the failure url as described in the RejectResponse chapter.

Message Specification

(Parameters marked with * are required.)

Message types

  • AuthnRequest - Sent from RelyingParty to Server. Starts authentication. Sent using HTTP POST or GET (redirect).
  • AuthnResponse - Sent from Server to RelyingParty. Ends authentication. Sent using HTTP POST.
  • RejectResponse - Sent from Server to RelyingParty. If authentication failed. Sent using HTTP GET (redirect).
  • CancelResponse - Sent from Server to RelyingParty. If authentication was cancelled. Sent using HTTP GET (redirect).

AuthnRequest

Parameter Name Description
auth_companyname* The ID of the company. Example: "acme"
auth_requestid* The request ID. Must be random string of at least 16 bytes length. Example: "a45b2ee710cfa743". Must be saved server-side for later use when validating the response message auth_inresponseto parameter.
auth_returnlink* The URL to where a successful response will be returned.
auth_cancellink* The URL to where the user will be redirected in case of cancelled authentication.
auth_rejectlink* The URL to where the user will be redirected in case of rejected authentication.
auth_authnmethod Names a specific authentication method to be used. Note that a Relying Party might not be authorized to use all different methods. If a method is specified using this parameter, usage of that method will be enforced by DServ. If a method is not requested, DServ will ask the user to select.
  • "diglias" - Idfyed
  • "bankid" - Swedish BankID with the bankid client on the same unit
  • "bankid-otherunit" - Swedish BankID with the bankid client on another unit
  • "norbankid" - Norwegian BankID
  • "telia" - Swedish Telia eID
auth_userid The user expected to authenticate. This parameter is used as a hint for relieving the user from manually entering the user ID. Since this is a convenience feature only, relying parties must always use the response auth_userid as the ID of the actually authenticated user. Supported authentication methods:

  • "bankid-otherunit" - auth_userid must be a 12 digit Swedish personal number.
  • "norbankid" - auth_userid must be a 11 digit Norwegian national identification number.
auth_responsedetails Requests meta information to be returned in the response. Used mainly for autditing and risk management. The following classes of response details are available:
  • "validity" - Requests information about the validity of the EID used.
  • "device" - Requests information related to the device used.
  • "pki" - Requests PKI level information, where applicable.
If multiple classes are requested, they are specified as a comma-separated list, e.g: 
auth_responsedetails=validity,device,pki
mac* Message authentication code. See Integration Notes below.
RelayState Any (opaque) value, which will simply be echoed back in the response. Must be Base64 encoded. This is normally some internal application state or deep link URL.

The AuthnRequest is sent to the integration URL, see Getting Started above.

Idfyed specific

If using the Idfyed authentication method specifically, there is an extended set of parameters that can be used in the AuthnRequest:

Parameter Name Description
auth_attributes An attribute specification controlling which attributes that are to be confirmed by the user in the Idfyed app. The value is a comma-separated list of attribute names. Example: 
auth_attributes=email,alias,givenName
If this parameter is omitted, the configuration default will be used. Parameter values including attributes not part of the RP contract will render an error. Also note that if using this parameter together with the auth_rp_ATTRIBUTE parameter, attributes included as value in auth_rp_ATTRIBUTE also needs to be included in auth_attributes to take effect.
auth_register Indicates whether app downloading instructions should be displayed in the authentication process.
  • "true": Display app downloading instructions.
  • "false": Don't display app downloading instructions. Default.
auth_rp_ATTRIBUTE Attribute to add to existing user with name ATTRIBUTE. This is only for Relying Parties authorized as a so called "ambassador". Authentications with one or more ATTRIBUTE set are called "Connect". Currently, only one value per attribute name is permitted.
auth_timestamp Timestamp that must be included for connect requests. The timestamp must be specified in the format: YYYY-MM-DD'T'HH:MM:SSZ and must be formatted according to ISO 8601. Example: 2015-03-05T08:54:43Z and 2015-03-05T08:54:43+01:00.

AuthnResponse

Parameter Name Description
auth_userid* The unique ID of the authenticated user. The value depends on the authentication method used, e.g
  • Idfyed: A UUID, e.g: "de305d54-75b4-431b-adb2-eb6b9e546013"
  • BankID/Telia: A Swedish personal number, e.g: "1212121212"
  • Norwegian BankID: a unique user ID
auth_inresponseto* The request ID. Must be validated by the requester upon reception.
auth_authnmethod* Names the authn method used. See authn_authnmethod in AuthnRequest.
auth_a_ATTRIBUTE Any ATTRIBUTE related to the user authentication. Which attributes that are included depends on the authentication method and what attributes the Relying Party is authorized to use. E.g:
  • Idfyed: Contact Idfyed for a set of attributes that may be used.
  • BankID:
    • givenname, capital letters
    • surname, capital letters
  • Telia
    • givenname
    • surname
  • Norwegian BankID:
    • name in the form Surname, Givenname
    • personalIdentificationNumber (optionally)
auth_detail_DETAIL Information returned as specified by auth_responsedetails. The following parameters are defined:
  • auth_detail_client_ip - The client IP. Class "device".
  • auth_detail_signature - The client signature created as part of the authentication. Class "pki".
  • auth_detail_ocsp - The OCSP response as returned by the CA system. Class "pki".
  • auth_detail_not_before - The notBefore field of the user certificate. See auth_timestamp for a decription of the format. Class "validity".
  • auth_detail_not_after - The notAfter field of the user certificate. See auth_timestamp for a decription of the format. Class "validity".
mac* Message authentication code. See Integration Notes below.
RelayState If included in request, the value will be sent back, unaltered.

RejectResponse

Parameter Name Description
error_code* A code identifying the error. Defined values are:
  • 100: "Unknown error", Base code for system errors.
  • 101: "Bad request"
  • 102: "Temporary error"
  • 20X: Authentication failed codes.
  • 604: User needs to Level Up, see Handling Level Up below.
error_message* Message describing the error. Aimed for system logs, not for user presentation.
inresponseto* The request ID. For reference.

CancelResponse

Parameter Name Description
inresponseto* The request ID. For reference.

Integration Notes

Response message validation

When a response message is received, the following actions are required in order to accept the user as authenticated:

  1. Ensure that the response includes all required parameters, i.e: auth_userid, auth_inresponseto, auth_authnmethod and mac.
  2. Make sure that the value of auth_inresponseto is equal to the server-side saved value of auth_requestid.
  3. Verify the value of the mac parameter according to MAC computation below.

If any of the above checks fail, the authentication must be rejected.

MAC computation

The MAC is computed as a HMAC MD5 of all the parameter names and values whose names are prefixed with "auth_". The parameter and value are connected in pairs using "=" and separated from other pairs with "&". The order of the pairs are alphabetical with regard to the parameter names. The HMAC is computed based on a company individual key and the MAC value must be sent using capital letters.

MAC computation algorithm

  1. Extract all parameters prefixed with "auth_".

  2. Sort them in alphabetical order.

  3. Only when verifying responses:

    Note This part applies to multiple same-name variable assignments like varA=1 and varA=2. Parameter assignments with a value containing a comma ",", like varX=1,2 and varY=3 is still one value ie this rule does NOT apply.

    1. The HTTP standard allows multiple parameter assignments like the example above where varA has both 1 and 2 as value, therefore this algorithm also must handle this case. In such a scenario it is important to include all parameters in the signature. Sort the values for each parameter in alphabetical order and concatenate the values with ",", i.e.: given the HTTP request: varA=2&varB=3&varA=1 would produce the result varA=1,2&varB=3. 1. SECURITY: It is important to add all values, not only one. (Consider the case where DServ includes one email value in the EAPI response, and where a man-in-the-middle appends a second value. In that case, if the application only includes the first value when verifying, the MAC will verify OK. However, if the application then (by accident) uses the second value, security is violated.) 1. Example: auth_a_email=john.doe@acme.org,john.doe@gmail.com.

  4. Serialize the parameters using "&" as separator, i.e: param_1=values_1&param_2=values_2&...&param_N=values_N.

    1. Example: auth_a_email=john.doe@acme.org,john.doe@gmail.com&auth_a_givenname=John&auth_a_sn=Doe.

  5. Using the key and the UTF-8 representation of the result from the previous step, compute a HMAC MD5.

  6. Convert the result from the previous step to an upper-case hex string.

Adding MAC to a request/response message

  1. Compute the MAC according to the computation algorithm above.
  2. Add the MAC to the message as a parameter named "mac".

Verifying MAC response message:

  1. Compute the MAC according to the computation algorithm above.
  2. Extract the "mac" parameter from the DServ message.
  3. Compare the computed MAC with the extracted MAC.
  4. If the MACs are equal, the message is authentic.

Handling Level Up

Applications requiring Diglias level 2 users also need to handle the case where level 1 users tries to login. If a level 1 user tries to login the process will fail with error code 604. In this case, the application needs to inform the user how to level up.

Changelog

Changes since EAPI v3.3

  • Added the EAPI request auth_responsedetails parameter and the corresponding EAPI response auth_detail_DETAIL parameters.

Changes since EAPI v3.2

  • Added the EAPI request auth_userid parameter.

Changes since EAPI v3.1

  • Added the EAPI request auth_attributes parameter.

Changes since EAPI v3.0

  • Unified the value set of the auth_authnmethod parameters in AuthnRequest and AuthnResponse. I.e, in EAPI v3.1, values of the parameter auth_authnmethod in AuthnResponse will no longer include the "authn-" prefix. E.g v3.1: auth_authnmethod=bankid, v3.0 auth_authnmethod=authn-bankid.

Changes since EAPI v2.0

  • Modified the MAC algorithm from only signing the attribute values, to sign parameters and values.

Changes since EAPI v1.1

  • The protocol is more clearly defined in terms of messages.
  • All parameters included in MAC computation is now prefixed with "auth_".
  • AuthnRequest parameter "orientation" is removed since it is no longer supported.
  • AuthnRequest parameter "authnmethod" is included as an optional parameter to be able to select a specific authn method.
  • AuthnResponse parameter "archiveid" is removed. It became superfluous as requestid/inresponseto was added.
  • AuthnResponse parameter "ssn" is renamed to "userid" as SSN is misleading.
  • AuthnResponse user properties such as "firstname" and "lastname" are generalized (by "auth-") to emphasize that other similar attributes may be added.
  • AuthnResponse parameter "authnmethod" is added in case the RelyingParty needs to know.
  • The AuthnResponse is now sent using HTTP POST due to the potentially large number of data sent.
  • Error information (error_code and error_message) is added to the ErrorResponse message.
  • The mac calculation is changed so that the key is no longer included as a part of the data, it's only serving as a key to the HMAC computation.
  • The mac calculation is more flexible du to the separation of the "auth_" parameters.