Identity Service Specification

Note: For the use of Developer Assets, these Terms and Conditions apply. Please also read the Requirements Notation and Conventions.

1. Overview

This specification describes the Identity Service. It builds upon the IDP Core Specification and leverages OpenID Connect and OpenID Connect for Identity Assurance.

Every IDP is also an OpenID Connect Provider (OP) which enables websites and apps, designated as Relying Parties (RPs), to leverage user and account data of the bank’s existing online banking user base.

Since “OpenId Connect is a simple identity layer on top of the OAuth 2.0 protocol”[1], the OP shares the authorization and token endpoints with the AS building block of the same IDP. OpenID Connect is simply “turned on” by passing a scope value openid in the Authorization Request.

1.1. OpenID Connect Profile

All IDPs MUST implement the following features as defined in the OpenID Connect specification and complementing specifications:

  • Request parameter id_token_hint in order to allow for a re-login using a user identity known to the Relying Party.

  • Request parameter nonce in order to prevent code injection attacks.

  • Request parameter prompt, with at least the values none, login and consent supported.

  • Request parameter acr_values in order to allow RPs to influence the authentication methods used by the IDP.

  • Request parameter claims in order to allow RPs to specify the claims they want to obtain in a fine grained fashion (data minimization) and to determine the way they are delivered (user info vs. ID token).

  • ID Tokens MUST be signed using the algorithm RS256.

  • ID Tokens MUST contain at least the following claims: iss, sub, aud, nonce, exp, iat.

  • Bare public keys: The IDPs MUST publish their public keys as bare JWK keys (which MAY also be accompanied by their respective X.509 representations).

  • Discovery document: IDPs MUST support retrieval of the OpenID Provider Configuration Information as specified in OpenId Connect Discovery, Section 4, based on the Issuer URL.

  • The openid-configuration document MUST contain the following values:

    • issuer

    • jwks_uri - MUST point to the location of the JWKS keys used to sign ID Tokens.

    • authorization_endpoint

    • token_endpoint

    • userinfo_endpoint

    • claims_supported - this value MUST advertise all claim values supported by the particular IDP in order to allow RPs to detect feature support in an early stage of the process.

    • scopes_supported - this value MUST advertise all scope values supported by the particular IDP in order to allow RPs to detect feature support in an early stage of the process.

    • acr_values_supported - this claim publishes all Authentication Context Class References supported by the OP, at least the ACRs values as specified in section Authentication Policy.

    • token_endpoint_auth_methods_supported - value MUST contain self_signed_tls_client_auth.

    • id_token_signing_alg_values_supported - value MUST contain RS256.

    • verified_claims_supported

    • trust_frameworks_supported

    • evidence_supported

    • id_documents_supported

    • id_documents_verification_methods_supported

    • claims_in_verified_claims_supported

IDPs MAY support the scope value offline_access and issue refresh tokens allowing the RP to obtain fresh access tokens and access user information even in situations where the user is not present.

1.1.1. User Consent Handling

In case of scope values representing OpenID Connect claim sets, it is not sufficient to just ask the user for consent to grant the RP access to the OP’s UserInfo Endpoint. The OP MUST present the effective claims (user and/or account data) the RP asked for to the user.

The IDP SHOULD present the actual values of the claims in the consent screen along with the option to adjust the values (if applicable).

The OP MUST ask the user again for consent if the purpose of the user claim usage with the RP has changed (see recital (32) and Art. 5 (1) GDPR). In this particular case, the RP MUST indicate this change to the OP by sending the request parameter prompt with a value of consent with the authorization request.

2. Login (ID Federation)

In this use case, the RP delegates the authentication process to the OP and relies on the user id asserted by the OP to log in the user locally. The RP will typically maintain a local user account, which is identified by the user id obtained from the OP.

