Emirates ID in login_hint — Sending It as a TPP, Receiving It as an LFI

When a TPP creates a consent it knows who its customer is, but the LFI does not find out until the PSU authenticates. login_hint closes that gap: the TPP passes the PSU's Emirates ID or Trade Licence Number in the Request JWT, and the LFI receives it when it starts the authorization interaction — before it has to render anything to the PSU.

As the standards put it, this exists “to allow LFIs to correlate the User identity, and therefore the features of their account, prior to the User being redirected to the LFI's authentication page.” An LFI can use it to pre-select a customer segment, choose an authentication channel, or decide which products the journey should offer.

Step 1 — Find the LFI's encryption key

The hint is encrypted to the target LFI, not to the API Hub. Fetch the LFI's JWKS from the Directory keystore using that LFI's organisation ID, and take the key with use: "enc":

Production   https://keystore.directory.openfinance.ae/{LFI-organisation-id}/application.jwks
Sandbox      https://keystore.sandbox.directory.openfinance.ae/{LFI-organisation-id}/application.jwks

That is the LFI's ENC1 key, the same server-side encryption key used for payment PII and described in Keys & Certificates. Use the kid from the JWK you selected.

Step 2 — Build the JWE

Sign first, then encrypt — the JWE wraps a JWS. Use RSA-OAEP-256 for key wrapping and A256GCM for content encryption, matching Message Encryption (JWE), and set cty: "JWT" so the LFI knows the plaintext is itself a token:

{
  "alg": "RSA-OAEP-256",
  "enc": "A256GCM",
  "kid": "<lfi-enc1-key-id>",
  "cty": "JWT"
}

import { SignJWT, CompactEncrypt, importPKCS8, importJWK } from 'jose'

/**
 * Build a login_hint value: a JWS signed with your signing key, wrapped in a
 * JWE encrypted to the LFI's ENC1 public key.
 *
 * @param identification  The Emirates ID or Trade Licence Number
 * @param type            'EmiratesID' | 'TradeLicenseNumber'
 * @param lfiJwksUri      The LFI's JWKS in the Directory keystore
 */
export async function buildLoginHint(
  identification: string,
  type: 'EmiratesID' | 'TradeLicenseNumber',
  lfiJwksUri: string,
): Promise<string> {
  // 1. The payload — exactly these two properties, nothing else
  const payload = { Type: type, Identification: identification }

  // 2. Sign it with your signing key (PS256)
  const signingKey = await importPKCS8(mySigningKeyPem, 'PS256')
  const jws = await new SignJWT(payload)
    .setProtectedHeader({ alg: 'PS256', typ: 'JWT', kid: mySigningKid })
    .sign(signingKey)

  // 3. Fetch the LFI's encryption key
  const { keys } = await (await fetch(lfiJwksUri)).json()
  const encJwk = keys.find((k: { use?: string }) => k.use === 'enc')
  if (!encJwk) throw new Error(`No encryption key (use: enc) in ${lfiJwksUri}`)
  const encKey = await importJWK(encJwk, 'RSA-OAEP-256')

  // 4. Encrypt the compact JWS — the JWE wraps a JWS, so cty is JWT
  return new CompactEncrypt(new TextEncoder().encode(jws))
    .setProtectedHeader({
      alg: 'RSA-OAEP-256',
      enc: 'A256GCM',
      kid: encJwk.kid,
      cty: 'JWT',
    })
    .encrypt(encKey)
}

Step 3 — Put it in the Request JWT

login_hint is a claim of the signed Request JWT you push to POST/par, alongside authorization_details. It is not a separate form field on the PAR request, and not a query parameter on the redirect:

{
  ....
  "login_hint": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiPGxmaS1lbmMxLWtpZD4iLCJjdHkiOiJKV1QifQ...",
  "authorization_details": [
    {
      "type": "urn:openfinanceuae:account-access-consent:v2.1",
      "consent": { "...": "..." }
    }
  ]
}

The consent stored by the API Hub holds what the TPP asked for — ConsentId, Permissions, ExpirationDateTime, OpenFinanceBilling and the consent status. The PSU identity hint is not among those fields, and GET/consents/{consentId} does not return it, at any point in the consent's life.