ITI.IUA

Integrating the Healthcare Enterprise

IHE_LOGO_for_tf-docs

IHE ITI

Technical Framework Supplement

Internet User Authorization (IUA) with updates to MHD and ATNA.

Revision 2.0 - Public Comment

Date: December 2, 2020

Author: ITI Technical Committee

Email: iti@ihe.net

Please verify you have the most recent version of this document. See here for Trial Implementation and Final Text versions and here for Public Comment versions.

Foreword

This is a supplement to the IHE IT Infrastructure Technical Framework V17.0. Each supplement undergoes a process of public comment and trial implementation before being incorporated into the volumes of the Technical Frameworks.

This supplement is published on December 2, 2020 for public comment. Comments are invited and can be submitted using the ITI Public Comment form or by creating a GitHub Issue. In order to be considered in the development of the trial implementation version of the supplement, comments must be received by January 15, 2021.

This supplement describes changes to the existing technical framework documents.

“Boxed” instructions like the sample below indicate to the Volume Editor how to integrate the relevant section(s) into the relevant Technical Framework volume.

| Editor: Please amend Section X.X by the following | |——————————————————|

Where the amendment adds text, make the added text bold underline. Where the amendment removes text, make the removed text bold strikethrough. When entire new sections are added, introduce with editor’s instructions to “add new text” or similar, which for readability are not bolded or underlined.

General information about IHE can be found at http://www.ihe.net.

Information about the IHE IT Infrastructure domain can be found at https://www.ihe.net/IHE_Domains.

Information about the organization of IHE Technical Frameworks and Supplements and the process used to create them can be found at https://www.ihe.net/about_ihe/ihe_process and https://www.ihe.net/resources/profiles.

The current version of the IHE Technical Framework can be found at https://profiles.ihe.net/.

CONTENTS

Introduction to this Supplement

Problem Statement

This profile is motivated by customer requirements for authorizing network transactions when using HTTP RESTful transports. IHE has authorization profiles for the Web Services and SOAP based transactions, and this profile provides an authorization profile for the HTTP RESTful transactions.

Being authorized means that the user, patient, or provider has legitimate access to this HTTP RESTful service. The authorization includes identifying the user and the application that is making the request to the HTTP RESTful server, so that server can make further access control decisions.

The HTTP RESTful transport is being used by many healthcare applications and smart devices. These share a common set of issues. A typical use case example is:

The HTTP RESTful services may include user-driven browser activity, downloaded applications, automatic devices, and IT systems. The existing IHE ITI Cross-Enterprise User Assertion (XUA) Profile fills these needs for the SOAP transport based transactions. The existing IHE ITI Enterprise User Authentication (EUA) Profile fills these needs for various different transports within a single enterprise environment, including HTTP RESTful transports.

The Basic Patient Privacy Consent (BPPC) Profile is associated with this profile and these other existing profiles. BPPC covers the legal and administrative needs for consent documentation and associating the patient consent with policy documentation. The BPPC Profile includes the ability to associate the electronic authorizations with the patient agreements and organizational policies.

IUA is not a substitute for the administrative activities such as withdrawing consent, policy setting, and other activities that BPPC documents provide. The current scope of IUA is the basic authorization activities. Future scope may include greater integration of this authorization with third party authorization and consent documentation profiles, such as those found in the IHE BPPC Profile.

The administrative actions needed to establish an Authorization Server for IUA are not covered by this profile. These activities depend upon the operational needs, and organizational and privacy policies that apply to a particular deployment.

Background on the problem environment

The application interacts with both patient and Authorization Server to support the granting of an access token. The application then uses the access token to retrieve and update health related data.

The key issues include:

Additional issues:

There are also environmental assumptions made by this profile.

IUA assumes that there will many systems working together to build the access control environment, where IUA provides one part only. For example, a glucose monitor may be authorized to have access to a patient’s medical record. The expectation is that this will mean access to all of the glucose-related information, which will include a variety of measurements and prescriptions. But, it is expected that if the device requests other sensitive health data about the patient, it will be rejected.

IUA also assumes that this profile is operating in an environment where access consents are managed by BPPC or other mechanisms. For example, there will be a documented consent agreement between a patient and a provider that the provider will provide medical records to a healthcare proxy that is identified and authorized by the patient. BPPC is one way to document that agreement. IUA is not a substitute for documenting, establishing, and modifying these legal agreements.

Relation to SMART-on-FHIR

IUA is not based on SMART-on-FHIR, but does strive to not conflict with that standard.

Concerns about SMART were raised surrounding the tight dependency between Resource and Authorization Server, the inclusion of launch/view context in the authorization flow, and the dependency on FHIR. The IHE IT Infrastructure Domain believes that IUA provides the following advantages over SMART:

That said, it is recognized that SMART-on-FHIR is evolving and adoption rates are increasing. Therefore, as indicated in Issue 13 below, IHE ITI welcomes community feedback on the harmonization of IUA and SMART.

Open Issues and Questions

Closed Issues

IHE Technical Frameworks General Introduction Appendices

| Editor: Please update the following appendices to the General Introduction as indicated below. Note that these are not appendices to this domain’s Technical Framework but rather, they are appendices to the IHE Technical Frameworks General Introduction. | |————————————————————————————————————————————————————————————–|

Appendix A - Actor Summary Definitions

| Editor: Please Add the following actors to the IHE Technical Frameworks General Introduction list of actors: | |—————————————————————————————————————–|

 

Actor Definition
Authorization Client A client that retrieves access tokens and presents them as part of transactions.
Authorization Server A server that issues access tokens to requesting clients.
Resource Server A server that provides services that need authorization.

Appendix B - Transaction Summary Definitions

| Editor: Please add the following transactions to the IHE Technical Frameworks General Introduction list of Transactions: | |—————————————————————————————————————————–|

 

Transaction Definition
Incorporate Access Token [ITI-72] Add an access token to a transaction.
Get Access Token [ITI-71] Request and obtain an access token for use in authorized transactions.
Introspect Token [ITI-102] Obtain the state and claims associated with an access token.
Get Authorization Server Metadata [ITI-103] Obtain metadata about a Authorization Server, such as endpoint locations and signing key material.

Volume 1 – Profiles

| Editor: Please add the following Section 34 to Volume 1 | |————————————————————|

34 Internet User Authorization (IUA) Profile

The IUA Profile adds authorization information to HTTP RESTful transactions. The IUA actors and behavior can be added to other profiles and transactions that need authorization.

The actors in the IUA Profile manage the access tokens used for authorization of access to HTTP RESTful services based on the flows and transactions defined in the OAuth 2.1 Authorization Framework [OAuth 2.1]. Authorization Clients interact with the Authorization Server to retrieve access tokens and incorporate them into HTTP RESTful transactions to authorize access to resources on the Resource Servers.

The OAuth 2.1 Authorization Framework requires client identification, which may be based on a client_id parameter [OAuth 2.1, Section 2.2]. Depending on the grant type, the use of the client_id may be required. For example, the Authorization Code grant type requires the use of the client_id for client identification [OAuth 2.1, Section 4.1], while the Client Credential grant type does not [OAuth 2.1, Section 4.2].

The OAuth 2.1 Authorization Framework also requires client authentication for confidential and credential clients [OAuth 2.1, Section 2.3]. It recommends the use of asymmetric (public-key based) methods for client authentication [OAuth 2.1, Section 9.1], but allows other suitable HTTP-based authentication schemes matching the security policy of the Authorization Server [OAuth 2.1, Section 2.3.2].

This profile requires the capability of a client_id for client identification and a client_secret used with the HTTP Basic Authentication scheme for client authentication of confidential and credentialed clients. Other methods for identification and authentication are allowed.

Depending on the grant type, the OAuth 2.1 Framework also requires user authentication. For example, the Authorization Code grant type covered by this profile requires user authentication [OAuth 2.1, Section 4.1], while the Client Credential grant type does not [OAuth 2.1, Section 4.2]. The methods used by the Authorization Server to authenticate the user (e.g., username and password login, session cookies, delegation to Authentication Server) are not scoped in the OAuth 2.1 Authorization Framework [OAuth 2.1, Section 3.1].

Since user authentication methods chosen depend on the projects or national security policy, they are not constrained in the IUA Profile and shall be defined in the specific implementation projects or national extensions of this profile. If the user authentication is not implemented in the Authorization Server, the use of OpenID Connect with the Authorization Grant or Hybrid flow is recommended.