The main benefit from a user’s perspective is an easy login without the need to set up a new password (or generally speaking any kind of credentials) with the RP. The RP, on the other hand, can rely on the fact that there is a verified person behind every user account asserted by a IDP (prevention of fake accounts).

The RP requests the login using the scope value openid.

RPs MUST also utilize the request parameter nonce to protect the flow from code injection.

The results of a successful transaction are carried in an ID Token.

The OP MUST include the following claims in every ID Token:

  • iss: the issuer URL of the respective IDP

  • sub: the user id of the respective user account

  • aud: the client id of the actual RP

  • exp: time when the ID token expires

  • iat: time at which the JWT was issued

  • nonce: MUST be the same value as used in the request, otherwise the RP MUST treat the transaction as compromised

  • acr: MUST be present if requested by the RP or if the RP requested a certain ACR, the value MUST be one of authentication class references described in Authentication Policy.

The RP MUST verify ID tokens according to the verification procedure described in OpenID Connect Core 1.0.

Example 1. ID Token as described in OpenID Connect Core 1.0. 
{
   "iss":"https://accounts.example-bank.com/issuer",
   "sub":"676768668767565456465678798",
   "aud":"yes.com:3630BF72-E979-477A-A8FF-8A338F07C852",
   "nonce":"n-0S6_WzA2Mj",
   "exp":1311281970,
   "iat":1311280970,
   "acr":"https://www.openbanking.verimi.cloud/acrs/online_banking"
}

As the objective of the login with ID federation is to securely recognize the same user again in subsequent login transactions, there is basically no need to transfer any other user data from OP to RP. However, it is possible to combine login with access to user data as described in User Information and Verified Person Data. It might also be combined with inquiries to access further services on behalf of the user.

2.1. User Identifiers

The OP MUST ensure that the user id provided in the sub claim is immutable to ensure perpetual access to the respective RP accounts. E-mail addresses or phone numbers DO NOT meet this requirement. Bank account numbers SHOULD NOT be used for this purpose, especially in situations where more than a single person has access to a certain bank account. Moreover, this might also result in privacy issues. It is recommended to use automatically created technical identifiers without any dependency on other data elements (e.g., account number).

The IDP MUST be able to determine the user account based on the sub value attested towards RPs. This is a pre-requisite to determine the user identified by an id_token_hint request parameter and to be able to process support requests.
The RP MUST build the identifier used to look up the local user account by using the iss and the sub as a composite key (e.g., by concatenating using a defined separator character), since the sub is guaranteed to be unique within the scope of a particular OpenId Connect OP only. RPs MUST NOT use other claims to map the user’s identity with the OP to its identity with the RP. For example the e-mail address is not suited for that purpose.

To protect the end-user from a possible correlation among RPs, the use of a Pairwise Pseudonymous Identifier (PPID) as the sub (subject) SHOULD be considered.

2.2. User Account Migration

When a user logs into an RP using for the first time, the RP typically stores the user identifier (combination of sub and iss - see above) and binds it to the user’s local account so the RP will be able to recognize the user account on subsequent logins with .

There are cases in which the issuer and/or the subject of the user account change, for example if two banks merge and in this context also merge their customer’s online banking accounts.

To support such cases, the IDP MUST provide the RP with a pointer to a previous user identifier for the same user utilizing the “aka” claim as described in the section User Account Migration.

2.3. Authentication Policy

In case of OpenID Connect, the RP may explicitly ask the OP to perform the authentication on a certain level.

These levels are represented by the following authentication context class references:

  • https://www.openbanking.verimi.cloud/acrs/online_banking: the user is authenticated using the primary online banking credentials, e.g., a pin code or a password. The user either entered her username or the username was automatically determined based on data from previous logins.

  • https://www.openbanking.verimi.cloud/acrs/online_banking_sca: the user is authenticated using two independent factors according to the definition in PSD2 RTS. The user either entered her username or the username was automatically determined based on data from previous logins.

An RP MAY request a certain or a set of authentication policies using the request parameter acr_values (see OpenId Connect). The OP MUST try to conduct a user authentication fulfilling one of the requested authentication policies and MUST attest the policy employed successfully in the ID token claim acr.

Example 2. Authentication Request with acr_values. 
GET /authorize?
   response_type=code
   &scope=openid
   &client_id=yes.com:3630BF72-E979-477A-A8FF-8A338F07C852
   &state=af0ifjsldkj
   &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
   &acr_values=https%3A%2F%2Fwww.yes.com%2Facrs%2Fonline_banking_sca HTTP/1.1
Host: server.example.com
Example 3. ID Token with acr claim. 
{
   "iss":"https://accounts.example-bank.com/issuer",
   "sub":"676768668767565456465678798",
   "aud":"yes.com:3630BF72-E979-477A-A8FF-8A338F07C852",
   "nonce":"n-0S6_WzA2Mj",
   "exp":1311281970,
   "iat":1311280970,
   "acr":"https://www.openbanking.verimi.cloud/acrs/online_banking"
}

The RP MAY ask the OP to adhere to the requested acr values by specifying the acr as essential claim as described in OpenID Connect. In this case, if the OP cannot meet these requirements, it MUST treat the transaction as failed authentication attempt and respond to the RP with an error code authentication_failed.

Every OP MUST publish its supported acr values in its openid configuration using the acr_values_supported parameter.

IDPs MUST only use dynamic TAN methods. Static TAN methods, such as iTAN, MUST NOT be used.
Example 4. ID token enriched by data regarding the authentication process. 
{
   "iss":"https://accounts.example-bank.com/issuer",
   "sub":"100465256161630236400723",
   "aud":"yes.com:3630BF72-E979-477A-A8FF-8A338F07C852",
   "nonce":"n-0S6_WzA2Mj",
   "exp":1311281970,
   "iat":1311280970,
   "auth_time":1311280969,
   "acr":"https://www.openbanking.verimi.cloud/aal/online_banking_sca"
}

The acr value indicates that the OP successfully performed SCA for the user with the user id (sub) 100465256161630236400723. The claim auth_time carries the time when the authentication occurred.

The OP MUST ask the user for consent before it reveals the user id to a particular RP. The OP SHOULD persist this consent and provide RPs with the user id in subsequent transactions without the need to ask the user for consent again. If the OP stores the consent persistently, it MUST also offer a service to the user to inspect and potentially revoke such consents.

2.5. Further Requirements

The OP MUST support the request parameter prompt with the value of none. This value tells the OP to suppress any user interaction. This might result in an error if the OP would need to interact with the user in order to process the request properly. Examples are

  • the OP needs to authenticate the user interactively (error login_required)

  • the OP needs to gather the user’s consent (error consent_required)

  • In other cases, the OP might respond with the error interaction_required.

3. User Information

The OPs MUST allow RPs to request user information (claims) belonging to the user’s online banking account. These user claims are provided without attestation of the underlying verification status, i.e., from the perspective of a RP this is unverified user data.

IDPs offer explicit attestation via the verified person data premium service defined in Verified Person Data. However, an RP could use the basic user information service and try to derive an implicit attestation from the fact that the data is provided by a certain provider without using the premium service. OPs SHOULD therefore ensure the data provided without attestation cannot be augmented with an implicit attestation. This can be achieved by allowing users to modify the claim values in the authorization process.

Claims are requested using the claims request parameter, which allows a fine-grained definition of the desired claims. It also allows the RP to determine whether the claims are provided via the UserInfo endpoint or within the ID Token.

3.1. Handling Unknown/Unsupported Claims

The claims every client is permitted to request are defined by its policy in the platform (property allowed_claims). If a client requests claims it is not permitted to use or a claim that is not known to the OP, the OP acts according to the following table:

Claim in allowed_claims not in allowed_claims

Claim is defined and supported

deliver claim value

error response unauthorized_client

