BCSC Encryption

Incompatibility with Cognito

The BCSC OIDC service does three things that the Cognito service cannot handle:

1. The ID token returned from the token endpoint is a JWE instead of a JWT. Cognito errors out on this format.
2. The encryption process for the JWE ID token requires the public side of an asymmetric key. Cognito does not expose this key.
3. The userinfo endpoint returns the JWE ID token. Cognito expects a JSON response from the userinfo endpoint.

In order to be able to use BCSC as an OIDC identity provider in Cognito, we had to fix all of these problems.

1. The FAM API exposes a proxy service for the BCSC token endpoint. Cognito talks to the proxy. All the proxy service does is remove the ID token from the BCSC response. Cognito makes no use of this token anyway, so this solves the problem.
2. The FAM API exposes a JWKS as an API endpoint. The JWKS is created from the public side of an asymmetric key managed by KMS specifically for FAM.
3. The FAM API exposes a proxy service for the BCSC token endpoint. Cognito talks to the proxy. The proxy service calls the BCSC userinfo endpoint and decrypts the returned JWE to get the userinfo JSON object and pass it back to Cognito.

With these services in place, the BCSC IDP in Cognito can be configured to talk to the proxy services instead of talking to BCSC directly for these interactions. See the diagram below for details.

Sequence Diagram

Sequence Diagram Explanation

1. An authorization request is sent from the browser to Cognito. Cognito redirects the browser to go to the BCSC sign-in page.
2. The user completes BCSC authentication (typically using the BCSC app on their mobile device).
3. The browser is redirected back to the Cognito service, passing the code. Cognito uses its BCSC client secret to exchange the code for tokens. Because this interaction is proxied, Cognito never gets the ID token from the response.
4. Cognito uses the bcsc auth token to make the userinfo request. Because this interaction is proxied, Cognito doesn't have to know how to consume the JWE provided by BCSC. BCSC uses the FAM JWKS endpoint to get a key to use to encrypt the JWE token. The proxy service uses the private key to decrypt the JWE token and return the result in the JSON format expected by Cognito.
5. Cognito maps the attributes from the userinfo object to build (or update) the user record in the Cognito user pool.
6. Cognito returns a response back to the browser with the code.
7. The browser is redirected back to the Cognito service, passing the code. Cognito builds the tokens (auth token, ID token, refresh token). Cognito responds with the tokens in a redirect request that sends the users browser back to the original web application. The web application can now use the tokens created by Cognito for business purposes.

Considerations for FAM DEV and FAM TEST

FAM includes BCSC DEV, BCSC TEST, and BCSC PROD as supported identity providers within the FAM PROD environment. These IDPs are meant to be used by project teams for their corresponding DEV, TEST, and PROD versions of their products.

FAM also has DEV, TEST and PROD versions, each of which support all the flavors of IDP (see Environment Management for details). Because the FAM DEV and FAM TEST environments need to support BCSC as well, these environments will use the proxy methods from FAM PROD in order to interact with BCSC. These lower environments are only accessible to the FSA Fingerprint team and are only used for internal and release testing.

It should be noted that BCSC PROD IDP can only be used in FAM PROD, as the BCSC PROD OIDC client intentionally does not recognize the redirect URI for FAM DEV or FAM TEST. This is good for security, but it does mean that the PROD integration can only be tested once it is in production.