It is the responsibility of the Resource Server to enforce the access policies based on the transaction performed and the information provided in the access token. Therefore, the Resource Server must be able to rely upon the decisions made by the Authorization Server (e.g., client identification, user authentication) which requires that a trust relation between the Resource Server and the Authorization Server was established beforehand.

The Resource Server may delegate the access policy enforcement to actors it is grouped with by providing the information from the access token and transaction data, or to other actors (e.g., by implementing the Authorization Decisions Verifier actor of the Secure Retrieve (SeR) Profile).

Note: An analogy of the segregation of duties for access control between the Authorization Server and the Resource Server is given in a textbook (Solving Identity Management in Modern Applications, APress 2019 by Yvonne Wilson and Abhishek Hingnikar) comparing the authorization and policy enforcement with a ticketing and entrance control to events (e.g., opera, cinema). In this analogy, the Authorization Server provides the ticket which authorizes participation, while additional checks are performed to finally participate in the event.

The IUA Profile relies on the OAuth 2.1 Authorization Framework. Since the original publication of OAuth 2.0 in 2012, several new RFCs have been published that add or remove functionality from the core specification. Version 2.1 of the OAuth Authorization Framework consolidates and simplifies the most commonly used features and best practices of OAuth 2.0.

34.1 IUA Actors, Transactions, and Content Modules

This section defines the actors, transactions, and/or content modules in this profile. General definitions of actors are given in the Technical Frameworks General Introduction Appendix A. IHE Transactions can be found in the Technical Frameworks General Introduction Appendix B. Both appendices are located at http://ihe.net/Technical_Frameworks/#GenIntro.

Figure 34.1-1 shows the actors directly involved in the IUA Profile and the relevant transactions between them. If needed for context, other actors that may be indirectly involved due to their participation in other related profiles are shown in dotted lines. Actors which have a required grouping are shown in conjoined boxes (see Section 34.3).

IUA Actor Diagram

Figure 34.1-1: IUA Actor Diagram

Table 34.1-1 lists the transactions for each actor directly involved in the IUA Profile. To claim compliance with this profile, an actor shall support all required transactions (labeled “R”) and may support the optional transactions (labeled “O”).

Table 34.1-1: IUA Profile - Actors and Transactions

Actors Transactions Optionality Reference
Authorization Client Get Access Token O ITI TF-2: 3.71
  Incorporate Access Token R ITI TF-2: 3.72
  Get Authorization Server Metadata O ITI TF-2: 3.103
Authorization Server Get Access Token R ITI TF-2: 3.71
  Introspect Token O Note 1 ITI TF-2: 3.102
  Get Authorization Server Metadata O ITI TF-2: 3.103
Resource Server Incorporate Access Token R ITI TF-2: 3.72
  Introspect Token O Note 1 ITI TF-2: 3.102
  Get Authorization Server Metadata O ITI TF-2: 3.103

Note 1: Optionality of this transaction is “R” for an actor that supports the Token Introspection Option.

34.1.1 Actor Descriptions and Actor Profile Requirements

Most requirements are documented in ITI TF-2 transactions. This section documents any additional requirements on this profile’s actors.

34.1.1.1 Authorization Client

The Authorization Client performs the network transactions and user interactions needed to obtain an access token and to attach that token to transactions to indicate that the transactions are authorized.

When Incorporate Access Token [ITI-72] is used with a FHIR server, an Authorization Client should query the capabilities endpoint on the Resource Server to determine if the Resource Server supports IUA. The element CapabilityStatement.rest.security.service will be populated with the code “IUA” at system canonical URL “http://profiles.ihe.net/fhir/ihe.securityTypes/CodeSystem/securityTypes”. The CodeSystem can be retrieved from the IHE FHIR GitHub repository, codesystem-IHE_securitytypes.xml.

34.1.1.2 Authorization Server

The Authorization Server provides access tokens to requesting clients. In IUA, the Authorization Server uses an authenticated user identity, the requested HTTP RESTful service URL to the Resource Server, and/or other information to determine whether HTTP RESTful transactions are authorized. If authorized, the Authorization Server provides an access token which authorizes the client to retrieve data and documents from the Resource Server.

The Get Access Token [ITI-71] transaction is scoped to the Authorization Code and Client Credential grant types (see Section 34.4.1.1 Authorization Grant Types). The Authorization Server shall support these grant types:

34.1.1.3 Resource Server

The Resource Server provides services to access protected resources that need authorization. In IUA, the Resource Server accepts an HTTP RESTful transaction request with an incorporated access token. It evaluates the access token to verify that the Authorization Server has authorized the transaction. The Resource Server shall enforce this authorization and may perform additional authorization decisions that are specific to the requested service. The Resource Server may then allow the transaction to proceed, subject to access control constraints that may be in place.

In general, Resource Servers perform additional access control decisions and may restrict responses even for transactions authorized by the Authorization Server.

When the Incorporate Access Token [ITI-72] transaction is used with a FHIR server, the Resource Server shall declare support for IUA in the capabilities endpoint using the element CapabilityStatement.rest.security.service and the code “IUA” at system canonical URL “http://profiles.ihe.net/fhir/ihe.securityTypes/CodeSystem/securityTypes”. The CodeSystem can be retrieved from the IHE FHIR GitHub repository, codesystem-IHE_securitytypes.xml.

The Authorization Server may support these grant types (see Section 34.4.1.1 Authorization Grant Types):

The Resource Servers and Authorization Servers may be grouped into an integrated product together with user authentication, access control, and other services.

34.2 IUA Actor Options

Options that may be selected for each actor in this profile are listed in the Table 34.2-1. Dependencies between options, when applicable, are specified in notes.

Table 34.2-1: IUA - Actors and Options

IUA Actor Option Reference
Authorization Client Authorization Server Metadata Section 34.2.1
Authorization Server JWT Token (Note 1) Section 34.2.2
  SAML Token (Note 1) Section 34.2.3
  Token Introspection (Note 1) Section 34.2.4
  Authorization Server Metadata Section 34.2.1
Resource Server JWT Token (Note 1) Section 34.2.2
  SAML Token (Note 1) Section 34.2.3
  Token Introspection (Note 1) Section 34.2.4
  Authorization Server Metadata Section 34.2.1

Note 1: Authorization Server or Resource Server Actors shall support at least one of the following options: JWT Token, SAML, or Token Introspection. The Authorization Client is not and does not need to be aware of the token processing options.

34.2.1 Authorization Server Metadata Option

This option enables automated configuration of Resource Servers and Authorization Clients by enabling them to pull configuration metadata directly from the Authorization Server.

An Authorization Client that supports this option shall have the means to be configured to interact with an Authorization Server metadata endpoint to retrieve configuration information.

Authorization Servers supporting the Authorization Server Metadata Option shall provide a metadata endpoint that provides configuration information to Authorization Client and Resource Servers. This information includes endpoint locations, supported authentication grants and signing key materials.

Resource Servers supporting the Authorization Server Metadata Option shall have the means to be configured to interact with an Authorization Server metadata endpoint to retrieve configuration information.

See ITI TF-2: 3.103 for transaction requirements.

34.2.2 JWT Token Option

This option uses JSON Web Token encoding as access token issued by the Authorization Server. The JSON Web Token constraints are defined in ITI TF-2: 3.71.4.2.2.1.

An Authorization Servers that supports this option shall provide an endpoint to retrieve JWT access tokens to be incorporated in RESTful requests to Resource Servers.

A Resource Server that supports this option shall be able to accept JWT access tokens in RESTful requests, to extract and validate the information provided in the JWT access token, and to enforce access policies based on it.

See ITI TF-2: 3.71.4.2.2.1 for transaction requirements.

34.2.3 SAML Token Option

This option enables integration of environments that use both the xXUA-compatible SAML access token and the OAuth authorization infrastructure.

An Authorization Servers that supports this option shall provide an endpoint to retrieve XUA-compliant SAML 2.0 access tokens to be incorporated in RESTful requests to Resource Servers.

A Resource Server that supports this option shall be able to accept XUA-compliant access tokens in RESTful requests, to extract and validate the information provided in the token, and to enforce access policies based on it.

See ITI TF-2: 3.71.4.2.2.2 for transaction requirements.

34.2.4 Token Introspection Option

Actors that support this option use the Token Introspection [ITI-102] transaction to validate and obtain the claims associated with an access token. Introspection allows for custom token formats and re-evaluation of tokens after commission (enabling features like token revocation), at the cost of introspection calls to the Authorization Server.