Claim is defined but not supported

ignore claim

error response unauthorized_client

Claim is not defined and not supported

ignore claim

ignore claim

A claim is defined if it is listed in this specification or if it is a custom claim (see Custom Claims).

The error unauthorized_client refers to the OAuth error code.

In all cases, all claims from the request MUST be listed in the mediation records' requested_claims element (see Billing Mediation).

3.2. Claims

This is the list of user-related claims utilized by :

Claim Type Description MTI

email

string

see OpenID Connect, section 5.1

yes

email_verified

boolean

see OpenID Connect, section 5.1

no

phone_number

string

based on OpenID Connect, section 5.1, representation of the phone number according to E.164 in the format

"+" + <CC> + <NDC> + <SN>

regular expression: ^\+[[:digit:]]{2,15}$

Example: +441134960000

It is recommended to provide the RP with the preferred mobile phone number of the user.

yes

phone_number_verified

boolean

see OpenID Connect, section 5.1

true if the bank successfully verified the user’s control of the particular phone number (e.g., by sending a one time code via text message)

no

given_name

string

see OpenID Connect, section 5.1

yes

family_name

string

see OpenID Connect, section 5.1

yes

gender

string

The gender selected by this person, male, female, or intersex. It might be set to a custom value.

see OpenID Connect, section 5.1

no

salutation

string

end-user’s salutation, e.g., Mr.

see OpenID Connect for Identity Assurance

no

title

string

end-user’s title, e.g., Dr.

see OpenID Connect for Identity Assurance

no

place_of_birth

JSON object

end-user’s place of birth as defined in OpenID Connect for Identity Assurance

NOTE: In the context of this specification, the field country is optional.

yes

birthdate

string

ISO 8601:2004 YYYY-MM-DD format, e.g., 2000-01-01

yes

nationalities

string array

ICAO 2-letter codes, e.g., DE

see OpenID Connect for Identity Assurance

yes

address

JSON object

see OpenID Connect, section 5.1.1

In the context of this specification, the elements street_address, locality, and postal_code are required.

yes

https://www.openbanking.verimi.cloud/claims/ tax_id

string

tax identification number

no

https://www.openbanking.verimi.cloud/claims/ preferred_iban

string

IBAN of the debit account the users wants to use for transactions. How this account is determined (if there are more than a single account associated with the user’s online banking account) is at the discretion of the IDP. The IDP might ask the user within the flow but should utilize sensible default and preferences in order to make the user experience as frictionless as possible.

no

https://www.openbanking.verimi.cloud/claims/ delivery_address

JSON object

If available, an address that can be used to mail physical goods to the user. Contents like the address claim as specified above.

no

txn

string

see OpenID Connect for Identity Assurance. Note: This claim is available independent of verified claims.

yes

3.3. Custom Claims

OPs and RPs can agree to convey additional user information in so-called “custom claims” as part of the identity information. It is up to the OPs and RPs to mutually agree on the contents and semantics of these claims. Custom claims can be used, for example, to transport internal user identifiers stored at the OP that can be used by the RP.

Custom claim names MUST start with an HTTPS URI that is under the control of the OP, e.g., https://bank.example/claims/. The domain MUST be registered on the OP or a cooperating party.

Custom claims can be requested using the claims parameter.

4. Verified Person Data

OPs MUST support the attestation of verified person data. This attestation consists of

  • the verified person data itself,

  • data about the verification process used to bind a person’s identity to a certain Online Banking Account, and

  • data about the actual authentication process used to ensure the binding between the user account and the actual user.

The latter data is carried using the acr claim as described in Authentication Policy.

The verified person data and the data about the verification process is requested and represented using a subset of OpenID Connect for Identity Assurance.

4.1. Request Syntax

Requests to OPs MUST follow the scheme described in the following. Claims and verification data are only returned from the OP if explicitly requested by the RP.

