Internet User Authorization: Difference between revisions

From IHE Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(2 intermediate revisions by the same user not shown)
Line 155: Line 155:
== Connectathon testing ==
== 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).]
18 vendors tested IUA actors from 2022 to 2026, in Europe (2024, 2025, 2026) and Japan (2024).]


== Formal specification ==
== Formal specification ==
Line 166: Line 166:


* [https://profiles.ihe.net/ITI/HIE-Whitepaper/index.html HIE white paper]
* [https://profiles.ihe.net/ITI/HIE-Whitepaper/index.html HIE white paper]
* [CONFIRM: any IUA-specific slides, webinars or videos before adding. No IUA video was found.]


== See also ==
== See also ==
Line 174: Line 173:
* [[MHD]]
* [[MHD]]
* [[BPPC]]
* [[BPPC]]
----- 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.

Latest revision as of 10:41, 19 November 2026

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 the token parameter (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, or active=true with 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 exp field, 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_credentials and authorization_code. Optional values include refresh_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

18 vendors tested IUA actors from 2022 to 2026, in Europe (2024, 2025, 2026) and Japan (2024).]

Formal specification

Further reading

See also