Integrator Relying Party Management

 

Table of contents

Services

Management

 

Overview

As can be seen in the Authentication and Signature services, identification of Relying Parties towards Freja eID services is achieved through SSL/TLS with client authentication. This, however, may present an issue for Relying Parties that act on behalf of their own customers, i.e. other organisations, most likely with their own branding and the requirement that the end user, consuming their services, is aware of the organisation she is interacting with.

In order to avoid the complexities of having such Relying Parties manage multiple SSL/TLS certificates, one per customer organisation, Freja eID allows annotation of such Relying Parties as "Integrators". Integrator RPs are allowed to act on behalf of their customer organisations by utilizing a single SSL/TLS client certificate, while passing in the identity of the customer organisation as a parameter to API calls.

Consequently, given the branding and presentation requirements towards end users within Freja eID, organisations on whose behalf Integrator RPs act on must be registered with Freja eID as ''Integrated Relying Parties''. They cannot make use of Freja eID services directly but rather through the Integrator RP they are associated with. This also simplifies billing information, as within the invoices that will be sent to Freja eID Integrator RPs, a line item will be presented for each customer that is configured as an Integrated RP.

Production checklist for Integrator RP

In order to use Freja eID in a production environment as the Integrator RP, you must fulfil the following:

  • Sign a contract allowing your organisation to access the production Freja eID services.
  • Provide Freja eID with a logo suitable to represent your organisation in the mobile application, as well as a display name and a short description. Please note that:
    • The logo must be delivered in one of the vector file formats: AI (Adobe Illustrator Artwork), EPS (Encapsulated PostScript) or editable PDF (Portable Document Format). The preferable format is AI (filename extension is .ai).
    • The display name is restricted to maximum length of 20 characters and the description should not exceed 75 characters. The URL can be up to 100 characters long.
  • For each Integrated RP you act on behalf of, provide Freja eID with the same information as mentioned above: logo, display name, URL and short description.
  • Obtain an SSL client certificate providing you access to the Freja eID production environment.
  • Import Freja eID Production root certificate as trusted into the trust store of your application.

Initiating requests as an Integrator RP

For each Integrated RP, as well for the Integrator itself, Freja eID generates a unique identifier called relyingPartyId. The Integrator RP needs to pass this identifier as an additional POST parameter in each call to Freja eID services (Authentication or Signature), wheter they are acting as themselves or on behalf of an Integrated RP. 

Below you can see the example authentication request initiated by an Integrator RP acting on behalf of their customer. For detailed information about the structure of all the methods and possible errors, refer to Authentication or Signature services respectively. Read also the General information about Freja eID RESTful APIs

Example request

If you wish to initiate authentication request as an Integrator RP for a user with the email address joe.black@verisec.com on behalf of an organisation (Integrated RP) with a relyingPartyId ''integratedRelyingParty'', the initAuthRequest call will look like this (compact format, line broken for clarity only):

initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJFTUFJTCIsInVzZXJJbmZvIjoiam9lLmJsYWNrQH
ZlcmlzZWMuY29tIn0=&relyingPartyId=integratedRelyingParty


 

Possible errors returned to the Integrator RP, in addition to the ones listed in Authentication and Signature services, are the following:

Return code
Explanation
1008Unknown Relying Party.
1011Invalid relyingPartyId.