Consumer Authentication - adamacrown/SoarianAPICalls GitHub Wiki
Tell me more about the consumer authentication process
This demonstration will take you through the steps for a consumer accessing the Soarian API to:
- Kick-off the Authorization Grant process [1]
- Authenticate the consumer via the Identity Provider (IdP)
- Authorize an application and receive an Authorization Bearer Token from the Cerner Authorization Server
- Test each Soarian FHIR API via Postman
Prerequisites:
- Download Postman locally to your machine via the link below [0]
- Ascertain your FHIR endpoint GUID from your Cerner contact - we'll refer to this GUID as parameter {{tenantId}}
- {{tenantId}} is an alphanumeric string that will look something like this: 0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca
- Determine the client ID you'll be testing with, which can be gathered from your Cerner contact; we'll refer to this parameter as {{clientId}}
- {{clientId}} is a registered and known identifier with the Cerner Authorization Server, which will allow the application complete authentication and authorization process
- The alphanumeric string that will look something like this: 689d8ca4-ddc3-4f1a-a1fd-b0bc956daed2
- Construct your Sandbox FHIR API Base URL, including your {{tenantId}} from the previous step, starting from this template to form the {{baseUrl}}: https://fhir-myrecord.sandboxcerner.com/dstu2/{{tenantId}}
- The {{baseUrl}} will look like: https://fhir-myrecord.sandboxcerner.com/dstu2/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca
- Gather your patient portal consumer user credentials (username, password)
1. Discover Authorization URLs
- Navigate in your browser to: https://authz-demo.sandboxcerner.com/client/demo
- Add your FHIR {{baseUrl}} - our example being https://fhir-myrecord.sandboxcerner.com/dstu2/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca - to the first box. This will help the AuthZ Demo application programmatically discover two endpoints key for patient access, including the endpoints for:
- Authorizing a user via https://authorization.sandboxcerner.com/tenants/{{tenantId}}/protocols/oauth2/profiles/smart-v1/personas/patient/authorize
- Generating a Token via https://authorization.sandboxcerner.com/tenants/{{tenantId}}/protocols/oauth2/profiles/smart-v1/token
- Click Discover Authorization URLs button.
- A few fields will autopopulate in the AuthZ Demo App, including Auth Server URI and the Token URI
The next section will step you through the fields to fill out to authorize the application to access the consumer's data.
Get Authorization Code
- Fill out the applicable fields that you plan to test - here's a well-built example:
Here are the fields we used to build out this example - sub in what you need as needed for your test case.
- Auth Server URI: https://authorization.sandboxcerner.com/tenants/{{tenantId}}/protocols/oauth2/profiles/smart-v1/personas/patient/authorize
- Client ID: for us, sandbox, or in your example, {{clientId}}
- Response Type: code
- Presentation: Tab
- Scope(s): patient/Patient.read patient/Condition.read patient/AllergyIntolerance.read patient/MedicationStatement.read patient/Immunization.read patient/DiagnosticReport.read patient/Observation.read patient/Procedure.read patient/Device.read patient/CarePlan.read patient/DocumentReference.read
- Aud (Audience): https://fhir-myrecord.sandboxcerner.com/dstu2/{{tenantId}}
- State: random, can be any string you create (e.g. abc123)
- Click the Get Authorization Code button, launching authorization grant workflow; you'll find your user agent (your internet browser) is redirecting you now to authenticate as a consumer in the identity provider configured for that endpoint.
- Add your credentials - your username and password, and complete the login process.
- You'll be redirected to the Right of Access Authorization Page, for which you'll authorize the application to access data on behalf of the consumer.
- Choose your consumer - in our case, Wilma Smart - then authorize the the application by clicking the Allow Access button.
- Your user agent, the browser, will be redirected back to the AuthZ Demo application, which will include the Authorization Grant code, {{code}}, generated by the Cerner Authorization Server. This will be used in the next section to redeem for the Authorization Bearer Token, the token used to call each FHIR API.
Let's advance to exchanging that {{code}} for a token.
Get Access Token
We'll now exchange the authorization code from the previous section, for a token - here's what our example starts as:
- Fill out the applicable fields as needed. In our example, we used the following:
- Token URI: https://authorization.sandboxcerner.com/tenants/{{tenantId}}/protocols/oauth2/profiles/smart-v1/token
- Client ID: sandbox, or in your example {{clientId}}
- Grant Type: authorization_code
- Code: 9e24c0a8-6876-4fbd-aab6-7c961442d8ae, or in your example, the {{code}} generated from the previous step
- State: 2774c98a-6260-42d4-b915-019a2eb6d590, or in your example, the {{state}} you entered in the Get Authorization Code section
- We then hit the Get Access Token button, providing us with an Access Token, or {{token}}
This token will be used in Postman to call each respective consumer API, to retrieve data the consumer can access.
- Most importantly, identify the person ID, or {{personId}}, you'll need to use when testing in Postman, as this will be the primary key used across each API call.
In this example, {{personId}} is 4342008 - this will be different based on the EMR system you're testing with. If you're testing with Soarian, you might expect to see the following format:
- OID|#|PersonID, or 1.3.6.1.4.1.37998.99.1.1.3.2.1|0|123456
Postman
Download this Postman Collection: https://www.getpostman.com/collections/ddc85cea6e0c3521cee6