Internet User Authorization: Difference between revisions

From IHE Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
PROPOSED UPDATE to https://wiki.ihe.net/index.php/Internet_User_Authorization
Wiki markup. Not yet posted. Items in [CONFIRM] need checking before posting.
----- BEGIN WIKI MARKUP -----
= Internet User Authorization (IUA) =
= Internet User Authorization (IUA) =


'''Internet User Authorization (IUA)''' is an IHE IT Infrastructure profile that conveys the identity, attributes and authorizations of a user to a RESTful service. It supports the authorization of transactions made over IHE's HTTP RESTful transports. IUA is the RESTful counterpart of [[XUA]] (Cross-Enterprise User Assertion), which uses SAML assertions.
'''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.


{| class="wikitable"
{| class="wikitable"
|-
|-
! Status
! Status
| Trial Implementation, Revision 2.5 (dated 2026-06-18)
| Trial Implementation, Revision 2.5 (June 18, 2026). Published for trial implementation and Connectathon testing; may be amended based on test results.
|-
|-
! Domain
! Domain
| IT Infrastructure (ITI)
| IT Infrastructure (ITI)
|-
|-
! Technology
! Specification
| OAuth 2.0 / 2.1 with JSON Web Tokens (JWT); HTTP RESTful transactions
| [https://profiles.ihe.net/ITI/TF/Volume1/ch-34.html IUA Volume 1, Section 34]
|-
! Source repository
| [https://github.com/IHE/ITI.IUA 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 ==
 
{| class="wikitable"
|-
! 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 ==
 
{| class="wikitable"
|-
! 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
|-
|-
! Specification
| Token Introspection (34.2.4)
| [https://profiles.ihe.net/ITI/TF/Volume1/ch-34.html IUA Volume 1, Chapter 34]
| AS, RS
| Validation via ITI-102; supports opaque or custom token formats. [CONFIRM: the master branch renames this option to "Bearer".]
|}
|}


== Overview ==
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 <code>active=false</code>.
 
* '''Request:''' an HTTP POST to the introspection endpoint, <code>application/x-www-form-urlencoded</code>, with the <code>token</code> 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 <code>active=false</code>, or <code>active=true</code> 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 <code>exp</code> 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 ==


IUA defines how a client application obtains an access token from an authorization server and presents it to a resource server. The resource server can then check the user's identity and authorizations before it processes a request.
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>code</code>. The implicit grant is not supported.
* '''grant_types_supported''' (required): must include <code>client_credentials</code> and <code>authorization_code</code>. Optional values include <code>refresh_token</code>, 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.


== Actors ==
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.


* '''Authorization Client''': requests an access token for a user or client application.
== Required actor groupings ==
* '''Authorization Server''': issues access tokens after authenticating the client.
* '''Resource Server''': accepts access tokens and enforces authorization on requests.


== Transactions and options ==
* Authorization Server and Resource Server must be grouped with a Consistent Time (CT) Time Client.
* Authorization Client has no required grouping.


[CONFIRM: transaction names and option list against Volume 1 and Volume 2 of the current revision. The text below is a placeholder structure.]
== Grant types ==


* ITI-71: Get Access Token (the token request).
* '''Required:''' Authorization Code and Client Credentials. Clients must support at least one; Authorization Servers must support both.
* Options: [CONFIRM: for example the JWT Token Option and the Client Credentials grant type, against the TI text.]
* '''Optional extensions:''' Device Authorization (RFC 8628), SAML assertion grants (RFC 7522), and JWT grants (RFC 7523).


== Relationship to other profiles ==
== JWT claims ==


* [[XUA]]: the SAML-based counterpart for user assertions.
The JWT IUA Extension (3.71.4.2.2.1.1) includes <code>subject_name</code>, <code>subject_organization</code>, <code>subject_organization_id</code>, <code>subject_role</code>, <code>purpose_of_use</code>, <code>home_community_id</code>, <code>national_provider_identifier</code> and <code>person_id</code>. These map to XUA attributes. A separate BPPC extension covers <code>patient_id</code>, <code>doc_id</code> and <code>acp</code>.
* [[ATNA]]: security audit and mutual authentication (TLS) for the same transactions.
* [[MHD]], [[PMIR]], [[mCSD]], [[SVCM]]: profiles that use IUA for authorization in the MHDS FHIR exchange blueprint.


== Use in FHIR-based architectures ==
== MHD scopes (Section 33) ==


IUA is categorized under FHIR because it is used with FHIR-based profiles such as MHD. [CONFIRM: wording, and whether to link the MHDS and CH EPR implementations listed in the wider profile documentation.]
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.


== Connectathon testing ==
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) ==


IUA has been tested at IHE Connectathons, most recently in Europe (2024, 2025 and 2026) and Japan (2024). Between 2022 and 2026, 18 vendors tested IUA actors: Authorization Client, Authorization Server and Resource Server. [CONFIRM: figures against the CAT results before posting.]
* '''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 (<code>authorization_details</code>) 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.]


== Recent changes ==
== Change history (selected) ==


* Revision 2.5 (2026-06-18): Trial Implementation. [CONFIRM: list of changes in this revision.]
* '''Issue 2:''' the Bearer Token Option was removed because it lacked a defined token format.
* CP-ITI-1331: removes the client_id/client_secret requirement for the Client Credentials grant; passed ballot 67; not yet in the published text. [CONFIRM: publication status.]
* '''Issue 1:''' client registration is out of scope.
* CP-ITI-1324: clarifies that JWT signing is required or optional; passed ballot 66. [CONFIRM: publication status.]
* '''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.]


== Open issues ==
== Connectathon testing ==


[CONFIRM: list any open issues from the TI text. None have been confirmed as open as of this draft.]
18 vendors tested IUA actors from 2022 to 2026, in Europe (2024, 2025, 2026) and Japan (2024).]


== Formal Specification ==
== Formal specification ==


* [https://profiles.ihe.net/ITI/TF/Volume1/ch-34.html IUA (HTML specification)]
* [https://profiles.ihe.net/ITI/TF/Volume1/ch-34.html IUA (HTML specification)]
* [https://profiles.ihe.net/ITI/IUA/index.html IUA profile page]
* [https://profiles.ihe.net/ITI/index.html IT Infrastructure Technical Framework]
* [https://profiles.ihe.net/ITI/index.html IT Infrastructure Technical Framework]


Line 72: 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 in the search.]


== See Also ==
== See also ==


* [[XUA]]
* [[XUA]]
* [[ATNA]]
* [[MHD]]
* [[MHD]]
* [[ATNA]]
* [[BPPC]]
 
----- END WIKI MARKUP -----
 
Notes for the editor (remove before posting):
* The current page is protected and has an unfilled placeholder in the related-profile text ("< supports IUA in some fashion >" and "< supported as a token type in IUA >"). Those placeholders are on other profile pages. Check before editing.
* The current page links to an old revision. Use the current permanent link when editing.
* The [[...]] links must match existing wiki page names. Check XUA, ATNA, MHD, PMIR, mCSD, SVCM before posting.

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