An Authorization Server that supports the Token Introspection option shall provide an endpoint that Resource Servers will use to validate and evaluate the access token. With this option, the Authorization Server may provide token formats other than JWT or SAML. Using this option, the token can be treated as an opaque data construct for Resource Servers. When Token Introspection option is used, the Authorization Server shall provide the Token Introspection [ITI-102] transaction service.

A Resource Server that supports the Token Introspection Option shall have the ability to use the Token Introspection [ITI-102] transaction to obtain the details of the token from the Authorization Server. This transaction can be used by the Resource Server when it is uncertain about the format of the token (JWT, SAML, or opaque), or when it wants to re-evaluate the authorization policy. To be able to invoke the introspection endpoint, the Resource Server must authenticate itself. It may obtain an access token of its own from the Authorization Server for this purpose.

See ITI TF-2: 3.102 Introspect Token for transaction requirements.

34.3 IUA Required Actor Groupings

An actor from this profile shall implement the required transactions and/or content modules in this profile in addition to all of the transactions required for the grouped actor (Column 2).

Table 34.3-1: Required Actor Groupings

IUA Actor Actor to be grouped with Reference Content Bindings Reference
Authorization Server CT / Time Client ITI TF-1:7 Consistent Time
Resource Server CT / Time Client ITI TF-1:7 Consistent Time
Authorization Client

The IUA actors are expected to be grouped with other actors that perform HTTP RESTful transaction:

34.4 IUA Overview

34.4.1 Concepts

The term “authorization” and “access control” are used colloquially for a variety of related activities. All of the concepts listed below are sometimes called “authorization” or “access control”. See the IHE ITI Access Control white paper for a detailed discussion of Access Control concepts. This profile will use more specific terms for each of these activities. These are:

34.4.1.1 Authorization Grant Types

The OAuth 2.1 Authorization Framework [OAuth 2.1, Section 4] defines the following authorization grant types:

The OAuth 2.1 Authorization Framework further defines extension points to implement extension grant types [OAuth 2.1, Section 4.3], specifically:

The SAML and JWT grants from RFC7522 and RFC7523 may be used in federation scenarios where an Authorization Server will accept tokens from another Authorization Server as credentials for issuing access tokens.

Both the RFC7522 and RFC7523 require the existence of a public key infrastructure. The operational aspects of such infrastructure are beyond the scope of this specification.

34.4.1.2 Terminology

The IUA Profile uses the terms “access token”, “refresh token”, “bearer token”, “Authorization Server”, “Resource Server”, “authorization endpoint”, “authorization request”, “authorization response”, “token endpoint”, “grant type”, “access token request”, and “access token response” as defined by The OAuth 2.1 Authorization Framework [OAuth 2.1].

This profile also uses the terms “token introspection”, “introspection endpoint”, “introspection request”, and “introspection response” as defined by the OAuth2 Token Introspection specification [RFC7662].

The OAuth 2.1 Authorization Framework uses the term “resource owner” for the user an authorized client may access data on behalf of. Typically, in health related environments, a healthcare professional accesses patients or organization related data (resources) for which the healthcare professional is not the “legal owner”, but may access according to the access policies of the environment. To avoid any misunderstandings related to the OAuth terms “resource owner” and “legal owner”, this profile uses the term “user” instead.

In accordance with the definitions in the OAuth 2.1 Authorization Framework [OAuth 2.1], this profile distinguishes confidential clients, credentialed clients, and public clients as follows:

Note: A public client classification does not automatically mean the client is insecure. Public clients typically are under the full control of the user (e.g., a native app on the user’s device) and secured against malicious attacks. Public clients just cannot hide authentication data from the user, making client authentication useless.

34.4.2 Use Cases

34.4.2.1 Authorization Use Cases

The IUA Profile applies to use cases where a user authorizes a client application to access health data on behalf of the user using OAuth, including:

The limitation of the scope is common to all use cases and one of the key concepts of OAuth to ensure data privacy protection by user consent. While the need for restricting the scope might be less obvious for primary system applications, it is apparent for mobile or web applications that provide specific services for patients or healthcare professionals, e.g., for medication or vaccinations or other specific use cases. Therefore, in general, an Authorization Server will present a form to the user to consent to an application specific and limited scope, e.g., to specific transactions, document types or classes, or subject-specific data the application is authorized to access.

34.4.2.2 Process Flow

Figure 34.4.2.2-1 shows the basis flow of information exchange common to IUA use cases.

ITI-71 Flow Diagram

Figure 34.4.2.2-1: Basic Process of the Access Token Request and Incorporate Access Token transaction

@startuml basic-flow

participant "Authorization Client" as Client
participant "Authorization Server" as AS
participant "Resource Server" as RS

autonumber 0 1 "<b>[00]</b>"
autoactivate on

group (optional) Get Authorization Server Metadata (ITI-103)

    Client-> AS : Authorization Server Metadata Request (ITI-103)
    AS --> Client: Authorization Server Metadata Response

    RS-> AS : Authorization Server Metadata Request (ITI-103)
    AS --> RS: Authorization Server Metadata Response

end

group Get Access Token (ITI-71)
    Client -> AS: Get Access Token Request
    Client <-- AS: Get Access Token Response
end

group Incorporate Access Token (ITI-72)

Client -> RS : Resource Request + Incorporate Access Token

alt JWT or SAML token
  RS -> RS: validate token
  deactivate RS

else introspect token

  group Introspect Token (ITI-102)
        RS -> AS : Introspect Token Request
        AS --> RS: Introspect Token Response
  end
end

Client <-- RS : Resource Response  
end

@enduml

Process Flow:

  1. (Optional) The Authorization Client fetches the metadata document from the Authorization Server to detect the relevant authorization endpoints, and supported grant types.

  2. (Optional) The Resource Server fetches the metadata document from the Authorization Server to detect the supported token format, relevant introspection endpoints, and signature verification key material.

  3. The Authorization Client authenticates to the Authorization Server and (optionally) provides claims related to the intended request to access protected resources of a Resource Server.

  4. The Authorization Server authenticates the client, validates the claims against any policy rules (such as user consent) and returns an access token that authorizes the Authorization Client to request the protected resources from Resource Servers. This may entail interaction with the user to establish user authentication and/or consent.

  5. The Authorization Client incorporates the access token to the requests of the protected resources to Resource Servers.

  6. The Resource Server obtains the claims associated with the access token. This may involve local validation of structured tokens or an additional token introspection request towards the Authorization Server.

  7. The Resource Server evaluates the claims and the request against a configured access policy and determines whether the client has access to the requested resources. If permitted, the Resource Server will return the requested resources.

34.5 IUA Security Considerations

IUA uses OAuth 2.1 which contains references to security analyses. There are also a variety of analyses available in the public literature. The IUA Profile does not introduce new considerations to those analyses and has not identified any new issues specific to healthcare.

For confidential clients, this profile requires client authentication using client_id and client_secret, if no other reliable client authentication method is used, and the client registration with a fixed redirect_uri.

IUA does not address issues around issuing and revoking client_ids. OAuth 2.1 relies upon the client_id for client identification and authorization. OAuth 2.1 does not further define how client_ids are managed.

Usually an Authorization Server publishes web forms where system administrators and users can apply for a client_id. OAuth 2.1 defines a mechanism for dynamically registering clients with Authorization Servers, by defining a set of desired client metadata values to be made available to the Authorization Servers [OAuth 2.1, Section 2].

The Authorization Server will have an administratively-managed list of approved client_ids for accepted clients. This list will be updated as new clients are approved or existing clients are removed. An access token will not be issued for unapproved clients. This assumes that the client_id management will deal with these security considerations in a manner similar to the certificate management assumptions made for secure communication transactions.

The Authorization Server will typically have an administratively-managed list of approved Resource Servers. The list of Resource Servers is used in access control decisions to determine if a client has access to a Resource Server. These access control decisions take place when an access token is created, are associated with the access token, and may be re-evaluated when an access token is introspected. Introspection is initiated by a Resource Server just prior to servicing a client request. Introspection can therefore be used to signal token revocation, or to provide Resource Server-specific authorization results (such as a limited view on the authorized scopes).

34.6 IUA Cross Profile Considerations

The Cross-Enterprise User Assertion (XUA) Profile provides equivalent functionality as IUA, but for SOAP-based transactions. Both XUA and IUA define a transaction to incorporate a token into other IHE transactions accessing protected data. These profiles have much in common, but also some remarkable differences:

The SAML Token Option in IUA enables an Authorization Client to incorporate access token originally retrieved and issued from a XUA X-Assertion Provider and use it in the Incorporate Access Token [ITI-72] transaction, when accessing protected data from a Resource Server via RESTful transactions.

Volume 2 – Transactions

| Editor: Please add Section 3.71 | |————————————|

3.71 Get Access Token [ITI-71]

3.71.1 Scope

This transaction is used by an Authorization Client to retrieve an OAuth 2.1-compliant access token.

3.71.2 Actor Roles

This profile defines the following actors and roles:

Table 3.71.2-1: Actor Roles

Actor Role
Authorization Client Client requesting an access token to authorize RESTful transactions
Authorization Server Server that grants access tokens.

3.71.3 Referenced Standards

This transaction relies on standards defined in the following documents and the references therein:

3.71.4 Messages

3.71.4.1 Get Access Token Request

3.71.4.1.1 Trigger Events

The Get Access Token Request is performed by an Authorization Client or Resource Server (in case of the Introspect Option) to obtain an access token to be used in further communication. The sequence of HTTP(S) requests to perform a Get Access Token transaction depends on the grant type (type of credentials) chosen.

3.71.4.1.2 Message Semantics

This transaction supports two distinct grants for obtaining an access token. These grants require their own variation in message sequences as depicted in the following sections:

3.71.4.1.2.1 Client Credential grant type

ITI-71 Client Credential

Figure 3.71.4.1.2.1-1: Sequence of HTTP requests in the client credential grant type.

@startuml client-credential-grant

participant "Authorization Client" as Client
participant "Authorization Server" as AuthzServer

autonumber 0 1 "<b>[00]</b>"

group Get Access Token (ITI-71) [Client Credentials Grant]
Client -> AuthzServer: Get Access Token Request
AuthzServer --> Client: Get Access Token Response
end

autonumber stop

@enduml

The Authorization Client requests an access token using client credentials (or other supported means of authentication). This grant type shall be used by confidential clients only [OAuth 2.1, Section 4.2].

The Authorization Client makes a HTTP(s) POST request to the token endpoint with the following parameters in the HTTP request entity-body [OAuth 2.1, Section 4.2.2]:

The request shall use the application/x-www-form-urlencoded format with a character encoding of UTF-8 [OAuth 2.1, Section 4.2.2].

The Authorization Client shall present its client_id and client_secret in a HTTP Basic Authentication Header to the Authorization Server.

Figure 3.71.4.1.2.1-2 is a non-normative example of the access token request with client authentication using the client_id and client_secret in the HTTP Authorization header:

POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&scope=scope_1 scope_2 ... scope_N
&resource=https://rs.example.com/

Figure 3.71.4.1.2.1-2: Example Access Token Request

An Authorization Client that supports the Get Authorization Server Metadata Option shall use the token_endpoint URL from the Authorization Server Metadata Document to obtain the access token; see ITI TF-2: 3.103 Get Authorization Server Metadata.

3.71.4.1.2.2 Authorization Code grant type

ITI-71 Authorization Code

Figure 3.71.4.1.2.2-1: Sequence of HTTP requests in the client authorization code grant type

@startuml authorization-code-grant

actor User

participant "User Agent" as UserAgent
participant "Authorization Client" as Client
participant "Authorization Server" as AuthzServer

autonumber 0 1 "<b>[00]</b>"

group Get Access Token (ITI-71) [Authorization Code Grant]
Client -> UserAgent: Redirect to Authorization Server \n(authorization request incl requested scopes, resource, etc.)
UserAgent -> AuthzServer: authorization request

note over User, AuthzServer
  Authorization Server determines access based on
  user authentication, consent and/or other policies.
end note

AuthzServer -> UserAgent: Redirect to Client \n(authorization response with Authorization Code)
UserAgent -> Client: authorization response

Client -> AuthzServer: Get Access Token Request \n(client credentials + Authorization Code)
AuthzServer --> Client: Get Access Token Response (access token)
end

@enduml

This grant type shall be used by confidential, credential and public clients, if the explicit consent of the user is required to authorize the Authorization Client to access data on behalf of the user.

An Authorization Client that supports the Authorization Server Metadata Option shall use the “authorization_endpoint” URL from the Authorization Server Metadata Document to redirect the User-Agent.

The Authorization Client directs the user-agent to make a HTTP GET request to the authorization endpoint with the following parameters using the “application/x-www-form-urlencoded” format [OAuth 2.1, Section 4.1.1.3]:

Figure 3.71.4.1.2.2-2 is a non-normative example of the authorization request:

GET /authorize?
  response_type=code
  &client\_id=s6BhdRkqt3
  &state=xyz
  &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
  &code_challenge=6fdkQaPm51l13DSukcAH3Mdx7_ntecHYd1vi3n0hMZY
  &code_challenge_method=S256
  &resource=https%3A%2F%2Frs.example.com%2F
  &scope=scope_1%20scope_2%20scope_N
  HTTP/1.1
Host: server.example.com

Figure 3.71.4.1.2.2-2: Example Authorization Request

If the access request is granted (by the user or some other access policy), the Authorization Server issues an authorization code.

The Authorization Server shall redirect the user agent to the Authorization Client’s redirect URI with the authorization response parameter in the application/x-www-form-urlencoded format. The response parameter shall be as follows:

HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz

The Authorization Client shall use the authorization code in an access token request to retrieve an access token and token metadata from the Authorization Server.

An Authorization Client that supports the Get Authorization Server Metadata Option shall use the “token_endpoint” URL from the Authorization Server Metadata Document to obtain the access token.

The Authorization Client makes a HTTP POST request to the token endpoint with the following parameters in the HTTP request entity-body [OAuth 2.1, Section 4.1.3]:

Figure 3.71.4.1.2.2-3 shows a non-normative example of the access token request with client authentication using the client_id and client_secret in the HTTP Authorization header:

POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
&code_verifier=3641a2d12d66101249cdf7a79c000c1f8c05d2aafcf14bf146497bed

Figure 3.71.4.1.2.2-3: Example Access Token Request

3.71.4.1.3 Expected Actions

The Authorization Server, upon receiving a Get Access Token Request, validates all request parameters.

The scope parameter incorporated in the token requests shall be used to restrict authorization grants to specific actions (e.g., restrict authorization to specific resources to read-only) and to convey claims, which at runtime are known to the Authorization Client only (e.g., if the user claims a breaking-the-glass access in a emergency situation). The Authorization Server may refuse token requests that mention scope values that are unknown to the Authorization Server.

Authorization Servers should limit the list of identifiers in the audience claim to a minimum to avoid token misuse by unintended parties.

The Authorization Client is recommended to provide a resource value to limit usability of the requested token to the intended Resource Server. If provided, the Authorization Server should evaluate any resource values provided as part of the token request procedure. The Authorization Server should execute policies to detect whether the client has access to the indicated resource. If the Authorization Client presented a resource value in the token request, the Authorization Servers shall limit the list of Resource Server identifiers in the audience claim to only those that are essential to interact with the specified resource (typically only the Resource Server itself).

If the request is valid and all access policy criteria are met, the Authorization Server shall respond with the access token response as outlined in Section 3.71.4.2 Get Access Token Response.

If the authorization request is invalid, the Authorization Server shall react as defined in [OAuth 2.1, Section 4.1.2.1].

3.71.4.1.3.1 Client Credential grant type

The Authorization Server shall authenticate the Authorization Client using its client identifier and secret as communicated in the HTTP Authorization header.

The Authorization Server shall verify the access token request as described in [OAuth 2.1, Section 4.2.2].

3.71.4.1.3.2 Authorization Code grant type

The Authorization Server shall authenticate confidential and credential clients using the client_id and client_secret, or by other reliable client authentication method. In the latter case, the Authorization Server shall resolve the client authentication to a client_id which was registered beforehand.

The Authorization Server shall verify that all required parameters of the authorization request are present and valid. If valid, the Authorization Server shall authenticate the user and obtain the user consent (by presenting the user a form to authorize specific scopes or by establishing approval via other means). When the user consent is established, the Authorization Server shall issue an authorization code to the client redirect URI conveying the authorization code and client state value.

The Authorization Client shall use the authorization code to request the access token from the Authorization Server. The Authorization Server shall verify the access token request as described in [OAuth 2.1, Section 4.1.3].

3.71.4.2 Get Access Token Response

3.71.4.2.1 Trigger Event

The Get Access Token Response is returned by an Authorization Server upon request from an Authorization Client to obtain an access token to be used in further communication.

