Integrator Relying Party Management

Owned by Former user (Deleted)
Nov 06, 2024
3 min read


This page:

Services

Management

Best practices:


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, Signature or Organisation ID), when they are acting on behalf of Integrated RPs. This parameter must be in URL-encoded form. When acting on their own behalf, Integrators may not make calls to Freja eID services by default.

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 authentication and signature methods and possible errors, refer to Authentication or Signature services respectively. Also, the additional POST parameter is needed if the Integrator RP wishes to add and Organisation ID for a user on behalf of their customer. For more information about Organisation ID and how to initiate authentication and signature requests using that user identifier, please refer to Organisation ID Service. 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@freja.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, Signature and Organisation ID services, are the following:

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



Go to: