Technical Specification: Representee Feature

v1.0, 2025-02-13

• Technical Specification: Representee Feature
  • 1 Overview
  • 2 Enabling and configuring the GovSSO representee feature
  • 3 Requesting representation rights
    • 3.1 Authentication request with representation scopes
    • 3.2 Session update requests with representation data
      • 3.2.1 Session update requests with representee_list scope
      • 3.2.2 Session update request with representee.* scope
  • 4 Receiving representation data
    • 4.1 representee_list claims
    • 4.2 representee.{subject} claims
  • 5 Logout request
  • 6 Environments
  • Change history

1 Overview

This document is an addition to the core technical specification, specifying details about the optional representee feature.

Central authorisations management information system Pääsuke can provide client applications data about representation rights. An application can register as a client of Pääsuke service. In that case, that application can directly query representation rights (legal representation rights loaded from the Estonian e-Business Register and authorisations created from the Pääsuke user interface in eesti.ee) by calling Pääsuke X-Road services.

GovSSO offers brokering representation rights data from Pääsuke to its client application. That way, the GovSSO client application does not have to query Pääsuke X-Road services but can get representation rights data from GovSSO (that internally performs queries to Pääsuke X-Road services getDelegateRepresentees and getRepresenteeDelegateMandates). GovSSO does not display representation rights data to the end-user on the GovSSO page.

2 Enabling and configuring the GovSSO representee feature

For a client application to obtain representation rights via GovSSO, the representee feature must be explicitly enabled and configured for that client application on the GovSSO side.

1. Prerequisite: the client application must register as a client of Pääsuke service see registration form. GovSSO can broker representation rights only if the client has a contract with Pääsuke service.
2. For a GovSSO client application with a certain client_id, provide RIA with the following configuration values (on the initial client application registration form or later via help@ria.ee):

3 Requesting representation rights

GovSSO client application can request representation rights by adding representee.* and/or representee_list to the initial authentication request scope values.

• The representee_list scope enables the client application for the currently authenticated user to get the list representations (the list of all representees (persons the authenticated user is allowed to represent) together with the role codes of the authorisations). The client application can use this information to display representation choices to the end-user on the client application page. GovSSO does not use representee_list to display additional information to the end-user on the GovSSO page. The representee.* scope enables the client application to request a specific representation (the list of representation rights granted by a particular person to the authenticated user) after initial authentication. The client application can request details of a specific representation with session update requests.
• The representee.{subject} scope enables client applications to get detailed representation data of a person from the representee_list with session update requests.

3.1 Authentication request with representation scopes

A client application cannot request representation information later during the user’s session if it didn’t request representation scopes in the initial authentication request.

Example authentication request with representation scopes

GET /oauth2/auth?
 
redirect_uri=https%3A%2F%2Fclient.example.com%2Fcallback&
scope=openid%20representee.*%20representee_list&
state=hkMVY7vjuN7xyLl5&
response_type=code&
client_id=58e7ba35aab5b4f1671a&
ui_locales=en&
nonce=fsdsfwrerhtry3qeewq&
acr_values=substantial&

(for better readability, the parts of the HTTP request are divided onto several lines)

3.2 Session update requests with representation data

By default, representation data will not be carried over to subsequent ID Tokens. If needed, the client application should request representation data with the following session update requests.

3.2.1 Session update requests with representee_list scope

To get a new up-to-date representee_list, the client application needs to add scope to the session update request.

Example GovSSO session update request with representee_list scope

POST /oauth2/token HTTP/1.1
Host: govsso.ria.ee
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
 
grant_type=refresh_token&
refresh_token=1kYI7zBU_WEGoMCVxSraXLcuA906szL9hxC2qq7bgso.uq1VHIByywr0Q9fk-V9Jp1BmLLQihoqXctHHHY8b3bQ&
scope=openid%20representee_list

(for better readability, the parts of the HTTP request are divided onto several lines)

3.2.2 Session update request with representee.* scope

The client application must add representee.{subject} scope to the session update request to get detailed representation information for a specific representee.

The {subject} value must be the ID code of a natural person or the registry code of a legal person, prefixed by the country code of the person’s origin.

The client application can only request detailed representation information about representees listed in the representee_list. Only information about one representee can be requested at once.

Example GovSSO session update request with representee.* scope

POST /oauth2/token HTTP/1.1
Host: govsso.ria.ee
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
 
grant_type=refresh_token&
refresh_token=1kYI7zBU_WEGoMCVxSraXLcuA906szL9hxC2qq7bgso.uq1VHIByywr0Q9fk-V9Jp1BmLLQihoqXctHHHY8b3bQ&
scope=openid%20representee.EE12345678901

(for better readability, the parts of the HTTP request are divided onto several lines)

4 Receiving representation data

All information regarding representation will be provided to the client application in the ID Token in addition to the default GovSSO claims.

If the GovSSO client application has also enabled the optional Access Token configuration, then representee.* scope specific claims will be present in the Access Token as well. Note that Access Token does not hold representee_list claims.

The representee claim is omitted from ID Tokens and Access Tokens if the authenticated user represents oneself.

4.1 representee_list claims

If representee_list scope was requested with the initial authentication request or subsequent session update requests, the ID Token will hold additional information regarding users representations.

Example representee_list claims in an ID Token

...
"representee_list": {
    "status": "REPRESENTEE_LIST_CURRENT",
    "list": [
      {
        "sub": "EE12345678",
        "type": "LEGAL_PERSON",      
        "name": "AS Legal Person"
      },
      {
        "sub": "EE12345678901",
        "type": "NATURAL_PERSON"
        "given_name": "Max"
        "family_name": "Stonewood"
      }
    ]
},
...

4.2 representee.{subject} claims

If representee.{subject} scope was requested with session update requests, the ID Token will hold additional information regarding users specific representation.

Example representee.{subject} claims for a natural person in an ID Token

...
"representee": {
    "status": "REQUESTED_REPRESENTEE_CURRENT", 
    "sub": "EE12345678901",
    "type": "NATURAL_PERSON",       
    "given_name": "Max",
    "family_name": "Stonewood",
    "mandates": [
      {
        "role": "AGENCY-Q:Submit"
      },
      {
        "role": "AGENCY-Q:Edit"
      }
    ]
},
...

Example representee.{subject} claims for a legal person in an ID Token

...
"representee": {
    "status": "REQUESTED_REPRESENTEE_CURRENT",
    "sub": "EE12345678",
    "type": "LEGAL_PERSON",
    "name": "AS Legal Person",    
    "mandates": [
      {
        "role": "BR_REPRIGHT:ROLE_IN_BOARD"
      },
      {
        "role": "AGENCY-Q:Edit"
      }
    ]
},
...

5 Logout request

If the last valid ID Token, i.e., the id_token_hint value included in the logout request, contains a representee_list claim, then the user’s browser must be directed to the GovSSO logout endpoint with a POST request (using Form Serialization method) because the id_token_hint value may be longer than what the browser would support in a GET request. For the GovSSO logout endpoint, a POST request can always be used, even when the id_token_hint does not contain a representee_list claim. At the GovSSO logout endpoint, a GET request may only be used if the id_token_hint does not contain a representee_list claim.

6 Environments

GovSSO demo and production environments are integrated with Pääsuke over following X-road environments:

Change history