Example 5. Request Syntax for Verified Person Data 
{
   "verified_claims":{ (1)
      "verification":{ (1)
         "trust_framework": …,  (4)
         "time": …, (5)
         "verification_process": …, (6)
         "evidence":[  (7)
            {
               "type":{ (8)
                  "value": …
               },
               "method": …, (3)
               "document":{ (2)
                  "type": …, (4)
                  "issuer":{  (2)
                     "country": …, (3)
                     "name": …, (6)
                     "… any other keys …": … (6)
                  },
                  "… any other keys …": … (6)
               }
               "… any other keys …": … (6)
            }
         ]
      },
      "claims":{ (1)
         "given_name": …, (3)
         "family_name": …, (3)
         "birthdate": …, (3)
         "place_of_birth": …, (3)
         "nationalities": …, (3)
         "address": … (3)
      }
   },
   … (claims)
}
1 This key MUST NOT be omitted and MUST contain an object with at least one key (verified_claims MUST contain verification and claims).
2 This key MAY be omitted completely. Otherwise, its value MUST be an object.
3 This claim MAY be requested using null or an object. The object MAY contain the keys essential and either value or values. Other keys are not permitted in the object.
4 This key MUST be requested (unless the parent element is omitted) using null or an object. The object MAY contain the keys value or values. Other keys are not permitted in the object.
5 time MAY be omitted. Otherwise, its value MUST be either null or an object with the max_age key and/or the essential key. Other keys are not permitted in the object.
6 This key MAY be requested using null or an object. The object MAY contain the key essential. Other keys are not permitted in the object.
7 evidence MUST either be omitted or MUST contain an array with exactly one object.
8 evidence/type MUST be requested (if evidence is not omitted) using a concrete value. Other keys are not permitted in the object.

value, values, essential, max_age are used as defined in OpenID Connect for Identity Assurance.

If a key is omitted in the request, the response MUST NOT contain the respective key.
Only “leaf” claims can be marked essential. Object/array claims (place_of_birth, nationalities, address) are considered leaf claims and can only be essential as a whole (or not).

OPs MUST reject requests not complying with this syntax.

Example 6. Minimal Request Example
{
   "verified_claims":{
      "verification":{
         "trust_framework": null
      },
      "claims":{
         "family_name": null
      }
   }
}
Example 7. More Complete Request Example 
{
   "verified_claims":{
      "verification":{
         "trust_framework": {
            "value": "de_aml"
         },
         "time": {
            "max_age": 8640000
         },
         "evidence":[
            {
               "type": {
                  "value": "id_document"
               },
               "method": null,
               "document":{
                  "type": null,
                  "issuer":{
                     "country": {
                        "essential": true
                     },
                     "name": null
                  }
               }
            }
         ]
      },
      "claims":{
         "given_name": {
            "essential": true
         },
         "family_name": {
            "essential": true
         },
         "birthdate": {
            "essential": true
         }
      }
   },
   "txn": null
}

4.2. OP Support

OPs MUST support the following Claims in verified_claims/claims:

  • given_name

  • family_name

  • birthdate

  • place_of_birth

  • nationalities

  • address

