Internet User Authorization
Internet User Authorization (IUA)
Internet User Authorization (IUA) adds authorization to HTTP RESTful transactions. It complements XUA (SOAP-based) and EUA (intra-enterprise). IUA is grounded in OAuth 2.1 and is base-standard agnostic. It is not based on SMART-on-FHIR, but it aims not to conflict with it, and it emphasizes loose coupling between the Resource Server and the Authorization Server.
| Status | Trial Implementation, Revision 2.5 (June 18, 2026). Published for trial implementation and Connectathon testing; may be amended based on test results. |
|---|---|
| Domain | IT Infrastructure (ITI) |
| Specification | IUA Volume 1, Section 34 |
| Source repository | IHE/ITI.IUA on GitHub (working copy of the supplement; not the published text) |
| Feedback | ITI Public Comment form or GitHub issue |
Scope
In scope: authorization of HTTP RESTful transactions, using access tokens obtained from an Authorization Server.
Out of scope:
- Consent administration and policy management (handled by BPPC or similar).
- Administrative setup of an Authorization Server.
- Client registration (see closed Issue 1).
Actors and transactions
| Actor | Transactions (optionality) |
|---|---|
| Authorization Client | ITI-71 Get Access Token (R); ITI-72 Incorporate Access Token (R); ITI-103 Get AS Metadata (O) |
| Authorization Server | ITI-71 Get Access Token (R); ITI-102 Introspect Token (O); ITI-103 Get AS Metadata (O) |
| Resource Server | ITI-72 Incorporate Access Token (R); ITI-102 Introspect Token (O); ITI-103 Get AS Metadata (O) |
- Authorization Client: performs the network transactions and user interactions needed to obtain an access token.
- Authorization Server: issues access tokens after evaluating user identity, the requested Resource Server, and other information.
- Resource Server: enforces this authorization and may perform additional authorization decisions.
Transactions:
- ITI-71 Get Access Token: request and obtain an access token.
- ITI-72 Incorporate Access Token: add an access token to a transaction.
- ITI-102 Introspect Token: obtain the state and claims of an access token.
- ITI-103 Get Authorization Server Metadata: obtain metadata about an Authorization Server.
Options
| Option | Applies to | Description |
|---|---|---|
| Authorization Server Metadata (34.2.1) | Client, AS, RS | Automated configuration by pulling metadata from the AS |
| JWT Token (34.2.2) | AS, RS | Access tokens are signed JWTs with IUA claim extensions |
| SAML Token (34.2.3) | AS, RS | XUA-compliant SAML 2.0 assertions as access tokens |
| Token Introspection (34.2.4) | AS, RS | Validation via ITI-102; supports opaque or custom token formats. [CONFIRM: the master branch renames this option to "Bearer".] |
Authorization Server and Resource Server actors must support at least one of the JWT Token, SAML Token or Token Introspection options.
ITI-102 Introspect Token
The Resource Server asks the Authorization Server whether an access token is active and what claims it carries. This works whether or not the claims are carried in the token, so it also supports opaque tokens. The Authorization Server may mark a token inactive, for example if it has expired, been revoked, or the requesting Resource Server is not in the token's audience. An inactive response contains only active=false.
- Request: an HTTP POST to the introspection endpoint,
application/x-www-form-urlencoded, with thetokenparameter (RFC 7662). The Resource Server authenticates with credentials agreed with the Authorization Server, typically a Bearer token obtained through the client credentials grant. HTTP GET is not allowed, to avoid token leakage in query parameters. - Response: JSON. Either
active=false, oractive=truewith the same claims as the JWT token content. The Authorization Server may tailor the scopes to the requesting Resource Server. - Expected actions: the Resource Server rejects requests with an inactive token using HTTP 401. It may cache a response only if the response carries an
expfield, and the cache must not outlive that expiry. - Security: TLS is required. The Authorization Server must validate expiry, revocation, audience, and the signature of any JWT. An inactive response must not disclose other claims.
ITI-103 Get Authorization Server Metadata
Authorization Clients and Resource Servers use this transaction to learn the Authorization Server's endpoints and key locations. It is an HTTP GET to the well-known metadata endpoint (RFC 8414 or OpenID Connect Discovery). The response is a JSON document with, among other claims:
- issuer (required): an https URL. For multi-tenant servers the issuer includes the tenant path.
- authorization_endpoint and token_endpoint (required).
- response_types_supported (required): must include
code. The implicit grant is not supported. - grant_types_supported (required): must include
client_credentialsandauthorization_code. Optional values includerefresh_token, the JWT bearer grant and the SAML bearer grant. - jwks_uri: required for servers that support the JWT or SAML token options.
- introspection_endpoint: required for servers that support the Token Introspection option.
- access_token_format (optional): the token formats the server issues.
Multi-tenant servers must return a different document for each tenant. The request must not include client credentials. Requests for an unknown tenant return HTTP 404.
Required actor groupings
- Authorization Server and Resource Server must be grouped with a Consistent Time (CT) Time Client.
- Authorization Client has no required grouping.
Grant types
- Required: Authorization Code and Client Credentials. Clients must support at least one; Authorization Servers must support both.
- Optional extensions: Device Authorization (RFC 8628), SAML assertion grants (RFC 7522), and JWT grants (RFC 7523).
JWT claims
The JWT IUA Extension (3.71.4.2.2.1.1) includes subject_name, subject_organization, subject_organization_id, subject_role, purpose_of_use, home_community_id, national_provider_identifier and person_id. These map to XUA attributes. A separate BPPC extension covers patient_id, doc_id and acp.
MHD scopes (Section 33)
When an MHD actor is grouped with an IUA actor, the Authorization Client requests a scope from the Authorization Server, and the MHD Resource Server enforces it. The supplement defines these scopes:
- ITI-65 (Provide Document Bundle): Document Source with IUA Authorization Client, and Document Recipient with IUA Resource Server.
- ITI-66 (Find Document Lists) and ITI-67 (Find Document References), and ITI-68 (Retrieve Document): Document Consumer with IUA Authorization Client, and Document Responder with IUA Resource Server.
Each scope authorizes the full transaction. Realm or project-specific refinements may be added.
Related profiles
- XUA: the SOAP equivalent. Its SAML assertions can be used through the SAML Token Option.
- ATNA: provides the "STX: HTTPS IUA" option (ATNA 9.2.6.7, ITI-TF-2 3.19.6.6). A Local Secure Node or Application grouped with an IUA Authorization Client must reject non-HTTPS connections. A Remote Secure Node or Application grouped with an IUA Resource Server must reject connections that do not carry a valid IUA token. Audit events are defined for ITI-71 and ITI-72.
- BPPC: consent documentation linked to IUA claims.
- EUA: enterprise-internal authentication.
- MHD (Section 33): the IUA supplement adds a security section and the scopes listed above.
- SeR (Secure Retrieve): the Authorization Decisions Verifier may be used for policy enforcement.
- CT (Consistent Time, Section 7): required grouping.
Open issues (Rev 2.5)
- Issue 12: whether IUA should define an AuditEvent for Resource Server DENY decisions. The master branch also adds an AuditEvent.entity requirement for the grouped profile.
- Issue 14: possible future use of OAuth Rich Authorization Requests (
authorization_details) for fine-grained scopes. - Issue 15: the OAuth 2.1 draft version. Section 3.71.3 cites draft-09 (July 2023), while Section 3.72.3 and 3.102.3 cite draft-01 (February 2021). [CONFIRM: whether the editors have fixed this.]
Change history (selected)
- Issue 2: the Bearer Token Option was removed because it lacked a defined token format.
- Issue 1: client registration is out of scope.
- Issues 11 and 13: public comment requested on IUA, MHD and SMART-on-FHIR scope and flow harmonization.
- CP-ITI-1288: integrated.
- CP-ITI-1324: clarifies that JWT signing is required or optional. Passed ballot 66. [CONFIRM: publication status.]
- CP-ITI-1331: removes the client_id/client_secret requirement for the Client Credentials grant. Passed ballot 67. [CONFIRM: publication status.]
Connectathon testing
[CONFIRM: add the Connectathon results before posting. From the CAT workbook: 18 vendors tested IUA actors from 2022 to 2026, in Europe (2024, 2025, 2026) and Japan (2024).]
Formal specification
Further reading
- HIE white paper
- [CONFIRM: any IUA-specific slides, webinars or videos before adding. No IUA video was found.]
See also
END WIKI MARKUP -----
Notes for the editor (remove before posting):
- The page is protected. Check the current permanent link before editing, because the existing page links to an old revision.
- The ... links must match existing wiki page names. Check XUA, EUA, ATNA, BPPC, MHD, SeR, CT before posting.
- Editorial error to report to the TC: MHD Volume 2 section 3.66.5.2 says "Get Access Token [ITI-72]" where it should say ITI-71.