Obtaining a Json Web Token (JWT) requires performing an authentication step (outlined in 'Getting Started in our Sandbox). This is initiated from a specially constructed URL that requires specific information, most of which will be granted after registration and on boarding.
You will need:
The base URL looks something like:
https://bluekcprod.b2clogin.com/bluekcprod.onmicrosoft.com/oauth2/v2.0/authorize?p=B2C_1A_INTEROPAPPDEVELOPERAUTHORIZATIONFLOW&client_id=appId&nonce=defaultNonce&redirect_uri=https%3A%2F%2Fjwt.ms&scope=openid%20offline_access&response_type=code&prompt=login
Replace 'appId', within the URL, with the provided Client ID.
Note: You can replace the redirect_uri with something other than https://jwt.ms. Make sure to encode the :// characters with %3A%2F%2F. Helpful Encoding Tool: URL Encoder.
The scope=openid%20offline_access is mandatory. Additional scopes can be appended in the URL (scopes can be requested during the onboarding process). As noted above, we recommend using the URL provided in the onboarding email, as it should include the additional scopes.
To get started, use the test authorization flow URL that's was provided from Blue KC, in the onboarding process.
See "Production App Configuration Resources" at the bottom of the page for the production /token API call.
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.
{
"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": "e11bf45a-7534-db09-a68d-6410d1fef145",
"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.
(name|patientId) with | as the separator
From the JWT pull out the patientId and use that patientId in the following URLs to test that.
When setting up your tool (e.g. postman, restful, etc.) set up the headers to have "Authorization" with a value of "Bearer {jwt}". {jwt} is the base64 encode JWT that you generated in the previous step.
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIm...
Once you have the token set as a header for the GET call and the patientId you can try various calls
For full documenation please refer to our Swagger documentation
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).
Sandbox Endpoints
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, JWT, etc.