TEFCA Individual Access Services (IAS) integration guide
TEFCA Individual Access Services (IAS) integration guide
Configure your application to support TEFCA Individual Access Services (IAS) with ID.me.
TEFCA Individual Access Services (IAS) integration guide
Configure your application to support TEFCA Individual Access Services (IAS) with ID.me.
The Trusted Exchange Framework and Common Agreement (TEFCA) is a U.S. healthcare interoperability framework that enables individuals to securely access their own health records across disparate networks. ID.me supports the TEFCA Individual Access Services (IAS) exchange purpose, empowering patients to request and receive their health information through apps of their choice using NIST 800-63-3 Identity Assurance Level 2 (IAL2) identity proofing.
Intended audience
Developers and IAM administrators responsible for configuring federation between a TEFCA IAS application and ID.me.
What you will build
A TEFCA-compliant patient access workflow where ID.me serves as the Credential Service Provider (CSP) issuing IAL2-verified identity tokens to your IAS application.
Result
A patient logs into your app, verifies their identity via ID.me, and grants consent to retrieve their clinical records with a single IAS request across the TEFCA network.
The following steps outline the TEFCA IAS authentication flow between the patient, your application, the Qualified Health Information Network (QHIN), and ID.me:
Your application redirects the patient to ID.me for identity verification, including the TEFCA IAS policy scope
The patient reviews and grants consent to share their verified identity attributes with your application
Before beginning this integration, ensure you have the following:
ID.me provides two environments:
https://api.idmelabs.com/
https://api.id.me/
All ID.me OIDC endpoints are derived from the base URL above. Replace the sandbox base URL with the production base URL in every endpoint you configure before going live.
Before configuring your identity provider settings, you must register your application with ID.me to obtain OAuth 2.0 credentials.
Contact your ID.me Solution Consultant and communicate that you intend to use the Individual Access token. Provide the following details:
openid plus the TEFCA IAS policy scope handle (provided by your Solution Consultant)ID.me will provision an IAL2-level project and policy for your application, then return:
client_id: Your application’s unique identifier. This will either reflect your HL7 OID or an ID.me specific client ID.client_secret: Your application’s secret credential (store securely — never expose in client-side code)Redirect URIs must be pre-registered with ID.me. ID.me will reject any authorization request that specifies an unregistered redirect_uri.
Requirements:
localhost only)com.example.app://callback) if registeredWith your client_id and client_secret in hand, configure your application to initiate the Authorization Code flow against ID.me.
Direct the patient to ID.me’s authorization endpoint with the following parameters:
Upon completion of the verification flow, ID.me redirects the patient back to your redirect_uri with an authorization_code. Parse this code from the URL and use it to perform the token exchange.
Exchange the authorization code for tokens using the token endpoint:
The token response varies depending on whether identity verification was successful.
Successful verification — ID.me returns an access_token, id_token, and refresh_token. The id_token is only issued when the patient’s demographics have been fully validated to IAL2. Use the id_token to relay the patient’s identity to the QHIN.
ID.me issues an id_token signed using RS256. The token payload follows standard OIDC claim names and includes TEFCA-required demographic attributes. The aud claim reflects your OID-formatted client_id.
The exact claim names returned depend on your ID.me policy configuration. Work with your ID.me Solution Consultant to confirm which attributes your policy handle returns and how they map to the TEFCA required demographics.
Per the Sequoia Project IAS SOP, the following patient demographics must be validated to IAL2 and present in the token:
Per the Sequoia Project IAS SOP, the following patient demographics must be validated to IAL2 and present in the token if they are known:
Before relaying the identity token to a QHIN, validate it against ID.me’s public key. Fetch the JWKS from the endpoint below and use a standard JWT library to verify the token signature using the key matching the token’s kid header value.
When validating, confirm all of the following:
iss claim matches ID.me’s issuer URI for the environment (sandbox or production)aud claim matches your registered client_idexp claim has not elapsed (token has not expired)iat claim is in the pastnonce claim matches the value sent in your authorization requestNever relay an identity token to a QHIN without first completing full token validation. An invalid or expired token will be rejected by the QHIN and may expose your integration to replay attacks.
Use the ID.me sandbox environment (https://api.idmelabs.com/) to validate your integration end-to-end before promoting to production.
Do this from your application using your sandbox client_id (OID format) and your TEFCA IAS policy scope. Confirm the redirect correctly lands on the ID.me sandbox login page.
Use the ID.me sandbox test credentials provided by your Solution Consultant. The sandbox simulates the full IAL2 proofing flow without requiring real identity documents.
Confirm that id_token and refresh_token are present, indicating a successful verification. Decode the id_token (e.g., at jwt.io) and verify:
iss matches https://api.idmelabs.com/oidcaud matches your OID-formatted client_idnonce matches the value sent in the authorization requestFetch the JWKS from https://api.idmelabs.com/oidc/jwks and confirming the signature verifies against the key matching the token’s kid header value.
Send this to your QHIN’s sandbox or test environment with the token relayed in the appropriate format (SAML attribute or tefca_ias FHIR extension). Confirm the QHIN accepts the token and returns a successful query response.
Token expiry defaults to 5 minutes (expires_in: 300). Request a fresh token for each IAS query rather than caching tokens across sessions.
When extracting claims from the identity token, follow these best practices to maintain a secure and reliable integration:
Validate the token — Always validate the token before extracting claims. Verify the signature, and confirm the exp and iat claims ensure the token is still valid. Never relay an unvalidated token.
Check the audience (aud) — Confirm the aud claim matches your client_id. This ensures the token was issued for your application and not for a different relying party.
Verify the issuer (iss) — Ensure iss matches ID.me’s issuer URI for the active environment. Tokens from the sandbox issuer must never be accepted in production and vice versa.
Handle claims securely — Extract only the claims your application needs to minimize data exposure. Treat demographic attributes (email, phone, address) as sensitive data and ensure compliance with applicable privacy regulations.
Use the state parameter — Always generate a unique state value per session in your authorization request and validate it on return. This prevents cross-site request forgery (CSRF) attacks.
Use the nonce parameter — Embed a unique nonce in the authorization request and validate it in the returned id_token. This prevents token replay attacks.
Do not cache JWKS keys indefinitely — Rotate your cached public keys periodically by re-fetching the JWKS endpoint. ID.me may rotate signing keys, and stale cached keys will cause signature validation failures.
Log and monitor — Log token validation attempts and monitor for unusual patterns, such as repeated validation failures or tokens with unexpected aud or iss values, which may indicate an attack.
If the QHIN rejects the identity token, check the following:
If patients are not presented with a consent screen to share identity attributes, confirm that your authorization request includes the correct TEFCA IAS policy scope handle. The scope drives which attributes are requested and triggers the consent screen. Contact your ID.me Solution Consultant to verify your policy scope configuration.