OPs MUST support the following elements in verified_claims/verification:

  • The trust_framework identifier de_aml MUST be supported.

  • The evidence type id_document MUST be supported with at least the following sub-elements:

    • type

    • method

    • document

  • For evidence/method: OPs MUST map the verification methods used to verify the bank customer’s identity to one of the following evidence verification methods (or omit evidence/method from the response if the verification method cannot be mapped):

    • pipp

    • sripp

  • The evidence/document element MUST be supported with at least the following sub-elements:

    • type

    • number

    • issuer

    • date_of_issuance

  • For evidence/document/type: OPs MUST map the identity document used to verify the bank customer’s identity to one of the following document types (or omit evidence/document/type from the response if the document type cannot be mapped):

    • idcard

    • passport

    • de_idcard_foreigners

    • de_emergency_idcard

    • de_erp

    • de_erp_replacement_idcard

    • de_idcard_refugees

    • de_idcard_apatrids

    • de_certificate_of_suspension_of_deportation

    • de_permission_to_reside

    • de_replacement_idcard

  • The IDP MUST support the evidence/document/issuer sub-elements name and country. If the IDP does not maintain a dedicated country value for the issuer of the ID document of a particular or all users, it MUST use the verified nationality of the respective user account as country value. If the IDP cannot reliably determine what nation issued the respective id document, it MUST omit the element.

    Note: Omitting the country element will cause an abort of the authorization process in case of identity for QES if the QTSP declared this element as essential.

    Note: Use of the nationality as value of the issuer country MUST NOT result in the addition of the nationalities claim to the mediation record of the respective transaction.

  • The constraints on verification data described in the request syntax above MUST be supported:

    • trust_framework

    • time

    • evidence/type

    • evidence/method

    • evidence/document/type

    • evidence/document/issuer/country

OPs MUST advertise their capabilities with respect to verified person data in the standard openid-configuration as defined in OpenID Connect for Identity Assurance.

4.3. OP Data Handling

  • If a requirement (using value, values, or max_age) within verified_claims/verification cannot be fulfilled by the OP (for example, due to data being unavailable, differing from the requested values, or when the OP is unable to map available data to allowed values), the OP MUST omit the verified_claims element from the response.

  • The essential designation MUST NOT influence whether claims or verification elements are delivered or not. For example, if a verification element marked as essential (but not restricted using value/values/max_age) is not available, the OP omits the particular element from the response as usual, but does not omit the verified_claims element as it would do with a value restriction.

  • If a particular claim within verified_claims/claims cannot be delivered by the OP, for example if the data is not available, or if requirements are expressed that cannot be fulfilled by the OP, the OP MUST NOT deliver the respective claim. If the resulting verified_claims/claims set is empty, the OP MUST omit verified_claims from the response, according to OpenID Connect for Identity Assurance.

Common cases where data is not available to the OP include the verification method (method) and the country of the issuer. When supported in the future, the eID function of the German eID Card does not provide a document number or issuer name. In this case, name and number MUST be omitted.

4.4. Error Handling

4.4.1. Request Syntax

A JSON schema is available at https://bitbucket.org/openid/ekyc-ida/src/e765a51e5d894dcc3b212c3ebd25efb4d14b5a6c/schema/ to verify the syntax of the incoming request.

This JSON schema is more permissive than the Request Syntax described above.

4.4.2. Compatibility with Old Spec Versions

RPs MUST NOT use older variants of requesting verified person data in the same transaction with the current method described herein. In particular, the claim https://www.openbanking.verimi.cloud/claims/verified_person_data MUST NOT be used together with verified_claims. OPs SHOULD reject such requests using the error code invalid_request.

5. Billing Mediation

The OP is supposed to report any successful login or user claims transmission to the Mediation Service.

The only exceptions are clients in the state demo, which indicates that the client can participate in the ecosystem without mediation records being written. For more information, see the IDP Core Specification.

The mediation record should be posted to the mediation service just before the data is sent to the RP, i.e. either just before the token response containing the ID token or just before the user info response is sent to the RP.

