Linking a User to a User Directory Interactively

A user who already has a Trivore ID account can link it to an external user directory, for example suomi.fi, by identifying once through that directory. After linking, the user can sign in with the directory, and the account is recognised as theirs. Your service starts the flow over the Management API, and Trivore ID returns the result to your service in a signed token.

This works like interactive strong identification; the difference is that the result is a user directory link instead of a strong identification entry.

Produce a URL leading to the interactive identification web page

Request the URL with POST https://{your-id-server}/api/rest/v1/userdirectory/{directoryId}/attach/{userId}. The request body gives a success redirect URI and a failure redirect URI. You may optionally give a nonce value, which is returned in the success redirect result token.

The request is authorised with either:

• a Management API client that has the ACCOUNT_MODIFY_LINKS permission, or
• an access token of the user being linked. A user can only link their own account.

The user directory must support external login, and it must include the namespace of the user. See the API documentation at https://{your-id-server}/apidoc for the full request and response reference.

The produced URL is single-use and valid only for a short time, so generate it immediately before forwarding the user to it.

Redirect the user to the produced URL

Have the user open the URL in their web browser. The user identifies through the user directory.

Wait for the result

On success, the user is redirected to the success redirect URI. On failure (including cancellation), the user is redirected to the failure redirect URI.

Success redirect URI parameters

If the account was linked successfully, the following parameter is added to the success redirect URI. This applies to Trivore ID version 6.x and later.

Parameter	Value
result	Signed JWT which describes the linking result. See Validating the result token.

The payload of the result token:

{
  // Token issuer, value is Trivore ID base URL
  "iss": "https://id.example.com",

  // Issued at timestamp when token was issued. Value is epoch seconds.
  "iat": 1789018469,

  // Token expiration timestamp. Value is epoch seconds. The token is valid for 30 minutes.
  "exp": 1789020269,

  // Audience, value always contains the success redirect URI without any query parameters.
  "aud": [
    "https://example.com/success"
  ],

  // JWT unique ID. Use this to prevent replay attacks.
  "jti": "425af4af-97b2-4e1c-b7ab-8015496262ae",

  // Nonce value provided in the original API request. Present only if a nonce was given.
  "nonce": "406ebf05-a777-4df0-bb01-ce4d558b4cc8",

  // Describes the token type, value is always the same
  "type": "urn:trivore:id:link-account:result",

  // Value should always be true (excluding certain theoretical edge cases).
  "success": true,

  // User directory ID that the user was linked to.
  "directoryId": "6aa923791b5db46501f1e2bb",

  // User ID that was linked.
  "userId": "6aa9239b1b5db46501f1e2bc",

  // ID of the user directory link of the user.
  "directoryLinkId": "6aa923b41b5db46501f1e2bd",

  // These fields are present only if success is false.
  "error": "machine-readable-error",
  "errorDescription": "Human-readable error message"
}

The created link can be read with GET https://{your-id-server}/api/rest/v1/userdirectory/{directoryId}/link/{directoryLinkId}.

Failure redirect URI parameters

If linking doesn't finish successfully, these parameters may be added to the failure URI:

Parameter	Value
error	Error code.
error_description	Short, human-readable explanation of the error, in English.

Validating the result token

Treat the result token as untrusted input until you have validated it:

1. Verify the signature with the Trivore ID signing keys. They are published at the jwks_uri of the discovery document, https://{your-id-server}/.well-known/openid-configuration. Select the key by the kid in the token header.
2. Check that iss is your Trivore ID base URL.
3. Check that aud contains your success redirect URI, without query parameters.
4. Check that exp has not passed.
5. Check that type is urn:trivore:id:link-account:result. This keeps a strong identification result from being accepted as a linking result, and the other way round.
6. If you sent a nonce, check that the token has the same value.
7. Store jti until the token expires, and reject a token whose jti you have already seen.
8. Check that success is true before using userId and directoryLinkId.

See also Initiating interactive strong identification, which returns a result token of the same form.