3.71.4.2.2 Message Semantics

The Authorization Server shall respond an error response as defined in the OAuth 2.1 Authorization Framework [OAuth 2.1, Section 5.2] if the request does not match the requirements or is not understood.

If the access token request is valid and authorized, the Authorization Server responds with the access token response message in JSON format with the following attributes [OAuth 2.1, Section 4.2.3]:

The access token response may contain other parameter or extensions depending on the implementation details of the Authorization Server [OAuth 2.1, Section 4.2.3].

The Authorization Server shall include the HTTP Cache-Control response header field with value no-store and the Pragma response header field value no-cache to the access token response [OAuth 2.1, Section 4.2.3].

Figure 3.71.4.2.2-1 is non-normative example of the access token response:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
  "token_type": "Bearer",
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "scope": "scope_1 scope_2 ... scope_M",
  "expires_in": 3600,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "example_parameter": "example_value"
}

Figure 3.71.4.2.2-1: Example Access Token Response

3.71.4.2.2.1 JSON Web Token Option

The OAuth2 specifications does not indicate the structure of the access token. Actors conforming to the JSON Web Token Option shall support access tokens formatted as signed JWT Tokens.

JWT token shall be signed as specified in JSON Web Signature [RFC7515]. If signed, the JWS Compact Serialization (base64 encoded, with single signature or MACed) shall be used as described in [RFC7515, Section 7.1].

Any actor may support the JWE (unsigned but encrypted) alternative of the JWT token.

Of the signature of JWT algorithms specified in the JSON Web Algorithms [RFC7518], the following algorithms shall be supported:

Other algorithms such as ES256: ECDSA using P-256 curve and the SHA-256 hash algorithm (“ES256”) are recommended.

Other algorithms may be supported except the “NONE” that shall not be used.

Note: It is recommended to use asymmetric (public-key based, e.g., RS256) methods for signing access token. When asymmetric methods are used, a Resource Server does not need to store sensitive symmetric keys, making these methods more robust against malicious attacks.

In the JSON Web Token Option, the access token is defined as JSON object with the following attributes:

The JWT access token may contain other parameters or extensions depending on the implementation details.

3.71.4.2.2.1.1 JWT IUA extension

The Authorization Server and Resource Server shall support the following extensions to the JWT access token:

The above claims shall be wrapped in an “extensions” object with key ‘ihe_iua’ and a JSON value object containing the claims. For example:

"extensions" : {  
  "ihe_iua" : {  
    "subject_name": "Dr. John Smith",
    "subject_organization": "Central Hospital",
    "subject_organization_id": "urn:oid:1.2.3.4",
    "other_value": "..."  
  }  
}

The claim content shall correspond to the content defined in the XUA specification (see ITI TF-2: 3.40.4.1.2 Message Semantics).

The mapping of IUA extension claims to XUA-compliant SAML 2.0 Assertion attributes is shown in Table 3.71.3.2.2.1-1 below.

Table 3.71.4.2.2.1.1-1: JWT claims of the IUA extension and corresponding XUA Assertion attributes

JWT Claim XUA Attribute
subject_name urn:oasis:names:tc:xspa:1.0:subject:subject-id
subject_organization urn:oasis:names:tc:xspa:1.0:subject:organization
subject_organization_id urn:oasis:names:tc:xspa:1.0:subject:organization-id
subject_role urn:oasis:names:tc:xacml:2.0:subject:role
purpose_of_use urn:oasis:names:tc:xspa:1.0:subject:purposeofuse
home_community_id urn:ihe:iti:xca:2010:homeCommunityId
national_provider_identifier urn:oasis:names:tc:xspa:1.0:subject:npi
person_id not defined

3.71.4.2.2.1.2 JWT BPPC extension

In an environment that uses the IHE Basic Patient Privacy Consents (BPPC) Profile for documenting the consent, the Authorization Server and Resource Server shall support the following extension parameter:

If present, the claims shall be wrapped in an “extensions” object with key ‘ihe_bppc’ and a JSON value object containing the claims, e.g.,

"extensions" : {  
  "ihe_bppc" : {  
    "patient_id": "543797436^^^&amp;1.2.840.113619.6.197&amp;ISO",
    "doc_id": "urn:oid:1.2.3.xxx",
    "acp": "urn:oid:1.2.3.yyyy",
    "other_value": "..."    
  }  
}

The mapping of IUA extension claims to XUA-compliant SAML 2.0 Assertion attributes is shown in Table 3.71.4.2.2.1.2-1.

Table 3.71.4.2.2.1.2-1: JWT claims of the BPPC extension and corresponding XUA Assertion attributes

JWT Claim XUA Attribute
patient_id urn:oasis:names:tc:xacml:2.0:resource:resource-id
doc_id urn:ihe:iti:bppc:2007:docid
acp urn:ihe:iti:xua:2012:acp

3.71.4.2.2.1.3 Example

The following is a non-normative example of JWT access token:

JOSE Header:

{
"typ": "IUA-JWT",
"alg": "HS256"
}

JWS Payload:

{
    "iss": "urn:tiani-spirit:sts",
    "sub": "b3ca1045-aa8b-42f9-9fd9-e0cbf5cb90a7",
    "aud": "http://ihe.connectathon.IUA/ResourceProvider-IHE-Connectathon",
    "exp": 1438251487,
    "nbf": 1438251187,
    "iat": 1438251187,
    "scope": "ITI-68",    
    "extensions" : {  
      "ihe_iua" : {  
        "subject_name": "Dr. John Smith",
        "subject_organization": "Central Hospital",
        "subject_organization_id": "urn:oid:1.2.3.4",
        "home_community_id": "urn:oid:1.2.3.4.5.6.7.8",
        "person_id": "urn:uuid:1.2.3.4",
        "subject_role": [
          {
            "system": "2.16.840.1.113883.6.96",
            "code": "46255001",
            "display": "Pharmacist"
          }
        ],
        "purpose_of_use": [
          {
            "system": "1.0.14265.1",
            "code": "12",
            "display": "Law Enforcement"
          }
        ]
      }
    }
}
3.71.4.2.2.2 SAML Token Option

An Authorization Server that supports the SAML Token Options shall be able to format the access token as a SAML 2.0 assertion.

The SAML 2.0 assertion content shall comply with XUA SAML assertion rules (see ITI TF-2: 3.40).

In accordance with [RFC7522, Section 2.2], the value of the access token contains a SAML 2.0 Assertion. It shall not contain more than one SAML 2.0 Assertion. The SAML Assertion XML data must be encoded using base64url, where the encoding adheres to the definition in Section 5 of RFC4648 [RFC4648] and where the padding bits are set to zero. To avoid the need for subsequent encoding steps (by “application/x-www-form-urlencoded” [W3C.REC-html401-19991224], for example), the base64url-encoded data must not be line wrapped and pad characters (“=”) must not be included.

3.71.4.2.2.3 Token Introspection Option

Actors that support the Token Introspection Option shall provide a non-empty, unique and non-guessable access token value.

The access token may be a structured value, for example using the JWT or SAML token formats as described in Sections 3.71.4.2.2.1 and 3.71.4.2.2.2. Alternatively, the token may be a opaque identifier pointing to a stored record of claims retrievable by the Authorization Server.

The Authorization Server shall have means to retrieve the claims associated with the access token during token introspection (for details see ITI TF-2: 3.102 Introspect Token).

3.71.5 Security Considerations

Authorization Client and Authorization Server that support with this transaction shall fulfill the security requirements defined in the OAuth Authorization Framework [OAuth 2.1], including:

Authorization Servers should limit the list of identifiers in the audience claim to a minimum to avoid token misuse by unintended parties.

The Authorization Client is recommended to provide a resource value to limit usability of the requested token to the intended Resource Server. If provided, the Authorization Server should evaluate any resource values provided as part of the token request procedure. The Authorization Server should execute policies to detect whether the client has access to the indicated resource. If the Authorization Client presented a resource value in the token request, the Authorization Servers shall limit the list of Resource Server identifiers in the audience claim to only those that are essential to interact with the specified resource (typically only the Resource Server itself).

3.71.5.1 Security Audit Considerations

The Authorization Client or Authorization Server that is grouped with an ATNA Secure Node or Secure Application shall be able to send an audit event as defined below:

  Field Name Opt Value Constraints
Event
(AuditMessage/EventIdentification)
EventID M EV(110114, DCM, “User Authentication”)
  EventActionCode M “E” (Execute)
  EventDateTime M not specialized
  EventOutcomeIndicator M not specialized
  EventTypeCode M EV(“ITI-71”, IHE, “User Authorization”)