The mediation record MUST contain the following data:

  • type is set to identity

  • issuer: set to the Issuer URL of the IDP

  • client_id: set to the client_id of the RP

  • requested_claims: A JSON-Objekt containing all requested claims along with the information whether the respective claim was marked as being essential. This element is a duplicate of the claims parameter in the OpenID Connect Authentication request plus the normalized representation of all claims requested via scope values (including sub and acr).

  • provided_claim_names: array containing each individual claim provided to the client. In case of verified claims the entries are built as follows:

    • For every claim embedded in the verified_claims/claims element, the entry is built by concatenating verified_claims/claims and the respective claim name, e.g., verified_claims/claims/place_of_birth.

    • For every entry in the verified_claims/verification element that is not a container element, the entry is built by concatenating verified_claims/verification and the respective claim name, e.g., verified_claims/verification/trust_framework. For every element provided in a container underneath verified_claims/verification, the name is build by concatinating verified_claims/verification, the names of the container elements and the respective claim name, using the separator /. Exception: For the evidence container the type of the particular evidence is appended in the following format: evidence[type='id_document']. Example: verified_claims/verification/evidence[type='id_document']/document/date_of_issuance.

  • provided_acr_value: (OPTIONAL) acr value as attested to the RP (if requested by the RP)

  • endpoint: the endpoint used to provide the data, set to token or userinfo

  • transaction_id: identifier uniquely identifying a certain OpenID transaction at the OP

  • delivery_time: the time when the data was delivered to the RP

  • The respective owner_id (see Platform API Documentation for details)

  • reference_id: OPTIONAL. String (1 to 100 characters restricted to a-z, A-Z, 0-9 and dashes ("-"),e.g. a uuid) generated by the IDP as unique mediation record id to prevent multiple mediation records for the same event. Uniqueness is considered per IDP (issuer element). If the field is provided in the mediation record, the mediation service checks whether a mediation record with the same reference_id for the the same issuer already exists and will refuse processing in that case.

The element transaction_id is used to correlate different mediation records created in the course of a particular transaction. It allows to group associated billing items and provides further information to resolve disputes.

Custom claims are included in billing mediation data in the same way as regular claims.

6. User Account Migration

An online-banking user should not lose access to her RPs even if the responsibility for managing her user account within the scheme is moved to another IDP. If, for example, a bank is acquired by or merges with another bank, then the resulting entity will provide the IDP for all respective customers in the scheme.

In this case, the user identifier that is presented to an RP changes:

  • The new IDP will use a different issuer URL (iss claim) than the previous IDP.

  • The subject (sub) claim value can change as well.

The User Account Migration describes a protocol to provide RPs with all data they need to securely acquire a link between the new and old user identifier of a particular user and a reliable way to verify the authenticity of the migration. The RP can then internally link/change the old user identifier to the new user identifier.

6.1. Requirements

The User Account Migration only works under following preconditions:

  • The IDPs involved cooperate to use an out-of-band process to migrate at least the following data from the old IDP to the new IDP for all users:

    • The previously used user identifiers; if PPIDs are used, this includes all previously used PPIDs at all RPs. If the PPIDs are not stored but computed from user data, care must be taken to transfer all user data that is needed to compute the PPIDs of the old IDP.

    • The transaction history.

    • The user consents given to certain RPs.

  • The issuer domain of the old IDP remains available as a trust anchor.

The new IDP MUST ensure that the mapping between the "old" user accounts and the "new" user accounts is correct in order to prevent account takeover!

6.2. User Account Migration Protocol

The starting point of the user account migration with an RP is a login attempt by the respective user with this RP. Since the authoritative IDP for her bank has changed, the issuer URL the account chooser will respond with is different this time (see above).

In order to enable the migration, two pieces of data need to be communicated:

  1. User Migration Data: The new IDP must provide the RP with data about the migration of the user account within the OpenID Connect login response of the new IDP.

  2. Change of Authority: The old IDP has to testify that it wants to migrate its users to the new IDP (i.e., the new IDP is really the authoritative identity source for migrated users), in a form that can be securely checked by RPs.

6.2.1. User Migration Data

The new IDP includes the user migration data in the ID Token returned to the RP in an aka claim as shown in the following example

