Redirector Application Use
To use redirector for a directory endpoint OAuth flow the client will first do a search on directory for the endpoint that will be used to authenticate the user and gather their clinical and/or payer data. The search can be for a term or a specific endpoint id if known. For example a search for clinical endpoints matching the term “epic” (https://stage.directory.onerecord.com:443/directory/v1/client/fhir/endpoint/clinical/search/epic) provides the following response body (partial):
[
{
"name": "Epic New",
"vendor": "Epic",
"endpointStatus": "active",
"disposition": "1",
"dataType": "clinical",
"derivedAuthUri": "https://fhir.epic.com/interconnect-fhir-oauth/oauth2/authorize?client_id=e9896805-87ce-4da3-991c-093e4d1a53c5&redirect_uri=https%3A%2F%2Fredirector.onerecord.com%2Finbound%2F&response_type=code",
"redirectUri": "https://redirector.onerecord.com/outbound/?portalURL=https%3A%2F%2Ffhir.epic.com%2Finterconnect-fhir-oauth%2Foauth2%2Fauthorize%3Fclient_id%3De9896805-87ce-4da3-991c-093e4d1a53c5%26redirect_uri%3Dhttps%253A%252F%252Fredirector.onerecord.com%252Finbound%252F%26response_type%3Dcode",
"_id": "8e9cb0f7-f920-49c3-ad23-b54b8a9ebe9f",
"parent_org": "Sandbox"
},
...
]
The client would use the value in redirectUri to forward the application user to the endpoint's Authentication and Authorization portal so that the user/patient can give access to OneRecord's registered client to their health records.
The client would need to add an extra query parameter to redirectUri in order for the redirector app (middle man application provided for OAuth authentication to any given FHIR endpoint).
clientURL
The clientURL is the url that will receive the code and status values generated during patient authentication with the FHIR endpoint's portal. This URL runs on the client side and redirector will send the user to this URL once the portal user authentication and authorization process has been completed and the FHIR portal has generated a code to be used for building an access token for the FHIR APIs.
As an example lets say the client has built a web page at https://client-app.com/authcode that will receive the code generated by the FHIR OAuth server during patient authorization. This would be the clientURL added to the redirectUri which will result in the following URL:
Notice that we have added the client URL value in URL encoded form.
This is the URL that the browser needs to be sent to for authentication and authorization.
One requirement is that the user needs to stay on the current tab/window, spanning a new tab or window will cause issues with redirector holding session variables that are needed for this process.
Once the user has authorized access to the FHIR data the browser will land at:
https://client-app.com/authcode?code={{oauth-code}}&state={{oauth-state}}
Where {{oauth-code}} is the code generated by the FHIR endpoints OAuth server and {{state}} is an autogenerated state value that redirector uses as verification with the API.
The client application should then be able to use these values to call the OneRecord integrator API to request an access token from the FHIR OAuth server.
That call is to https://stage.integrator.onerecord.com:443/integrator/v1/fhir/auth/8e9cb0f7-f920-49c3-ad23-b54b8a9ebe9f/token with the following body:
{
"state": "{{oauth-state}}",
"authorizationCode": "{{oauth-code}}"
}
The response will contain the authenticated token to use in the request for FHIR resource to the OneRecord API.
Updated almost 2 years ago