Source (1)      
Human Requestor (0)      
Destination (0)      
Audit Source (Client Authentication Agent) (1)      
Participant Object (1)      

Where:

  Field Name Opt Value Constraints
Source
(AuditMessage/ActiveParticipant)
UserID M The process ID as used within the local operating system in the local system logs.
  Alternative UserID U not specialized
  UserName U not specialized
  UserIsRequestor M not specialized
  RoleIDCode M EV(110150, DCM, “Application”)
  NetworkAccessPointTypeCode M “1” for machine (DNS) name, “2” for IP address
  NetworkAccessPointID M The machine name or IP address
Audit Source
AuditMessage/ AuditSourceIdentification
AuditSourceID U not specialized
  AuditEnterpriseSiteID U not specialized
  AuditSourceTypeCode U not specialized
Token
(AuditMessage/ ParticipantObjectIdentification)
ParticipantObjectTypeCode M “2” (System)
  ParticipantObjectTypeCodeRole M “13” (Security Resource)
  ParticipantObjectDataLifeCycle U not specialized
  ParticipantObjectIDTypeCode U not specialized
  ParticipantObjectSensitivity U not specialized
  ParticipantObjectID U not specialized
  ParticipantObjectName U not specialized
  ParticipantObjectQuery M URL requested
  ParticipantObjectDetail U not specialized

| Editor: Please add Section 3.72 | |————————————|

3.72 Incorporate Access Token [ITI-72]

3.72.1 Scope

This transaction is used to incorporate authorization information into HTTP RESTful transactions.

3.72.2 Actor Roles

Table 3.72.2-1: Actor Roles

Actor Role
Authorization Client Authorization component of a HTTP RESTful transaction client.
Resource Server Authorization component of a HTTP RESTful transaction server.

3.72.3 Referenced Standards

This transaction relies on standards defined in the following documents and the references therein:

XUA Cross-Enterprise User Assertion (XUA) – Attribute Extension

3.72.4 Messages

simple-iauth

Figure 3.72.4-1: Process flow for Incorporate Access Token Transaction

@startuml incorporate-token

participant "Authorization Client" as client
participant "Resource Server" as rs
participant "Authorization Server" as as

group Incorporate Access Token (ITI-72)

client -> rs : Resource Request + Access Token

alt JWT or SAML token
  rs -> rs: validate token

else introspect token
    rs -> as : Introspect Token (ITI-102)
    as --> rs: token claims
end

client <-- rs : Resource Response  
end  
@enduml

Main Flow:

  1. The Authorization Client sends a resource request to a Resource Server, together with the access token. The token is opaque to the Authorization Client.

  2. The Resource Server identifies the format of the token, validates the token, and obtains the claims associated with the token. To this end it may use the Authorization Server metadata, such as signing keys (for JWT or SAML tokens), or the introspect endpoint location.

  3. The Resource Server makes an access control decision based upon the claims from the access token and the transaction details. It may provide access to the resource, a subset of the resource, or reject the request in total.

This transaction works in conjunction with other HTTP RESTful transaction. It extends the other transaction by adding information to the HTTP request for that HTTP RESTful transaction.

3.72.4.1 Trigger Events

A client needs to make an HTTP RESTful transaction to a Resource Server that enforces access authorization.

3.72.4.2 Message Semantics

The Authorization Client shall incorporate the access token as received from the Authorization Server in a HTTP Authorization header of the type Bearer [OAuth2.1, Bearer token] as-is.

A non-normative example of the access token incorporation to a RESTful transaction is:

GET /example/url/to/resource/location HTTP/1.1
Authorization: Bearer vGHTPOJzh3QFd\[...omitted for brevity...\]99bhgT8Ya
Host: example.com

3.72.4.3 Expected Actions

The Resource Server shall be able to determine the token format (JWT, SAML, or other) by evaluating the “access_token_format” value in the Authorization Server Metadata document (see ITI-103), inspection of the access token value, or some other method.

When the Resource Server is not able to process the token format (through local verification or introspection), it shall respond with HTTP 401 (Unauthorized).

The Resource Server shall validate or introspect the access token and ensure that it has not expired.

If the token includes a scope claim, the Resource Server shall verify that the scope covers the transaction to the requested resource [OAuth 2.1, Section 7].

If the token includes an audience claim, the Resource Server shall verify that the audience includes the Resource Server itself [OAuth 2.1, Section 7].

The Resource Server shall verify that the claims conveyed in the access token match the transaction type and data (e.g., verify that the patient_id attribute of the access token corresponds to the patient_id of the resource request).

In addition, the Resource Server shall enforce the access policies set in the specific environment by matching the information from the access token and the transaction data to the access policies.

If the token verification, or scope matching, or the access policy enforcement fails, the Resource Server shall respond with a HTTP 401 (Unauthorized) error.

Authorization Clients receiving a HTTP 401 (Unauthorized) error should NOT retry the request with the same token. An Authorization Client should reformulate the request or obtain a new token from the Authorization Server before retrying.

3.72.4.3.1 JSON Web Token Option

A Resource Server that supports the JSON Web Token Option shall be able to interpret and validate the access token as a JWT Token as defined in Section 3.71.4.2.2.1.

A Resource Server that supports the Authorization Server Metadata Option (see ITI TF-1: 34.2.1) shall use the keys published through the Authorization Server Metadata Document for validating the JWT token’s signature.

3.72.4.3.2 SAML Token Option

A Resource Server that supports the SAML Token Option shall be able to interpret and validate the access token as a XUA-compliant SAML Assertion as defined in Section 3.71.4.2.2.2.

A Resource Server that supports the Authorization Server Metadata Option (see ITI TF-1: 34.2.1) shall use the keys published through the Authorization Server Metadata Document for validating the SAML token’s signature.

3.72.4.3.3 Introspect Token Option

A Resource Server that supports the Token Introspection Option shall be able to interact with the Authorization Server using the Introspect Token [ITI-102] transaction as described in Section 3.102 to validate the access token and obtain the related claims.

A Resource Server that supports the Authorization Server Metadata Option (see ITI TF-1: 34.2.1) shall use the introspection endpoint published through the Authorization Server Metadata Document for validating the token and obtaining the related claims.

3.72.5 Security Considerations

Authorization Clients and Resource Servers that support this transaction shall fulfill the security requirements defined in the OAuth Authorization Framework [OAuth 2.1], especially:

3.72.5.1 Security Audit Considerations

When an ATNA Audit message needs to be generated by the Resource Server and the user is authenticated by way of a JWT Token, the ATNA Audit message UserName element shall record the JWT Token information using the following encoding:

alias"<"user"@"issuer">"

where:

When an ATNA Audit message needs to be generated by the Resource Server and the user is authenticated by way of a SAML Token, the ATNA Audit message UserName element shall record the SAML token information using the following encoding:

alias"<"user"@"issuer">"

where:

| Editor: Please add Section 3.102 | |————————————-|

3.102 Introspect Token [ITI-102]

Token introspection defines a protocol that allows Resource Servers to query the Authorization Server to determine the set of claims for a given token that was presented to them by an Authorization Client. These claims include whether or not the token is currently active and the authorization context in which the token was granted.

Token introspection allows a Resource Server to query this information regardless of whether or not it is carried in the token itself (e.g., as encoded in a JWT token), allowing this method to be used along with or independently of structured token values.

The Authorization Server may decide to mark a token as active or inactive based on internal policies executed during introspection. For example, a token may be marked inactive if it has expired, been revoked, or if the introspection-requesting Resource Server is not part of the intended audience of the token. Note that the introspection response for inactive tokens does not contain other (privacy/security sensitive) claims, nor does it mention the reason why the token is marked inactive.

Additionally, token introspection is carried out in the context of a particular Resource Server, allowing the returned authorization claims to be tuned to that authorization context. For example, the Authorization Server may limit the list of scopes to those that are deemed relevant for that particular Resource Server.

3.102.1 Scope

This transaction shall be used by Resource Servers to request an OAuth2.1-compliant bearer token evaluation from an Authorization Server.

3.102.2 Actor Roles

Table 3.102.2-1: Actor Roles

Actor Role
Resource Server Introspection Requester
Authorization Server Introspection Responder

3.102.3 Referenced Standards

This transaction relies on standards defined in the following documents and the references therein:

3.102.4 Messages