Example 8. User Migration Data in the ID Token. 
{
  "iss": "https://newop.example.net/",
  "sub": "JRrr09BzhZ6BJ9t0yD8DzyZjg7ziB3a40jeoUvZkUgw",
  "aud": "s6BhdRkqt3",
  "iat": 1471238000,
  "exp": 1471238300,
  "aka": [
    {
      "iss": "https://oldop.example.net/",
      "sub": "787676666712868798743079787877"
    },
    {
      "iss": "https://veryoldop.example.com/",
      "sub": "eWVzriB1c2VyIG1pZ3JhdGlvbg=="
    }
  ]
}

aka (also known as) is a list of objects that each consist of the two fields iss and sub which contain the respective values of the user account with the old IDP(s). There might be multiple objects in the aka claims, since, for example, repeated mergers of banks can lead to situations where users are migrated from veryoldop.example.com to oldop.example.net and further to newop.example.com.

The sub included in the aka claim MUST match the sub the old IDP used with the respective RP, even if the old IDP issued pairwise pseudonymous identifiers (PPIDs).
The RP MUST NOT trust any aka claims without validating whether the new IDP is really the authoritative identity source which officially replaced the old IDP in the scheme. This MUST be verified through the Change of Authority document described next.

6.2.2. Change of Authority (CoA)

The old issuer publishes a document that communicates the change of authority, i.e., an authorization for migration of users to the new IDP, under a fixed CoA URL, which can be derived from the old IDP’s issuer URL. This CoA document is completely under the control of the old IDP (or the legal entity now controlling the old IDP’s domain).

The CoA document MUST be a JSON document available at the path formed by concatenating the string /.well-known/yes/change-of-authority to the issuer URL. The JSON document contains two elements, issuer and new_issuer, where issuer MUST match the issuer URL of the old issuer.

The following shows an example request

Example 9. Request for the CoA Document 
GET /.well-known/yes/change-of-authority
Host: oldop.example.com
Example 10. Response (CoA Document)
HTTP/1.x 200 Ok
Content-Type: application/json

{
   "issuer":"https://oldop.example.net/",
   "new_issuer":"https://newop.example.net/"
}

If new_issuer matches the issuer of the ID token, the RP can migrate the user account. Otherwise, the user’s identity (potentially) has been transferred multiple times. In this case, the RP must repeatedly request the CoA documents of the respective new_issuer until a CoA document is reached that points to the issuer of the ID token. (See the Relying Party Developer Guide for a detailed algorithm.)

If there is no path to reach the issuer denoted in the respective aka claim, the RP MUST terminate the process and MUST NOT use the aka data. In such a case, the RP shall then proceed by only using the regular iss and sub claim in respective the ID Token.

6.3. IDP Implementations

Any IDP taking over responsibility for user accounts previously managed by another IDP in the scheme MUST provide RPs with the aka claim in its ID Tokens in order to facilitate continued access for its users to the respective RPs.

Any IDP that stops operation and transfers authority for its user accounts to another IDP MUST publish the Change of Authority document as described above. Such an IDP is supposed to no longer publish the openid-configuration document.

7. References

8. Document Control

8.1. Changes

  • Version 2.2 (2020-01-20)

    • removed birth*_name from the mandatory to implement list for verified claims

    • added description of default content of verification sub-element or verified_claims

    • added requirements for the IDP to support constraint on various verification sub-elements

    • added reference_id to mediation record description

    • added note that the OP may decide whether amr is provided

    • added pin to the list of authentication methods (was already shown in the example)

    • added note that the IDP must be able to resolve sub claims to user accounts

    • added description of fulfilled_verification_requirements mediation record field

    • made place_of_birth.country optional

    • made evidence.method subelement only conditionally required

  • Version 2.1

    • Added note on treatment of requests for person data without attestation (aka unverified person data)

  • Version 2.0

    • Changed Service to be based on OpenID Connect for Identity Assurance

    • Added birth_middle_name to mandatory claims for verified person data

    • Clarification regarding txn claim in mediation record

  • Version 1.1

    • First version of the ID Service Specification was forked from the IDP Specification

9. Responsibilities

document owner

Dr. Daniel Fett (danielf@verimi.com)