Client

Pure SMART servers are using the OAuth2 standard for authorization and hence Apps running against a SMART provider must be registered with the server. Many servers support OAuth2 Dynamic Client Registration, and so does this client. If you connect to such a server you don't have to specify a client_id – the framework will automatically register itself if needed. See below for details.

If you are simply testing grounds you can use our sandbox server and the shared my_mobile_app client-id. Some FHIR test servers may not use authorization and you won't have to specify security settings when initializing the client. The examples here assume that you're talking to a SMART on FHIR server.

Usage

To start off working with the Swift-SMART library you want to instantiate a Client and hold on to it:

import SMART

let smart = Client(
    baseURL: "https://fhir-api-dstu2.smarthealthit.org",
    settings: [
        "client_id": "my_mobile_app",
        "redirect": "smartapp://callback",    // must be registered
    ]
)

There are many other options that you can pass to settings, some are mentioned below but make sure to take a look at init(baseURL:settings:).

Note: The SMART framework embeds the Swift-FHIR data models framework. These are compiled into the framework, you will only need to import SMART in your source files.

Authorization

On FHIR servers requiring authorized access you must first have the user authorize your app. The client's authProperties variable allows you to specify a few options for how you want to authorize. The default settings use an embedded web view to have the user log in, and then displays a native patient selector.

smart.authProperties.embedded = true
smart.authProperties.granularity = .PatientSelectNative
smart.authorize() { patient, error in
    if let error = error {
        // there was an error
    }
    else {
        // `patient` is a "Patient" resource on success, unless you've used
        // the `TokenOnly` granularity
    }
}

The client currently supports four authentication granularity settings:

• TokenOnly: Standard OAuth2 authorization. After login you get a token and the login screen disappears.
• LaunchContext: If the app was launched via context – rather unusual for an iOS app – this option also dismisses the login screen after login, but makes sure you have the launch scope set for obtaining launch context.
• PatientSelectWeb: Adds the launch/patient scope, meaning the web server will prompt you to select a patient after login, then returns a patient-id with the token. The framework will then retrieve the Patient resource and return it in the authorize() callback.
• PatientSelectNative: The default setting, will present a native patient selector right after login for the user to select a patient. This Patient resource will then by returned in the authorize() callback. Relies on the FHIR server's capability to order patients and badge-fetches patients for display.

See the SMART documentation for launch context and scope information.

Authorized Requests

You can also use the following to make sure the client is ready to execute requests. This step is performed automatically when you use authorize(callback:) so you only need it against open servers.

smart.ready() { error in
    // do your work
}

Dynamic Client Registration

If no client_id is provided during initialization, but the server's Conformance statement defines a registration URL, the client automatically attempts to register your app using Dynamic Client Registration. If you use dyn-reg, specify at least your app's name with client_name. You can also provide logo_uri so that when users being prompted to authorize your app get to see your app's icon.

Implementation Details

The ready(callback:) method, which is also executed by the authorize(callback:) method, will fetch the FHIR server's conformance statement, if it hasn't been cached. The conformance statement is currently used to extract:

• OAuth2 endpoints (via our SMART extensions) to determine authorize and token URLs as well as the dynamic client registration URL
• Operation definitions