BlueButton+Plus+-+OAuth+Workflows

flat

This specification provides an overview of The ABBI PULL Protocol. In the following, authorizer.com Represents the host for the web site that authorizes access to the data. This server provides authorization services using OAuth 2.0, and supports end-points for authorization and access grants. dataholder.com Represents the URL of the web site that provides the ABBI services to your application. application.com Represents the web site describing the application, and in the case of web-based applications, the web-application itself. =Identifying Installed Instances of your Application= Before your application can interact with an authorization end point, it and the authorization end-point must agree on the identity that the application will use for itself. There are several ways that this identity can be established:
 * Identifying Installed Instances of your Application
 * Locating Endpoints
 * Obtaining the Authorization Token
 * Obtaining an Access Token
 * Making Authorized ABBI Requests
 * Retrieving the Current Summary Document
 * Searching for Documents
 * Manual Application Registration
 * Dynamic Registration
 * Client Identity Assertion

Manual Application Registration
Most applications that use OAuth 2.0 today support a manual registration step. This works when there is a single authorization endpoint associated with the API in use (e.g., when using the Twitter or Facebook API's). This is not well suited for cases where the application must work with multiple endpoints supporting the same API. However, this process may be appropriate for initial application development and testing. Data Holders using the ABBI PULL Protocol may support manual registration, however, details are beyond the scope of this specification.

Dynamic Registration
Applications should be able to dynamically register themselves with a registration endpoint using the [|OAuth 2.0 Dynamic Client Registration Protocol].

**Client Identity Assertion** The client identity can be established by the application by providing a Client Identity Assertion to the authorization endpoint, where the assertion itself is signed by a certificate provided by the software manufacturer or by the deployer of the software. This identity assertion can be used to distinguish each installed instance of the application from other installed instances. The identity of the installed application can be for an installation on a specific device, or could be for all instances of the application installed by a single user (e.g., licensee of the application). Specific details for how this assertion is provided to the installed instance of the application are out of scope of this specification, but the format of the assertion is within scope. The format is described in more detail below: The client identity assertion is a JSON Web Token [[|JWT]] signed according to the JSON Web Signature [[|JWS]] specification in accord with the requirements of the JWT Bearer Token Profile for OAuth 2.0 [[|JWT-Bearer]].

Web Signature Header
The JWT is signed by the software manufacturer or deployer. It contains a JSON Web Signature Header with the following token keys and constraints: Either the x5u or the x5c key must be present in the assertion.
 * Assertion Key || Constraints || Comments ||
 * alg || Required. Fixed to "RS256" || Identifies the algorithm used to sign the Header and Body. ABBI uses RSA with SHA-256. ||
 * typ || Required. Fixed to "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" || Indicates that this is a JWT Bearer token. ||
 * x5u || Conditional. An absolute URL to an X.509 certificate chain in PEM encoded format starting with https:// || The certificate used to sign the JWT (and its trust chain). ||
 * x5c || Conditional. An array of base64 encoded strings, each representing the DER encoding of an X.509 certificate. || The certificate used to sign the JWT (and its trust chain). ||

An example header appears below: { "alg": "RS256", "typ": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", "x5u": "https://application.com/certificate.pem" }

Assertion Body
The assertion body asserts the identity of the installed instance of the client application.
 * Assertion Key || Constraints || Comments ||
 * iss || Required. A URL identifying the issuer. || Identifies the issuer of the identity assertion. This must be the subject identified in the certificate used to sign the assertion body. [[file:///C:/Users/212042380/Documents/ABBI%20OAuth%20Workflows.docx#_msocom_3|[KWB3]]] ||
 * sub || Required. A unique identifier in a namespace that is under control of the issuer. [[file:///C:/Users/212042380/Documents/ABBI%20OAuth%20Workflows.docx#_msocom_4|[KWB4]]] || Identifies the subject of the assertion, and is the same value as is used for client_id in OAuth 2.0 authorization flows. ||
 * aud || Required. The fixed value "http://www.siframework.org/ABBI/aud" || Specifies that the audience for this identity assertion is OAuth authorizers that conform to the ABBI authorization profile. ||
 * exp |||| Required. The expiration date of this assertion. In most cases, identity assertions are readily reissued, and so should not expire more than three years in the future. However, embedded applications may not easily have their identity refreshed, as it may be set at time of manufacturer, and should be permitted to be longer. ||
 * nbf || Optional. No constraints. || Indicates that the identity assertion cannot be used before this date. ||
 * iat || Optional. No constraints. || Indicates the time at which this assertion was issued. ||
 * jti || Optional. No constraints. || Provides a unique identifier for this assertion. ||
 * Additional assertions for ABBI (all starting with “http://www.siframework.org/ABBI/”) Note that the definitions of these parameters appear in [|Section 2 Client Metadata] of the OAuth 2.0 Dynamic Registration Protocol ||
 * client_name || Required. Name of the application. || Identifies the application. ||
 * client_uri || Required. An absolute url to a page describing the application, starting with https: || URL for application describing its purpose and use, terms of service, and data use policies. ||
 * logo_uri || Optional. An absolute url starting with https: to a resource containing a gif, png or jpg image. || URL for the application logo. ||
 * redirect_uris || Required. A space separated list of redirection urls. These must begin with https: //unless the hostname is localhost, in which case, it can begin with http:// || The redirection urls permitted to be used by the application. ||

An example JWS Body appears below: { "iss": "https://application.com", "sub": "https://application.com/application?client_id=12345", "aud": "http://www.siframework.org/ABBI/aud", "exp": "1394064000", "nbf": "1362528000", "iat": "1362528000", "jti": "6789", "http://www.siframework.org/ABBI/client_name": "Application Name", "http://www.siframework.org/ABBI/client_url": "https://application.com/application", "http://www.siframework.org/ABBI/logo_url": "https://application.com/application/logo.png", "http://www.siframework.org/ABBI/redirect_uris": "https://application.com/redirect http://localhost:8080/redirect" }

Certificates
The certificates used to sign an application identity should be code-signing signing certificates. Code-signing certificates are appropriate for signing application configuration detail, and would be appropriate for the use described within this specification. Issuer Identifier The “iss” key identifies the issuer. It must be the same value that appears in the issuers X.509 certificate used to sign the JWS Assertion. The value must be the same as the value in the [|Subject] field, or in the [|Subject Alternative Name] field of the X.509 certificate as described in [[|RFC 5280]].

Subject Identifiers
The subject identifier must be an identifier in a namespace under the control of the issuer. This could be formatted as an e-mail address, a URL, or some other URI. It need not resolve to a web page or be a real e-mail address. One possible set of values that could be used are URLs constructed from the application URL, as follows: https://application.com/application?client_id=12345 While this mechanism may be used to guarantee control over the namespace, application providers are warned NOT to provide private details about a specific client identifier should that URL be accessed through a web page.

Conveying the Client Identity via OAuth
OAuth workflows requiring client authentication must be provided with the client identity assertion, as specified in the Assertion Framework for OAuth 2.0 [[|OAuth-Assertion]]. That assertion is transmitted in using the following parameters in the OAuth 2.0 requests:

client_id
This value is required, and must be the same as the value of the sub key in the client identity assertion.

client_assertion_type
This value is required, and must be set to the fixed value of urn:ietf:params:oauth:client-assertion-type:jwt-bearer, as specified in [[|JWT-Bearer]].

client_assertion
This value is required, and is the [[|JWS]] representation of the client assertion.

Authorization Policies
Client Identities are protected except for those which are shared by multiple instances of the same application. Shared identities can be readily used by rogue applications pretending to be the client asserted by the shared identity. If it accepts shared credentials, the authorization endpoint shall make the end-user aware of the insecure nature of this client identity prior to creating an authorization.

Application Access to Data Holders
Authorization servers must first approve an application and its client_id and the identity assertion associated it before the application instance will be access to data made available by a data holder. There are a number of mechanisms by which authorization servers can make these decisions. The following section discusses each of these techniques.

White Listing
Applications must be approved by the authorization server before an authorization will be successful. The advantage to this approach is that data holders can be certain that the application will be a good actor before it gains access. The major disadvantage is that this creates an obstacle for application developers, who must potentially be white-listed on thousands of sites. A centralized white-list could be used, but again this still provides an obstacle, just not a big one. It also means that someone must host the centralized white-list.

Black Listing
Applications will be approved so long as they are not on a list of unapproved applications. This is a common approach for access control to internet web sites. There are a number of readily available services that identify “bad actors” in the ecosystem. The advantage to this approach is that it reduces hurdles for application developers, but will allow bad actors into the ecosystem until they are detected.

Trust Policies
Applications could be approved by the authorization end-point so long as they provide some evidence of being trusted. One mechanism already proposed in this specification is that the url describing the application must be to a web page that is accessed using the https: protocol. This enables authorizers to make access control decisions based upon the SSL certificate presented when the URL is retrieved and based on the content of the page. Note that there may likely be cases where the application URL may not be hosted by the application developer.

Deploying the Application Identity to an Application Instance
This specification does not prescribe the method by which application identities are deployed to an application instance. However, it does offer some suggestions about how the identity could be deployed:

At Download Time
When the application is downloaded, the website where the application is download from could generate a new application identity to be used by the end-user, and that could be downloaded as part of the download package.

During Application Registration
It is not uncommon for applications to take users through an application registration process. During that process, the application could be provided with the installed application identity.

During Application Installation/Configuration
While the application is being installed/configured, it could query the user for a certificate to use for signing/creating the application identity, or offer instructions on how to use existing tools to create and install an identity for the client application. This might be used for situations where an application is being supplied via open source or other cases where the deployer (installer) of the application needs to take responsibility for the application identity. For example, company/open source provider XYZ builds a generic application that uses the ABBI API to gather and analyze data, which is then used by company ABC. Company ABC adds features and user interface capabilities, and deploys the final application to their end-users. Company ABC needs to take responsibility for supplying the client identity. =Locating Endpoints= There are a number of steps to accessing data with ABBI. The second step is to discover the web end-points that your application will need to use to make the various requests to different servers. End-point discovery is a multi-step process. Data holders can support multiple authorization servers, and each authorization server is responsible for managing its end-points for providing authorization services. However, the process is similar in both cases. End-point discovery makes use of RFC-5787 to provide a well-known URL to access server metadata about end-point locations. The location of server end-points for an ABBI data holder can be found in a document located at []. The location of server end-points for an authorizer can be found in a document located at []. These documents are accessed through simple HTTP GET requests. A response to these requests may return a redirect to another location. Clients must follow redirects in this case.

The host-meta document
The host-meta document is served in either XRD format (application/xrd+xml), or JRD format (application/json). If the application does not specify the format in the Accept header, it is returned in XRD format. These formats are specified by the [|OASIS Extensible Resource Descriptor Format], and Appendix A of [|Web Host Metadata].

Subject
The host-meta document must contain a subject. The subject is a URI which identifies the resource being described by the document. For a data holder, the subject of the document is the ABBI services. For the authorization server the subject is the authorization services. The subject of the document is the host servicing requests. In XRD, the subject is communicated in the  element:  https://dataholder.com

…

In JRD, the subject is communicated as a name value pair, { "subject": "https://dataholder.com" …

Link
The host-meta document must contain a link describing each service end-point that is accessible from the host. Each link has a relationship and URI reference, and may also have one or more human readable titles in various languages. If no language is specified for the title, then this title is the default. In XRD format this appears as shown in the example below.  Client Authorization Endpoint   Client Authorization Endpoint 

In JRD format, the same example would appear as shown below. "links": [ { "rel": "http://ietf.org/rfc6749/endpoint/authorization", "href": "https://authorizer.com/authorization", "titles": { "default": "Client Authorization Endpoint", } } { "rel": "http://ietf.org/rfc6749/endpoint/authorization", "href": "https://authorizer1.com/authorization", "titles": { "en-us": "Client Authorization Endpoint", } } ]

The values for rel (an attribute in XRD format, or property in JRD format) identify the type of endpoint being exposed. We propose use of values describing endpoints that would be consistent with the OAuth 2.0 specification. The URL identifying the relationship may change as this work becomes standardized.
 * **Endpoint Name** || **Relationship (rel)** || **Description** ||
 * OAuth Authorization || http://ietf.org/rfc6749/endpoint/authorization [[file:///C:/Users/212042380/Documents/ABBI%20OAuth%20Workflows.docx#_msocom_7|[KWB7]]] || Authorization grant endpoint ||
 * OAuth Access Grant || http://ietf.org/rfc6749/endpoint/token [[file:///C:/Users/212042380/Documents/ABBI%20OAuth%20Workflows.docx#_msocom_8|[KWB8]]] || Access token/refresh token endpoint ||
 * ABBI Summary Endpoint || http://siframework.org/ABBI/endpoint/summary || Access most recent summary. ||
 * ABBI Search Endpoint || http://siframework.org/ABBI/endpoint/search || Search for documents ||
 * ABBI Authorizer || http://siframework.org/ABBI/host/authorizer || Identifies a host that may be used to authorize access to the ABBI services. ||

Requirements for host-meta content
Each host must respond to a request for the host-meta content, and must be able to return it in either the XRD or JRD format based upon the request. This document must be accessible via a GET request over HTTPS from the /.well-known/host-meta URL.

Authorizers
An authorizer must include at least one URL supporting Client Authorization and Access Grants in its host-meta response. All URLs must use the HTTPS protocol. The example below shows a minimally conforming XRD and JRD document for the fictional host authorizer.com.  https://authorizer.com  <Link rel="http://ietf.org/rfc6749/endpoint/token" href="https://authorizer.com/token"/> </XRD>

{ "subject": "https://authorizer.com", "links": [ { "rel": "http://ietf.org/rfc6749/endpoint/authorization", "href": "https://authorizer.com/authorization" }, { "rel": "http://ietf.org/rfc6749/endpoint/token", "href": "https://authorizer.com/token" } ] }

Data Holders
A data holder must include at least one ABBI Authorizer link identifying a host that may be used to access authorization services. It should list all authorizers it accepts an authorization from to allow patients to choose the authorizer that supports their identity of choice. A data holder must also include a URL for an ABBI summary endpoint. It should include a URL for an ABBI Search Endpoint. If the data holder also acts as an authorizer, then it must conform to the rules for authorizers expressed above. The examples below illustrate a minimal XRD and JRD document for an ABBI data holder that supports all ABBI endpoints and supports two different external authorizers. <XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0" > https://dataholder.com</Subject> <Link rel="http://siframework.org/ABBI/endpoint/summary" href="https://dataholder.com/summary"/> <Link rel="http://siframework.org/ABBI/endpoint/search" href="https://dataholder.com/xdsentry/search"/> <Link rel="http://siframework.org/ABBI/host/authorizer" href="https://authorizer.com "/> <Link rel="http://siframework.org/ABBI/host/authorizer" href="https://authorizer1.com "/> </XRD>

{ "subject": "https://authorizer.com", "links": [ { "rel": "http://siframework.org/ABBI/endpoint/summary", "href": "https://dataholder.com/summary" }, { "rel": "http://siframework.org/ABBI/endpoint/search", "href": "https://dataholder.com/xdsentry/search" }, { "rel": "http://siframework.org/ABBI/host/authorizer", "href": "https://authorizer.com" }, { "rel": "http://siframework.org/ABBI/host/authorizer", "href": "https://authorizer1.com" } ] }

In order to obtain the authorization endpoints for this scenario, the client application must choose one of the authorizers (or allow the user to choose the authorizer), and retrieve the XRD or JRD document from the selected authorizer. The example below illustrates an XRD and JRD document for an ABBI data holder that is also an authorizer. <XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0" > https://dataholder.com</Subject> <Link rel="http://ietf.org/rfc6749/endpoint/authorization" href="https://dataholder.com/authorization"/> <Link rel="http://ietf.org/rfc6749/endpoint/token" href="https://dataholder.com/token"/> <Link rel="http://siframework.org/ABBI/endpoint/summary" href="https://dataholder.com/summary"/> <Link rel="http://siframework.org/ABBI/endpoint/search" href="https://dataholder.com/xdsentry/search"/> <Link rel="http://siframework.org/ABBI/host/authorizer" href="https://dataholder.com "/> </XRD>

{ "subject": "https://authorizer.com", "links": [ { "rel": "http://siframework.org/ABBI/endpoint/summary", "href": "https://dataholder.com/summary" }, { "rel": "http://siframework.org/ABBI/endpoint/search", "href": "https://dataholder.com/xdsentry/search" }, { "rel": "http://siframework.org/ABBI/host/authorizer", "href": "https://dataholder.com" }, { "rel": "http://ietf.org/rfc6749/endpoint/authorization", "href": "https://dataholder.com/authorization" }, { "rel": "http://ietf.org/rfc6749/endpoint/token", "href": "https://dataholder.com/token" } ] }

Note: A data holder can be an authorizer AND rely on other external authorizers if it chooses to do so. Having discovered the necessary end-points that your application needs to interact with, you are now ready to assign your application instance an identity, or request access to the ABBI end-points. =Obtaining an Authorization Token= After your application has been provided with an identifier, the next step it must perform to access the user’s data is to have your application to obtain an authorization token. This is a short-lived token (e.g., ten minutes) that is created by the data holder, and returned to your application to enable it to get a longer-lived (e.g., days or weeks) access token. While OAuth 2.0 defines an implicit grant flow that can reduce the number of server round trips required to obtain access, the authorization grant flow is more secure. Given that ABBI is exchanging healthcare information, the additional security is worth an additional server round-trip.

Authorization Token Request
To obtain an authorization token, the application must make a GET request to the authorization endpoint as shown below. GET /authorize?client_id=//APPLICATION_ID//&scope=SCOPE&response_type=code&state=//STATE//&

redirect_uri=//REDIRECT_URI// HTTP/1.1 Accept: text/html Host: authorizer.com

The server at authorizer.com will ensure that the end-user is logged in. This may be done by checking for a cookie (indicating that the user is already logged in), by making the user log in via a form, or via another mechanism (possibly including issuing redirects). Once authorizer.com has ensured that the user is logged in, it will display a page asking the user to consent to the specified application accessing their data. If the user consents to access, execution follows the normal flow. The application must then display the web page returned, following redirects as requested.

client_id
This parameter identifies the third-party application making the request on behalf of the user. This must be the same value provided in the sub key of the client identity assertion.

client_assertion_type
This value is required, and must be set to the fixed value of urn:ietf:params:oauth:client-assertion-type:jwt-bearer, as specified in [JWT-Bearer].

client_assertion
This value is required, and is the JWS representation of the client identity assertion.

scope
This parameter identifies the kind of information that is being requested by the application. For ABBI, we define one required scope that must be supported by applications. Set the scope parameter to *. This tells the receiver that you are interested in being able to access all ABBI endpoints it exposes. The receiver will return a scope parameter indicating which ABBI endpoints have been authorized by the request.

response_type=code
This parameter is required and indicates to authorizer.com that you are requesting an authorization token.

state
The state parameter will be returned with the value that your application passed in. If any other value is returned this is an error that might signal a cross-site forgery attempt.

redirect_uri
The redirect_uri parameter is used by authorizer.com to tell your application whether the request has succeeded or failed. If your application is a web site running in a web browser, it tells the web browser how to communicate the success or failure to your web site, and must be an https:// URL that will be serviced by your web site. If your application is running locally on the machine, then this URL must be http://localhost, and may include a port number indicating which port should be used to communicate the success or failure information. The redirect_uri must match one of the urls provided under the http://www.siframework.org/ABBI/red key in the client identity assertion. To ensure that local applications are not limited in where they can listen for responses, clients are permitted to select from a list of multiple redirect URLs. Locally running applications need not actually listen on any port. They can simply parse the HTTP response given to them to determine the success or failure state. However, by ensuring that multiple ports can be used, applications are able to use a web browser control to initiate the dialog, and be notified of the response when an HTTP request was made to that port by the browser control.

Invalid redirect_uri
If the REDIRECT_URI is different from the one that was used when the application was registered, authorizer.com will send a 400 (Bad Request) error. This indicates that the client issued a request, but the redirect_uri parameter does not match one of the uris that the client registered with.

Other Errors
To distinguish error responses from normal responses, we specify use of the 303 (See Other) response when the authorization failed. However, applications may wish to check for an error parameter in what should be a successful response just in case the authorizer doesn’t follow this specification completely. The Location header of the redirect response will indicate the error and state and may include other parameters (See OAuth 2.0). //REDIRECT_URI//?error=//ERROR_CODE//&state=//STATE//

error
The error parameter indicates what type of error occurred. The following values are defined by this specification. Other values may also be returned.
 * access_denied || The user does not consent to access ||
 * unauthorized_client || authorizer.com does not authorize the client ||
 * invalid_scope || The scope is not valid or not recognized (note that if scope = *, this error should not occur). ||

state
The state parameter should have the same value as the passed in state parameter. In all cases, if the STATE value passed in the original request does not match the STATE value returned by the server, it may indicate some attempt to hijack user information, e.g., through cross-site request forgery. Additional URL parameters may be present in error responses. We refer you to the OAuth documentation on error_description and error_uri. Other parameters may also be present. Unrecognized parameters in an error response should be ignored.

Success Response
If the authorization request was successful, authorizer.com will send a 302 (Found) response. Note that we indicate that errors must use the 303 (See Other) response instead of 302 (Found) to simplify processing. However, your application should also verify that the returned URL does not contain an error parameter. A success response will include query parameters on the redirect_uri that was used in the authorization request.

access_token
This parameter will contain a string that represents the authorization token.

token_type=Bearer
The token_type parameter identifies the type of token. The OAuth for ABBI specification requires that this be a Bearer token to simplify web access.

scope
This parameter indicates the scope of the authorization provided. It is a space separated string identifying the ABBI (or other) end-points which have been made available. If scope was specified as * in the initial request, this parameter will contain other values. Each token in the string represents one or more ABBI end-point addresses which may be accessed by your application using the provided access_token.

state
The state parameter must be the same as the state parameter your application specified when it made the request. If this parameter is different, it may indicate that your application is being subject to a cross-site forgery attempt.

expires_in
This parameter may be returned by authorizer.com. It indicates the number of seconds for which this token is valid. Note, authorization tokens should be short-lived (e.g., on the order of 10 minutes), as they will be quickly exchanged for access tokens by the application. Once exchanged for an access token, an authorization token cannot be used again. =Obtaining an Access Token= The next step is to turn the authorization token into an access token. Authorization tokens are passed from authorizer.com to your application through several layers (e.g., the browser client), and are thus somewhat exposed. Once your application has the authorization token, it must make a separate (and more secure) request to turn that into an access token. POST /access HTTP/1.1 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 Content-Type: application/x-www-form-urlencoded Host: authorizer.com grant_type=authorization_code&client_id=//APPLICATION_ID//&client_secret=//CLIENT_SECRET//& code=//CODE//&redirect_uri=//REDIRECT_URI//

Authorization Header
If the client has a client secret and can use basic authentication (true in most cases), then it must supply an authorization header. The value of the authorization header is computed by URL encoding the UTF-8 characters<span style="font-family: Calibri,sans-serif; font-size: 11pt;"> of the client_id and client_secret, concatenating them with a :, and then base64 encoding the resulting string.

grant_type
The grant_type parameter is required and must contain the value authorization_code.

client_id
This parameter identifies the third-party application making the request on behalf of the user. This must be the same value provided in the sub key of the client identity assertion.

client_assertion_type
This value is required, and must be set to the fixed value of urn:ietf:params:oauth:client-assertion-type:jwt-bearer, as specified in [JWT-Bearer].

client_assertion
This value is required, and is the JWS representation of the client identity assertion.

code
This parameter is required, and is the authorization token provided from the previous step.

redirect_uri
This parameter is required, and must be the same value as used in the previous step.

Success Response
A success response with return a 200 (OK) Status code, and return an entity in application/json format containing the access token and additional parameters as shown in the example below: HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "access_token":"2YotnFZFEjr1zCsicMWpAA", "token_type":"bearer", "expires_in":3600, "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", "scope":"read", "example_parameter":"example_value" }

access_token
This property must always be present. It indicates the access token value.

token_type
This property must always be present. The token_type will contain the value bearer, indicating that the token is a bearer token as described in RFC-6570.

expires_in
This property must always be present. It indicates the number of seconds before the token expires. Access tokens should be refreshed before they expire.

refresh_token
This property must always be present. It indicates the token that must be used to obtain new access tokens. Tokens are refreshed as described in OAuth 2.0.

scope
This property must always be present. It indicates the scope of the access token that was issued. =Making Authorized ABBI Requests= Once an access token has been granted, it may be used multiple times until it expires to make API requests. All ABBI requests containing an access token must be communicated using TLS to secure the token.

Authorization Header
The access token SHOULD be sent in all requests using the Authorization header and the Bearer authorization scheme as described in RFC-6750. Data holders must support the use of the Authorization header to communicate the access token. Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

In the POST Body
The access_token parameter may be sent in the POST body. If the body is application/x-www-form-urlencoded, then it must be stored in the first part of the entity body, in the access_token parameter. If the body is sent using application/json, then it must be included as a property with the name access_token in the entity body.

Use in URL Query Parameters is Forbidden
Even though allowed (although strongly recommended against) in RFC-6750, the access token shall not be sent in a URL query parameters according to the ABBI protocol. According to RFC-6750: //Browsers, web servers, and other software may not adequately secure URLs in the browser history, web server logs, and other data structures. If bearer tokens are passed in page URLs, attackers might be able to steal them from the history data, logs, or other unsecured locations.// Given that ABBI provides access to patient health information, and may be used on public computers (e.g., libraries, health centers), the danger of using bearer tokens in a URL makes it likely that tokens could be retrieved from these systems.

=The Current Document Endpoint= The current document endpoint returns the most recently available summary document. Servers must support two forms for making this request. The first form uses an HTTP GET request, and provides the access token in the authorization header, as shown below:

<span style="font-family: 'Courier New',Courier,monospace;">GET /summary?_format=xml <span style="font-family: 'Courier New',Courier,monospace;">Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

The second form uses an HTTP POST request, and provides the access token in the POST body, as shown in the following example:

<span style="font-family: 'Courier New',Courier,monospace;">POST /summary

<span style="font-family: 'Courier New',Courier,monospace;">access_token=Bearer%202YotnFZFEjr1zCsicMWpAA&_format=xml

Both forms of the request may include an HTTP Accept header parameter which indicates the preferred content format for returning the summary document. An optional _format query/post parameter may be present, and if present overrides the content of the HTTP Accept header parameter. Possible values for Accept and _format appear in the table below. Data holders must support these values: text/xml, xml, text/html, html, text/plain, text and plain and may support other formats.

|| Description || || Documents supporting the text/xml mime type. These include XML formats such as [|HL7]'s [|CDA] (including [|CCD] or [|CCDA]) or [|ASTM]'s [|CCR]. || || An alias for text/xml. || || Documents will be rendered in the text/html mime type. This includes any HTML suitable for rendering, including [|HTML 4], [|XHTML] or [|HTML 5]. || || An alias for text/html. || || A document rendered as a simple text file, such as might be produced using the original Blue Button interface. || || An alias for text/plain. || || Another alias for text/plain. || || A document rendered using the [|Portable Document Format], including [|PDF/A]. || || An alias for application/pdf. || || A document rendered in the format specified in [|RFC 4627]. || || An alias for application/json. || || Other formats and aliases may be supported by the server. ||
 * Values:

If neither the Accept header, nor the _format query/post parameter are provided, the server shall provide the text/xml form of the medical summary.

If no summaries are available for the patient, the server should respond with a 404 Not Found response. //How is this different from the case where the path doesn't exist on the server?//

=The Search Endpoint= The search endpoint is used to obtain a list of medical documents available for the patient from the data holder in an atom feed. Details of the structure of this feed are described in the HL7 [|xdsentry resource] described in the draft FHIR standard. Like the Current Document Endpoint, there are two forms of this request. The first form uses an HTTP GET request, and provides the access token in the authorization header, as shown below:

<span style="font-family: 'Courier New',Courier,monospace;">GET /xdsentry/search?//searchParameters// <span style="font-family: 'Courier New',Courier,monospace;">Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

The second form uses an HTTP POST request, and provides the access token in the POST body along with other search parmeters, as shown in the following example:

<span style="font-family: 'Courier New',Courier,monospace;">POST /xdsentry/search

<span style="font-family: 'Courier New',Courier,monospace;">access_token=Bearer%202YotnFZFEjr1zCsicMWpAA&//searchParameters//

Search Parameters
Search parameters that can be used with this endpoint are described below. [|string] |||| The _format parameter is provided to enable applications without control over HTTP Headers to specify the format of the resource. It indicates the format used to represent the XdsEntry resource. Overrides the Accept header if present in GET and search operations, and the Content-Type header in PUT or POST operations. || || **Description** || || The resource will be returned in application/json format as defined [|by HL7 here]. || || A synonym for application/json. || || The resource appears as an XdsEntry element using the text/fhir+xml format as defined [|by HL7 here]. || || A synonym for text/fhir+xml. || || A synonym for text/fhir+xml. || [|code-simple] (repeating) |||| Various mime types and/or information models can be used to represent different kinds of content, including summary notes, discharge notes, operative notes, et cetera. This parameter filters the responses to ensure that only specified notes are included. The following values are supported: || [|code-simple] (repeating) |||| The text/xml mime type can represent information using a variety of different schemas representing different information models. The purpose of this parameter is to allow users to request information conforming to a specific information models. || [|code-simple] (repeating) |||| Various mime types and/or information models can be used to represent different kinds of content, including summary notes, discharge notes, operative notes, et cetera. This parameter filters the responses to ensure that only specified notes are included.
 * _format
 * ^  || **Values:**
 * mimeType
 * ^  || **Values:** || **Description** ||
 * ^  ||  || Documents supporting the text/xml mime type. These include XML formats such as [|HL7]'s [|CDA] (including [|CCD] or [|CCDA]) or [|ASTM]'s [|CCR]. ||
 * ^  ||  || An alias for text/xml. ||
 * ^  ||  || Documents rendered in the text/html mime type. This includes any HTML suitable for rendering, including [|HTML 4], [|XHTML] or [|HTML 5]. ||
 * ^  ||  || An alias for text/html. ||
 * ^  ||  || A document rendered as a simple text file, such as might be produced using the original Blue Button interface. ||
 * ^  ||  || An alias for text/plain. ||
 * ^  ||  || Another alias for text/plain. ||
 * ^  ||  || A document rendered using the [|Portable Document Format], including [|PDF/A]. ||
 * ^  ||  || An alias for application/pdf. ||
 * ^  ||  || A document rendered in the format specified in [|RFC 4627]. ||
 * ^  ||  || An alias for application/json. ||
 * format
 * ^  || **Values:** || **Description** ||
 * ^  ||  || Content formatted using the ASTM [|CCR] Standard ||
 * ^  ||  || Content formatted using the HL7 CDA Standard that conforms to the [|Continuity of Care Document Release 1.0] ||
 * ^  ||  || Content formatted using the HL7 CDA Standard that conforms to the [|Consolidated CDA Specification (including CCD 1.1)] ||
 * class

class=HandP&class=Consult || [|dateTime-simple] |||| Filters entries starting on or after the specified time.
 * Example:**
 * ^  || **Values:** || **Description** ||
 * ^  ||  || Summary records using CCD (1.0 or 1.1) and/or CCR ||
 * ^  ||  || History and Physical Notes ||
 * ^  ||  || Consultation Notes ||
 * ^  ||  || Discharge Summaries ||
 * ^  ||  || Operative Notes ||
 * ^  ||  || Procedure Notes ||
 * ^  ||  || Progress Notes ||
 * ^  ||  || Imaging Reports ||
 * ^  ||  || Laboratory Studies ||
 * service.start-after

Time Zone
If time is specified, the time zone may be specified. If time is not specified, time zone is not permitted. When time zone is not specified, behavior with respect to time zone is not specified. The server may assume local time, local time of the querying system, or some other fixed time zone.

To specify services starting after 6:00am on January 1, 2012 in the Eastern Time Zone: /xdsentry/search?service.start-after=2012-01-01T06:00-05:00
 * Examples:**

To specify services starting after 6:00am on January 1, 2012 with no time zone /xdsentry/search?service.start-after=2012-01-01T06:00 || [|dateTime-simple] |||| Filters entries starting before the specified time. See [|notes on time zone] above.
 * service.start-before

To specify all services starting on January 1, 2012 /xdsentry/search?service.start-after=2012-01-01&service.start-before=2012-01-02
 * Examples:**

To specify all services starting before January 1, 2012 /xdsentry/search?service.start-before=2012-01-01 || [|dateTime-simple] |||| Filters entries stopping on or after the specified time. See [|notes on time zone] above.
 * service.stop-after

To specify only services that occured on on the date of January 1, 2012 /xdsentry/search?service.start-before=2012-01-02&service.stop-after=2012-01-01
 * Examples:**

To specify only services that occured between the hours of noon and 1pm on the date of January 1, 2012 /xdsentry/search?service.start-before=2012-01-01T13:00:00&service.stop-after=2012-01-01T12:00:00 || [|dateTime-simple] |||| Filters entries stopping before the specified time . See [|notes on time zone] above. || [|dateTime-simple] |||| Filters entries created on or after the specified time . See [|notes on time zone] above. || [|dateTime-simple] |||| Filters entries created before the specified time . See [|notes on time zone] above. ||
 * service.stop-before
 * created-after
 * created-before

=Editor’s Comments= Images, especially describing the various steps, Discovery, Registration, Authentication and Making Authenticated Requests would be very helpful.

Authorization Header: There are several places in the protocol where I made allowances for applications which could not send an Authorization Header, but frankly, I think we should just rule that out. Almost all modern browsers support the XMLHttpRequest object, which supports setting the Authorization header from within scripts that use it. Smart phones, tablets and similar devices all have programming environments which support access to HTTP Headers. The only programming environment that I can imagine which does not support access to the HTTP Header field is XSLT, whose document function does allow access to HTTP resources, but does not provide any access to POST requests (it can only perform an HTTP GET), and doesn’t support access to HTTP Headers. As XSLT is not a programming environment that is used by itself, I don’t see this as being a huge problem.

See updates to the Identifying Installed Instances of your application. While the changes are minimal, the ramifications are not. The protocol allows for dynamic registration OR client identity assertion, and doens't require one or the other to be supported by data holders. I'm open to suggestions as to which is SHOULD and which is SHALL. Note the similarity between dynamic registration and identity assertion.

We still need to address the issue of binding the authorization to a patient identity, given that the authorization endpoint may need some way to associate the authenticated user with data for a specific patient. Scope may be the answer. For example, I will want to use the same identity to access information about both of my daughters’ records. When I configure my client application, it will have to offer me a choice of records to access from each data holder in this case. On my phone, I may want the application to have access to their records, as well as those of myself and my wife. But on my tablet, I might only want to configure it to access my records. We’ll have to work that part out. I think the ABBI protocol may need to include a method to select the patient for whom the authorized user is accessing information for. One mechanism that would work would be to require the application to register itself with the data-holder for each distinct patient it is accessing. The scope parameter associated with the registration could be used to somehow identify which patient is associated with the request, but the question then becomes: How does the user communicate that scope to the application. I’m still thinking this one through. We don’t want to make it hard for people to use the same identity for more than one patient, but we don’t want that to make it more difficult for everybody.

<span style="font-family: Calibri,sans-serif; font-size: 11pt;"> Note that if the authorization endpoint only issues client_id and client_secret values using US ASCII alphanumeric characters and the - and _ characters, there is no need for URL encoding.

This is probably the easiest method for all to implement. These are the same kinds of certificates that can be used for code-signing, or NwHIN Direct May appear as the subject, or as an alternative subject in the X.509 certificate Could be formatted similar to an e-mail address: user@domain, or structured as a URI. What about e-mail signing certificates (e.g., Direct)? Should those be allowed? I can think of cases where a patient hacker would want to create their own software, and should be able to do so readily without having to spend $$$ on a code signing certificate. The policies applicable to an e-mail certificate might be different. I’d be somewhat concerned about sharing my private key with untrusted software though… This would be appropriate to identify an end point conforming to OAuth 2.0, but we might want to be more specific, identifying end-points that conform to the ABBI profile for authorizers. Ditto