EAPI v3.4

Overview

EAPI is a protocol for delegating user authentication. Messages are passed between the Relying Party and Diglias 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:

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

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:

Message Specification

(Parameters marked with * are required.)

Message types

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" - Diglias
  • "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_useridas 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.

Diglias specific

If using the Diglias 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 Diglias 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
  • Diglias: 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:
  • Diglias: 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.)
      2. 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.

Changes since EAPI v3.3

Changes since EAPI v3.2

Changes since EAPI v3.2

Changes since EAPI v3.0

Changes since EAPI v2.0

Changes since EAPI v1.1