We highly recommend PKCE for any mobile app usage and PKCE can be integrated into any flow. Please ask us to turn on the feature for you on the Azure B2C side. To determine how to use PKCE in your app please consult your app devleoper documentation on how to implement PKCE in particular with Azure B2C.
PKCE is designed to deal with a specific attack wherein the the browser used to perform the authorization step must pass the generated token to the app on the mobile device. PKCE prevents other apps from reading that token from the browser to use the token for malicious purposes. While there may be no known malicious apps stealing tokens used for FHIR APIs there is strong financial incentive for malicious actors to steal such tokens.
Once a token (JWT) is issued, its security is the responsibility of your app. It is considered extremely sensitive and failure to adequately safeguard tokens may result in loss of access to Blue KC Patient Access APIs.
Refresh tokens last for 90 days, but a member/patient may revoke access at any time. Refresh tokens are only available with the appropriate OIDC flows and PKCE is strongly encouraged for such flows.
The token returns all of the standard JWT elements from Azure B2C plus some custom claims. Your code will need to understand one of these custom claims. You may safely ignore the others.
{
"typ": "JWT",
"alg": "RS256",
"kid": "3keoem5aEBDxiMVwlj0zTkZ3L5hDT5wNxLwrQ8-6Juw"
}.{
"exp": 1609449886,
"nbf": 1609446286,
"ver": "1.0",
"iss": "https://bluekcprod.b2clogin.com/f7072c0c-e001-426f-89b8-51ea1c0731fe/v2.0/",
"sub": "e11de45a-7594-4b09-a68d-6410dbfff145",
"aud": "5574853e-a0ef-45ad-9301-d94f6102e857",
"acr": "b2c_1a_interopappdeveloperauthorizationflow",
"nonce": "defaultNonce",
"iat": 1609446286,
"auth_time": 1609446286,
"signInName": "InteropAppDev1",
"appId": "5574853e-a0ef-45ad-9301-d94f6102e857",
"consentedMemberNamesAndBeKeys": [
"KERRY REBER|90003160541",
"BETHANY SERNA|90001627557"
],
"consentedMemberUniqueKeysAndBeKeys": [
"167172350|90003160541",
"86268102|90001627557"
]
}
Notice the element "consentedMemberNamesAndBeKeys"
"consentedMemberNamesAndBeKeys": [
"KERRY REBER|90003160541",
"BETHANY SERNA|90001627557"
]
Because a patient may be capable of authorizing your app to see multiple people's information we needed a way store in the JWT who the patient has authorized for your app.
When queries against the API need the patientId parameter you can find the allowable patient IDs in the JWT.
Each element of the "consentedMemberNamesAndBeKeys" array is a tuple (name|patientId) with | as the separator
For example: Kerry's patient ID is 90003160541.
Within your app this allows you to manage only one JWT, but pull data for multiple people.
If the member/patient has authentication issues, please direct the member to https://members.bluekc.com and work out their authentication issues with Blue KC member services. The member will also need to set up 2 factor authentication using either the Microsoft or Google Authenticator app. SMS 2 factor is not available.
A return status of 401 is recoverable and requires re-authentication (or renewing the access token with the refresh token)
A return status of 403 is non-recoverable and indicates a bad search parameter, a resources belonging to a member not on the JWT or a confidential communication placed on a member.
You will need to understand how to configuration your application to participate in an OIDC (OpenID Connect, OAuth 2.0) authorization flow. From an OAuth perspective the flow is called and authorization flow because the person authorizes an app to make API calls using the identity of the person. The result of the flow is an identity token that that contains an access token. The access token must be presented at the API in order to get any data returned. During the flow a standard authentication step will occur.
Additionally, just as with manually obtaining a JWT, your app must be configured with the AppID, return URLs and scope. Depending on the libraries and tools you use, different things may be asked for. Below is a complete list of URLs that your app may need to know. In particular, it should absolutely want to know the authorize endpoint.
Microsoft documentation: OAuth 2.0 authorization code flow in Azure Active Directory B2C
The sandbox authorization endpoints always return a particular set of patients irrespective of the credentials passed as long as authentication succeeds. The production endpoints will return one or more patients that the user has authorized. This may be self or other (e.g. personal representative or parent for a minor child).
Production Endpoints
Testing production configuration is difficult because you need a valid set of credentials from a production member to validate the workflow and return URL, PKCE configuration, etc. We can assist in validating your configuration. Sandbox is designed to be as functionally close as possible to production. So simply changing out the appid, base URL