This guide is intended to walk you through how to setup your very own reference SMART on FHIR implementation using Okta as the identity platform. This guide focuses on the AWS platform. There will be additional guides for other cloud providers to come. For an overview of this project and all of the components, please see here: Project Introduction
Note: This documentation has recently been overhauled to document an automated deploy process. If you were thrown off by this change- please see the original documentation here
- An Okta tenant (Get one here free)
Note: this guide relies on setting up a custom domain on the Okta tenant. If you're using an existing Okta tenant, be sure you're comfortable with adjusting the custom domain configuration.
- A domain name to use for your Okta/SMART authorization service (Example: smartauthz.yourdomain.tld).
Note: for the easiest setup, it is recommended that this domain be managed within Route53
- Node.js 12+
- Serverless framework (Get started here)
- Postman, or other API invocation tool (not strictly required- but will make configuration easier)
In this section, we'll ensure that we have our pre-requisites setup properly.
Note - I've found the easiest way to provide your AWS IAM credentials to the serverless framework using the "serverless config credentials" command referenced 1/2 way through the guide.
git clone https://github.com/oktadev/okta-smartfhir-demo.git
cd okta-smartfhir-demonpm installTo assist with the deployment of the overall solution, a guided deployment process has been created! The automated process performs the following high level tasks.
- Uses a questionnaire to collect pre-requisite information from you
- Which FHIR server you wish to protect
- What domain name you'd like to use for the authorization service
- What AWS region you'd like to deploy in
- Generates configuration files for automatically deploying Okta resources as well as AWS resources
- Automatically deploying Okta configuration
- Automatically deploying AWS configuration
- Assists with any manual steps that are necessary
Overall the process is managed in a step-by-step manner with the ability to start/stop the overall process at any point. After each step in the process, the user has the ability to continue, or pause and continue at a later time.
Files managed with the deploy script:
-
deploy/work/state - This is a file created by the deploy script that determines what step in the process you're in, is used to start/stop the process, and finally is used to carry configuration information between the steps.
-
deploy/work/okta_org_config.'deploymentname'.json - This will will be generated as a copy of deploy/okta/okta_org_config_example.json, with proper configuration obtained during the deployment process. This may be used for future updates to Okta.
-
/serverless.'deploymentname'.yml - This file will be generated as a copy of serverless.aws.example.yml, with proper configuration obtained during the deployment process. This may be used for future updates to AWS.
cd deploy
npm installnode deploy_aws.jsFollow the guided process to finish your deployment!
There are 3 main sections to a manual deployment:
- Initial Okta configuration
- Deploy AWS resources
- Finalize Okta configuration
Create a clone of this file for use for your manual deployment
npm install
cp serverless.aws.yml serverless.ymlNote - the layout of serverless.yml file specifies all configurable variables at the top of the file, within the "params" section. No other configuration outside of this section should be necessary.
Create a clone of this file for use in your manual deployment
cd deploy/okta
npm install
cp okta_org_config_example.json okta_org_config.jsonThe details within the okta_org_config file are documented within the file. The "SUFFIX" setting will cause that value to be appended to all objects within Okta (except for claim/attribute names that must be named a certain way).
Note: Omit the "SAMPLEUSER" fields if you do not wish to create a sample user in the Okta tenant.
node deploy_okta_objects.js okta_org_config.json initThe output of the initial deploy is verbose and explains which fields need to go where in serverless.yml. Note: You should have values for all parameters except for API_GATEWAY_DOMAIN_NAME_BACKEND. We'll fill this value in step 11
node add_custom_domain.jsThis script will output to the screen the proper DNS configuration that is necessary for validating the domain. It will also output the "domain id" to the screen that you'll need in the next step.
After you've setup the proper DNS records with your DNS vendor, run:
node verify_custom_domain.js <domain ID output in step 7>Within the AWS console, request a TLS certificate for your authz domain that you've decided upon, and configured as the domain within Okta.
*Note- you must request this certificate within your deployed region AND us-east-1, if different.
This step will configure a custom domain within the AWS API gateway that will be used in the final AWS deploy step.
serverless create_domain --verbose -c serverless.ymlVisit: https://YOURREGION.console.aws.amazon.com/apigateway/main/publish/domain-names?region=YOURREGION
Copy the "API Gateway domain name" field into your serverless file. It will look similar to: uniqueid.execute-api.awsregion.amazonaws.com
API_GATEWAY_DOMAIN_NAME_BACKEND: API Gateway domain name from AWS consoleIn this step we'll finalize the AWS deployment in AWS using the serverless framework.
serverless deploy --verbose -c serverless.ymlNote this step will likely take 10-15 minutes to execute to completion.
For the final AWS/DNS step, go into the cloudfront module within the AWS console. In the console, you should see a "distribution" for your new deployment. You need to copy the "DomainName" field - it will be similar to: uniqueid.cloudfront.net. You need to update your CNAME record that you created in step 6/7 such that your authorization server domain name points to cloudfront instead of Okta directly.
For the final overall step, we'll finalize the Okta deployment. In /deploy/okta:
node deploy_okta_objects.js okta_org_config.json finalizeOnce complete- the following endpoints will be available for you to provide your FHIR service:
- Issuer (if your FHIR server needs it): https://yourauthzdomain.your.tld/oauth2/{serverless.FHIR_AUTHZ_SERVER_ID}
- Authorize: https://yourauthzdomain.your.tld/oauth2/{serverless.FHIR_AUTHZ_SERVER_ID}/smart/v1/authorize
- Token: https://yourauthzdomain.your.tld/oauth2/{serverless.FHIR_AUTHZ_SERVER_ID}/v1/token
- Keys: https://yourauthzdomain.your.tld/oauth2/{serverless.FHIR_AUTHZ_SERVER_ID}/v1/keys
If you want to create a sample user with a sample FHIR ID, run:
node deploy_okta_objects.js okta_org_config.json sampleuserThere are no major considerations for creating SMART clients. The dynamic client registration protocol may be used, or for demonstration purposes, the Okta admin UI may be used to create a client as shown.
Important settings:
- Application Type: Web
- Allowed Grant Types: Authorization Code only
- Consent: Not required (it's handled by a custom screen - not Okta default consent screen)
- Redirect URI: 2 values shall be put here!
- The smart_proxy_callback URL that you were provided when you deployed the Okta-SMART endpoints.
- The actual redirect_url of the application (this is validated by the /authorize proxy)
