Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve capabilities #143

Merged
merged 3 commits into from
Jul 27, 2017
Merged

Improve capabilities #143

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d4166f9
Respond to request for change
Jul 27, 2017
de0313c
Strip baseurl
Jul 27, 2017
219b866
Strip non-index link
Jul 27, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 135 additions & 0 deletions capability-statement/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
---
layout: main
title: "SMART on FHIR Authorization: Capability statement"
---

# Publishing OAuth2 URLs

If a server requires SMART on FHIR authorization for access, its metadata must
support automated dicovery of OAuth2 endpoints by including a "complex"
extension (that is, an extension with multiple components inside) on the
`CapabilityStatement.rest.security` element. Any time a client sees this extension, it
must be prepared to authorize using SMART's OAuth2-basead protocol.

[The top-level extension uses the URL
`http://fhir-registry.smarthealthit.org/StructureDefinition/oauth-uris`, with
the following internal components:

<table class="table">
<thead>
<th>Component</th>
<th>Required?</th>
<th>Description</th>
</thead>
<tbody>
<tr>
<td><code>authorize</code></td>
<td><span class="label label-success">required</span></td>
<td><code>valueUri</code> indicating the OAuth2 "authorize" endpoint for this FHIR server.
</td>
</tr>
<tr>
<td><code>token</code></td>
<td><span class="label label-success">required</span></td>
<td><code>valueUri</code> indicating the OAuth2 "token" endpoint for this FHIR server.</td>
</tr>
<tr>
<td><code>register</code></td>
<td><span class="label label-default">optional</span></td>
<td><code>valueUri</code> indicating the OAuth2 dynamic registration endpoint for this FHIR server, if supported.
</td>
</tr>
<tr>
<td><code>manage</code></td>
<td><span class="label label-default">optional</span></td>
<td><code>valueUri</code> indicating the user-facing authorization management workflow entry point for this FHIR server. Overview in <a href="https://drive.google.com/file/d/0BylO-n0_de7gOWxiYkhra2dQRXM/view">this presentation</a>.</td>
</tr>
</tbody>
</table>

# Publishing Additional Conformance Details

A SMART on FHIR server should further describe its conformance with optional
capabilities in the SMART on FHIR specificaiton by declaring a list of the
capabilties that it supports. Details are [provided here](../conformance/).

### Example CapabilityStatement (as JSON)


```
{
"resourceType": "CapabilitiyStatement",
...
"rest": [{
...
"security": {
"service": [
{
"coding": [
{
"system": "http://hl7.org/fhir/restful-security-service",
"code": "SMART-on-FHIR"
}
],
"text": "OAuth2 using SMART-on-FHIR profile (see http://docs.smarthealthit.org)"
}
],
"extension": [{
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/oauth-uris",
"extension": [{
"url": "token",
"valueUri": "https://my-server.org/token"
},{
"url": "authorize",
"valueUri": "https://my-server.org/authorize"
},{
"url": "manage",
"valueUri": "https://my-server.org/authorizations/manage"
}]
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "launch-ehr"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "launch-standalone"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "client-public"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "client-confidential-symmetric"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "sso-openid-connect"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "context-banner"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "context-style"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "context-ehr-patient"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "context-ehr-encounter"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "context-standalone-patient"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "context-standalone-encounter"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "permission-offline"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "permission-patient"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "permission-user"
}]
],
...
```

86 changes: 0 additions & 86 deletions conformance-statement/index.md
View file
Open in desktop

This file was deleted.

56 changes: 19 additions & 37 deletions conformance/core-set.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,38 +1,20 @@
# Core Capabilities

"extension": [{
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "launch-ehr"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "launch-standalone"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "client-public"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "client-confidential-symmetric"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "sso-openid-connect"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "context-patient"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "context-encounter"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "context-banner"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "context-style"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "permission-offline"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "permission-patient"
}, {
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode": "permission-user"
}]
To be conformant with SMART on FHIR's Core Capabilities, an EHR must support
the following capabilities, and must advertise them in its [capability
statement](../capability-statement):

* `launch-ehr`
* `launch-standalone`
* `client-public`
* `client-confidential-symmetric`
* `sso-openid-connect`
* `context-banner`
* `context-style`
* `context-ehr-patient`
* `context-ehr-encounter`
* `context-standalone-patient`
* `context-standalone-encounter`
* `permission-offline`
* `permission-patient`
* `permission-user`
39 changes: 32 additions & 7 deletions conformance/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ A SMART on FHIR server can convey its capabilities to app developers by listing
a set of the capabilities described below. This can be published out of band,
or it can be conveyed as part of a server's FHIR `CapabilityStatement` using
an extension on `CapabilityStatement.rest.security`. For example, a server
can publish its support for Core SMART on FHIR Support by including: [Core Capabilities](./core-set.md)
can publish its support for Core SMART on FHIR Support by including: [Core Capabilities](./)

## Specific Capabilities (by category)

Expand All @@ -36,14 +36,39 @@ can publish its support for Core SMART on FHIR Support by including: [Core Capab

### Launch Context

`context-patient`: support for patient-level launch context (requested by `launch/patient` scope, conveyed via `patient` token parameter)
`context-encounter`: support for encounter-level launch context (requested by `launch/encounter` scope, conveyed via `encounter` token parameter)
`context-banner`: support for "need patient banner" launch context (conveyed via `need_patient_banner` token parameter)
`context-style`: support for "SMART style URL" launch context (conveyed via `smart_style_url` token parameter)
The following capabilities convey that a SMART on FHIR server is capable of provding basic context
to an app at launch time. These capabilities apply during an EHR Launch or a Standalone Launch:

`context-passthrough-banner`: support for "need patient banner" launch context (conveyed via `need_patient_banner` token parameter)
`context-passthrough-style`: support for "SMART style URL" launch context (conveyed via `smart_style_url` token parameter)

#### Launch Context for EHR Launch

When a SMART on FHIR server supports the launch of an app from _within_ an
existing user session ("EHR Launch"), the server has an opportunity to pass
existing, already-established context (such as the current patient ID) through
to the launching app. Using the following capabilities, a server declares its
ability to pass context through to an app at launch time:

`context-ehr-patient`: support for patient-level launch context (requested by `launch/patient` scope, conveyed via `patient` token parameter)
`context-ehr-encounter`: support for encounter-level launch context (requested by `launch/encounter` scope, conveyed via `encounter` token parameter)

#### Launch Context for Standalone Launch

When a SMART on FHIR server supports the launch of an app from _outside_ an
existing user session ("Standalone Launch"), the server may be able to
proactively resolve new context to help establish the details required for an
app launch. For example, an external app may request that the SMART on FHIR
server should work with the end-user to establish a patient context before
completing the launch.

`context-standalone-patient`: support for patient-level launch context (requested by `launch/patient` scope, conveyed via `patient` token parameter)
`context-standalone-encounter`: support for encounter-level launch context (requested by `launch/encounter` scope, conveyed via `encounter` token parameter)


### Permissions

`permission-offline`: support for refresh tokens (requested by `offline_access` scope)
`permission-patient`: support for patient-level scopes (e.g. `patient/Observation.read`)
`permission-offline`: support for refresh tokens (requested by `offline_access` scope)
`permission-patient`: support for patient-level scopes (e.g. `patient/Observation.read`)
`permission-user`: support for user-level scopes (e.g. `user/Appointment.read`)

8 changes: 4 additions & 4 deletions index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -157,8 +157,8 @@ On receiving the launch notification, the app would query the issuer's
Accept: application/json

The metadata response contains (among other details) the EHR's
<a href="{{site.baseurl}}authorization/conformance-statement">
conformance statement</a> identifying the OAuth `authorize` and `token`
<a href="./capability-statement">
capability statement</a> identifying the OAuth `authorize` and `token`
endpoint URLs for use in requesting authorization to access FHIR
resources.

Expand All @@ -179,8 +179,8 @@ In order to obtain launch context and request authorization to access FHIR
resources, the app discovers the EHR authorization server's OAuth
`authorize` and `token` endpoint URLs by querying the FHIR endpoint
for the <a
href="{{site.baseurl}}authorization/conformance-statement">
EHR's conformance statement</a>.
href="./capability-statement">
EHR's capability statement</a>.

The app then can declare its launch context requirements
by adding specific scopes to the request it sends to the EHR's authorization
Expand Down