Introspection entails a single request and response between a Resource Server and an Authorization Server. This flow is typically executed as part of the authorization of RESTful resource request as depicted in ITI TF-1: 34.4.2.2 Process Flow.

ITI-102 Introspect Diagram

Figure 3.102.4-1: ITI-102 Introspect Diagram

@startuml introspect

participant "Resource Server" as ResourceServer
participant "Authorization Server" as AuthzServer

autonumber 0 1 "<b>[00]</b>"
autoactivate on

group Introspect Token (ITI-102)  
ResourceServer -> AuthzServer : Introspection Request\n(incl.Resource Server Access Token and Client Access Token)
ResourceServer <-- AuthzServer : Introspection Response
end

autonumber stop

@enduml

General flow:

  1. Optionally, the Resource Server obtains a metadata document from the Authorization Server, providing the introspect endpoint location.
  2. The Authorization Client as well as the Resource Server independently obtain their access tokens from the Authorization Server. The Resource Server requires this token to invoke the introspection endpoint.
  3. The Authorization Client will invoke a Resource Server endpoint, embedding its client access token in the request.
  4. The Resource Server obtains the authorization claims associated with the token from the Authorization Server by invoking the introspect endpoint. This step may be omitted if the Resource Server has a cached introspect response value for the access token (including responses where the active field was set to false).
  5. The Resource Server will evaluate the token claims, enforce any access control policies, and return the requested resources to the Authorization Client.

3.102.4.1 Token Introspection Request

This request is send by the Resource Server to the Authorization Server to evaluate the validity and contents of an access token.

3.102.4.1.1 Trigger Events

Resource Server wishes to evaluate the validity and contents of an access token.

3.102.4.1.2 Message Semantics

The Resource Server shall perform an HTTP POST request to the introspect endpoint with the following parameters using the “application/x-www-form-urlencoded” format [RFC7662]:

The Resource Server must securely identify himself towards the Authorization Server by using credentials agreed between the Authorization Server and Resource Server. See ITI TF-2: 3.102.5 Security Considerations for details.

A Resource Server that supports the Authorization Server Metadata Option (see ITI TF-1: 34.2.1) shall use the introspection endpoint published through the Authorization Server Metadata Document for validating the token and obtaining the related claims.

A non-normative example of an introspection request is (using a Bearer HTTP Authorization header) is:

POST /introspect HTTP/1.1
Host: server.example.com
Authorization: Bearer 23410913-abewfq.123483
Accept: application/json
Content-Type: application/x-www-form-urlencoded

token=2YotnFZFEjr1zCsicMWpAA

The token being introspected may be opaque to the Resource Server. It may be formatted as JWT or SAML token, but custom formats are allowed.

3.102.4.1.3 Expected Actions

Upon receiving the introspect request, the Authorization Server shall evaluate the Resource Server’s access to the introspect endpoint. If access is not allowed, the Authorization Server shall return HTTP 401 (Not Authorized).

The Authorization Server shall:

The Authorization Server may return different responses for the same inspected token. For example, an Authorization Server may limit which scopes from a given token are returned for each Resource Server to prevent a Resource Server from learning more about the larger network than is necessary for its operation.

The Authorization Server may include an expiry field (exp) in the introspect result. This expiry field value shall be shorter or equal to the expiry time of the access token introspected.

3.102.4.2 Token Introspection Response

The Authorization Server returns the active state and authorization claims related to the token.

3.102.4.2.1 Trigger Events

The Authorization Server has formulated an access policy decision for the introspected access token.

3.102.4.2.2 Message Semantics

The introspect response is a JSON-formatted object. There are two variants of this object.

  1. The Authorization Server considers the token to be invalid for the given Resource Server because of formatting issues, revocation data, expiry, or other access policy considerations. The introspect result object shall contain a single field “active” with boolean value “false”.
  2. The Authorization Server considers the token to be valid for the given Resource Server. The object shall contain a field “active” with boolean value “true”. In addition, it shall contain the same fields and values as formulated for the JWT token content as specified in Section 3.71.4.2.2.1 JSON Web Token, including defined extensions.
3.102.4.2.3 Expected Actions

The Resource Server shall inspect the “active” field of the introspect result. If the active field is set to “false”, the Resource Server shall return HTTP 401 (Not Authorized) for all requests carrying the introspected access token.

The Resource Server shall use the introspection results as access token claims in all access control evaluations as depicted in Section 3.72.7.

The Resource Server may cache introspection results for a given access token in case the introspection result contains an expiry field. This cache shall not extend the period as defined by the expiry field. If no expiry field is provided, the Resource Server shall not cache the introspection results.

3.102.5 Security Considerations

The Resource Server shall securely identify itself towards the Authorization Server by using credentials agreed between the Authorization Server and Resource Server.

At minimum, the Authorization Server and Resource Server shall support the use of Bearer tokens for Resource Server authentication as defined in [OAuth2.1, Section 7.2]. To obtain a bearer token, the Resource Server may request such a token from the Authorization Server, reusing the client credential grant flow as described in the Get Access Token [ITI-71] transaction (see ITI TF-2: 3.71.4.1.2.1 Client Credential Grant Type).

An Authorization Server that supports the Authorization Server Metadata Option (see ITI TF-1: 34.2.1) should provide the available token introspection authentication options as part of its metadata document.

Note: The use of bearer tokens to authorize the introspect request will not lead to circular references to introspect. The Authorization Server is expected to natively understand the bearer tokens it created and therefore does not need to call introspect on itself.

Resource Servers and Authorization Servers that support this transaction shall fulfill the security requirements defined in [RFC7662], especially:

3.102.5.1 Security Audit Considerations

Resource Servers shall use the introspection results as authorization claims when formulating audit messages, as specified in Section 3.72.5.1.

| Editor: Please add Section 3.103 | |————————————-|

3.103 Get Authorization Server Metadata [ITI-103]

3.103.1 Scope

This transaction is used by Authorization Clients and Resource Servers to obtain metadata about an Authorization Server such as endpoint locations and references to key stores required to validate (token) signatures.

3.103.2 Actor Roles

Table 3.103.2-1: Actor Roles

Actor Role
Authorization Client Metadata Requester
Resource Server Metadata Requester
Authorization Server Metadata Provider

3.103.3 Referenced Standards

This transaction relies on standards defined in the following documents and the references therein:

3.103.4 Messages

The Get Authorization Server Metadata transaction consists of a single request and response initiated by an Authorization Client or Resource Server as depicted in the diagram below:

ITI-103 Get Authorization Server Metadata Diagram

Figure 3.103.4-1: ITI-103 Get Authorization Server Metadata Diagram

@startuml get-authorization-server-metadata

participant "Authorization Client\nor\nResource Server" as Client
participant "Authorization Server" as AuthzServer

autonumber 0 1 "<b>[00]</b>"
autoactivate on

Client -> AuthzServer: Authorization Server Metadata Request
Client <-- AuthzServer: Authorization Server Metadata Response

@enduml

3.103.4.1 Authorization Server Metadata Request

Used to request the metadata document of an Authorization Server.

3.103.4.1.1 Trigger Events

An Authorization Client or Resource Server wants to learn about Authorization Server endpoint locations, key material required for signature validation, or other relevant authorization data.

3.103.4.1.2 Message Semantics

The client issues a HTTP GET request to the well-known metadata endpoint associated with Authorization Server.

There are various ways of formulating this endpoint as described in [RFC8414, section 3.1], and [OpenID Connect Discovery, section 4]. Authorization Servers are recommended to follow one of these procedures, but may choose a different well-known endpoint location mechanism.

The manner in which the Authorization Clients or Resource Server are configured with the Authorization Server metadata endpoint locations is beyond the scope of this transaction.

A non-normative example of such a request using [RFC8414] is:

GET /.well-known/oauth-authorization-server/tenant1 HTTP/1.1
Host: example.com
3.103.4.1.3 Expected Actions

Upon receiving a metadata request, the Authorization Server should respond with the metadata document as described in Section 3.103.4.2.

Implementations supporting multi-tenancy shall respond with different metadata documents for different tenants, providing at least a different issuer value.

Requests for metadata for non-existing tenants shall result in a HTTP 404 (not found) response.

3.103.4.2 Authorization Server Metadata Response

The response is a set of claims about the Authorization Server’s configuration, including all necessary endpoints and public key information.

3.103.4.2.1 Trigger Events

The Authorization Server Metadata Response message is returned as response to a valid Authorization Server Metadata Request.

3.103.4.2.2 Message Semantics

