Sandbox - Registering a New App

Overview

In order to run your app against the SMART public sandbox, you will first need to register your app with our authorization service (i.e. create a new client). There are three ways to do this that we offer.

  • The easiest way to register your app is by using our Quick Registration Form below. The form simplifies the registration process by picking up reasonable defaults for your new client on your behalf that should meet most app’s needs. You can always tweak the client’s settings later using the authorization server’s interface.
  • The Authorization Server UI provides a more advanced interface for client registration and management. If you know what you are doing and would like to exercise more control over your client, this may be a better option for you than the Quick Registration Form.
  • If you would like to use an API to be able to register your apps and clients from your own code or application, you can use the OAuth 2.0 Dynamic Client Registration Protocol described in the last section of this document

Quick Registration Form

Client Quick Registration
launch
launch/patient
launch/encounter
patient/*.read
user/*.*
user/*.read
openid
profile

Authorization Server UI

This is a more advanced alternative to using the Quick Registration Form.

Step 1

Log into the OpenID Connect Server at https://authorize-dstu2.smarthealthit.org and click on Register a new client in Self-service client registration.

Step 2

In the Main tab enter a user-friendly name for your app in the Client name box. Also, enter the main URI of your app which the user client should visit after completing the app authorization process with the OpenID Connect Server. Finally, enter the URL of the app’s logo that will be displayed to the user during the authorization process.

Step 3

In the Access tab make sure that the app is granted the following scopes: launch, launch/patient, launch/encounter, patient/*.read, user/*.*, openid, profile. The code response type should be unchecked.

Step 4

On the Credentials tab change the authentication method:

Step 5

In the Other tab uncheck the Always require that the auth_time claim be sent in the id token and enter the URL to your launch.html page in the Initiate Login box.

Step 6

Click the Save button. The OpenID Connect Server will assign a Client ID and Registration Access Token to your self-service client. Make sure to copy them to a file on your local machine, because you will need them to update your client configuration.

Step 7

You can use the Client ID and Registration Access Token for your self-service client to update or delete its record in the OpenID Connect Server.

OAuth 2.0 Dynamic Client Registration Protocol

Based on: http://tools.ietf.org/html/draft-ietf-oauth-dyn-reg-17

To register your client dynamically in the OpenID Connect OAuth 2 server, you may use a REST call like this:

POST /register HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: authorize-dstu2.smarthealthit.org

{
   "client_name": "Cool SMART App",
   "redirect_uris": [
     "https://srv.me/app/cool"
   ],
   "token_endpoint_auth_method": "none",
   "grant_types": ["authorization_code"],
   "initiate_login_uri": "https://srv.me/app/launch.html",
   "logo_uri": "https://srv.me/img/cool.png",
   "scope": "launch launch/patient launch/encounter patient/*.read user/*.* openid profile"
}

If everything goes well, the server will respond with a JSON object that will contain the client id that you should use. The above example is for a public client. If you’d like to register a private client, you will need to change the token_endpoint_auth_method value to “client_secret_basic”.

We're hiring a senior developer to work full time on the open source SMART on FHIR project. Learn More!
The SMART on FHIR API is evolving in parallel with the FHIR ballot releases. If you spot problems, please file an issue. Or better yet, you can edit this page.