The response is a set of claims about the Authorization Server’s configuration, including all necessary endpoints and public key location information.

The response shall be structured as a plain JSON document.

The document shall be structured according to the rules set forth in [RFC8414, Section 2], with these additional constraints:

In addition to the claims provided in [RFC8414], Authorization Servers should provide the following claim:

3.103.4.2.3 Expected Actions

The Authorization Client or Resource Servers requesting the metadata document shall use the endpoint locations from the metadata document in its interactions with the Authorization Server.

The Authorization Client or Resource Servers requesting the metadata document should use the JWK values retrieved from the jwks_uri endpoint published in the metadata document for validating JWT and/or SAML tokens.

Resource Servers requesting the metadata document should use the “access_token_format” claim to determine the method of token validation and usage (e.g., interpret and validate access token as JWT structure).

3.103.5 Security Considerations

All security considerations as described in [RFC8414, Section 6.2] shall be implemented.

Note: The issuer claim value of the metadata document is not necessarily the same as the issuer claim value associated with access-tokens. The issuer value in the metadata document refers to the source of the metadata document itself. This document may point to an token endpoint at a server other than the metadata document server. The issuer claim associated with the access token should refer to the server that implements the token endpoint.

As the metadata document is intended to support the authorization processes, there is no need to provide client credentials towards the metadata endpoint. To prevent unnecessary disclosure of credentials, the Authorization Server Metadata Request shall not include and credentials from the Authorization Client or Resource Server.

33 MHD Profile

| Editor: Please add the following to MHD Volume 1: Section 33.5 MHD Security Considerations | |————————————————————————————————|

33.5.1 Use with the Internet User Authorization (IUA) Profile

The IUA Profile provides support for user authentication, app authentication, and authorization decisions. When MHD actors are grouped with IUA actors there are additional security and privacy functionality enabled by this grouping. There are additional requirements and functionality enabled through scope definitions that are transaction specific. See the Security Considerations sections of the MHD-defined transactions for guidance on scope definition when grouped with IUA actors.

| Editor: Please add the following to MHD Volume 1: Section 33.6 MHD Cross Profile Considerations | |—————————————————————————————————–|

33.6.4 Use with the Internet User Authorization (IUA) Profile

The IUA Profile provides support for user authentication, app authentication, and authorization decisions. When MHD actors are grouped with IUA actors there are additional security and privacy functionality enabled by this grouping. There are additional requirements and functionality enabled through scope definitions that are transaction-specific. See the Security Considerations sections of the MHD-defined transactions for guidance on scope definition when grouped with IUA actors.

| Editor: Please add the following to MHD Volume 2: Section 3.65.5 Security Considerations | |———————————————————————————————-|

3.65.5.2 Use with the Internet User Authorization (IUA) Profile

The IUA Profile provides support for user authentication, app authentication, and authorization decisions. When MHD actors are grouped with IUA actors there are additional security and privacy functionality enabled by this grouping. There are additional requirements and functionality enabled through scope definitions that are transaction-specific.

An MHD Document Source, when grouped with an IUA Authorization Client, shall use [ITI-71] Get Access Token to request the following scope from the IUA Authorization Server to enable the MHD [ITI-65] transaction with the authorizing token [ITI-72].

The MHD Document Recipient, when grouped with an IUA Resource Server, shall require [ITI-72] Incorporate Access Token in all [ITI-65] Provide Document Bundle transactions, shall enforce the authorization decision in the token, and may further enforce policies beyond those made by the Authorization Server such as consent or business rules.

scope: “ITI-65”

This scope request authorizes the full ITI-65 transaction. This scope implicitly requests patient-specific Create/Update for DocumentManifest, DocumentReference, List, and Binary. Further scope refinement is allowed in realm or project-specific situations; these scopes would be in addition to the scope defined here.

| Editor: Please add the following to MHD Volume 2: Section 3.66.5 Security Considerations | |———————————————————————————————-|

3.66.5.2 Use with the Internet User Authorization (IUA) Profile

The IUA Profile provides support for user authentication, app authentication, and authorization decisions. When MHD actors are grouped with IUA actors there are additional security and privacy functionality enabled by this grouping. There are additional requirements and functionality enabled through scope definitions that are transaction specific.

An MHD Document Consumer, when grouped with an IUA Authorization Client, shall use [ITI-71] Get Access Token to request the following scope from the IUA Authorization Server to enable the MHD [ITI-66] transaction authorizing token [ITI-72].

The MHD Document Responder, when grouped with an IUA Resource Server, shall require [ITI-72] Incorporate Access Token in all [ITI-66] Find Document Manifests requests, shall enforce the authorization decision in the token, and may further enforce policies beyond those made by the Authorization Server such as consent or business rules.

scope: “ITI-66”

This scope request authorizes the full [ITI-66] transaction. This scope implicitly requests patient-specific Search/Read for DocumentManifest resources as defined in [ITI-66]. Further scope refinement is allowed in realm or project-specific situations; these additional scopes would be in addition to the scope defined here.

| Editor: Please add the following to MHD Volume 2: Section 3.67.5 Security Considerations | |———————————————————————————————-|

3.67.5.2 Use with the Internet User Authorization (IUA) Profile

The IUA Profile provides support for user authentication, app authentication, and authorization decisions. When MHD actors are grouped with IUA actors there are additional security and privacy functionality enabled by this grouping. There are additional requirements and functionality enabled through scope definitions that are transaction specific.

An MHD Document Consumer when grouped with an IUA Authorization Client, shall use [ITI-71] Get Access Token to request the following scope from the IUA Authorization Server to enable the MHD [ITI-67] transaction authorizing token [ITI-72].

An MHD Document Responder, when grouped with an IUA Resource Server, shall require [ITI-72] Incorporate Access Token in all [ITI-67] Find Document References requests, shall enforce the authorization decision in the token, and may further enforce policies beyond those made by the Authorization Server such as consent or business rules.

scope: “ITI-67”

This scope request authorizes the full [ITI-67] transaction. This scope implicitly requests patient-specific Search/Read for DocumentReference resources as defined in [ITI-67]. Further scope refinement is allowed in realm or project specific situations; these additional scopes would be in addition to the scope defined here.

| Editor: Please add the following to MHD Volume 2: Section 3.68.5 Security Considerations | |———————————————————————————————-|

3.68.5.2 Use with the Internet User Authorization (IUA) Profile

The IUA Profile provides support for user authentication, app authentication, and authorization decisions. When MHD actors are grouped with IUA actors there are additional security and privacy functionality enabled by this grouping. There are additional requirements and functionality enabled through scope definitions that are transaction specific.

An MHD Document Consumer, when grouped with an IUA Authorization Client, shall use [ITI-71] Get Access Token to request the following scope from the IUA Authorization Server to enable the MHD [ITI-68] transaction authorizing token [ITI-72].

The MHD Document Responder, when grouped with an IUA Resource Server, shall require [ITI-72] Incorporate Access Token in all [ITI-68] Retrieve Document requests, shall enforce the authorization decision in the token, and may further enforce policies beyond those made by the Authorization Server such as consent or business rules.

scope: “ITI-68”

This scope request authorizes the full [ITI-68] transaction. This scope implicitly requests patient-specific Read for Binary resources as defined in [ITI-68]. Further scope refinement is allowed in realm or project specific situations; these additional scopes would be in addition to the scope defined here.

9 ATNA Profile

| Editor: Please add the following row to ATNA Volume 1: Section 9.2 ATNA Actor Options Table for both the Secure Node and Secure Application Actors | |————————————————————————————————–|

“STX: HTTPS IUA” ITI TF-1:9.2.6.7

| Editor: Please add Section 9.2.6.7 as follows | |—————————————————|

9.2.6.7 STX: HTTPS IUA

The system will utilize server-side authenticated TLS (also known as https) to authenticate the server to the client and provide communications integrity and encryption. The system will utilize the Internet User Authorization (IUA) Profile to authenticate the client application to the server (IUA Resource Server). See ITI TF-2: 3.19.6.6.

| Editor: Please add the following section to Volume 2 as follows | |———————————————————————|

3.19.6.6 STX: HTTPS IUA

This configuration utilizes server-side authenticated TLS (also known as https) to authenticate the server to the client and provide communications integrity and encryption; and the IUA Profile to authenticate the client application to the server (IUA Resource Server).

The ATNA Local Secure Node or Secure Application shall be grouped with an IUA Authorization Client. The ATNA Remote Secure Node or Secure Application shall be grouped with an IUA Resource Server.