Skip to main content

Launch the SDK

In order to enter the Impact Finance user experience, the Bank App must provide two things:

  • An ID Token as proof of identity and authentication of the End User, and
  • a locale code specifying which language to present to the End User.

Using the SDKs, this data is provided as arguments to the launch method. Without the SDKs, the same effect can be achieved by by opening a Webview or iframe with a POST request to /users/verify_token with token and locale in the request body. Optionally, a location can also be provided to deep link into a particular part of the experience. After successful token verification, the Impact Finance Web App will issue a session cookie and redirect the user to either a default or the provided location.

Authentication​

We rely on your existing authentication of your customers. Proof of identity and authentication is passed to the Impact Finance Web app via OpenID Connect ID Tokens.

The ID Token should be in the form of a signed (and optionally encrypted) JSON Web Token (JWT), containing the following minimal set of claims to limit data exposure:

  • iss: Issuer Identifier for your Authorization Server. It is communicated out-of-band (configured in DEPo) during integration.
  • sub: Subject Identifier, i.e. an id for the authenticated End User. If possible, we recommend using a Pairwise Pseudonymous Identifier (PPID).
  • aud: Audience that this ID Token is intended for. It is communicated out-of-band (configured in DEPo) during integration.
  • exp: Expiration time, after which the token will not be valid. Also, see token-renewed sessions on how this value affects session duration.
  • iat: Time at which the JWT was issued.

To improve the user experience of Shared Dreams ("Group Dreams"), the following additional claims should be provided:

  • given_name: Given name(s) or first name(s) of the End User.
  • family_name: Surname(s) or last name(s) of the End-User. To limit data exposure, it's enough to give away the first letter of the family name.

DES expects asymmetric token signatures, with a public key set exposed at a public JWKS endpoint. This endpoint is is configurable in DEPo.

Sequence Diagram​

sequenceDiagram participant bfe as Bank App participant sdk as Impact Finance SDK + Web App Frontend participant des as DES Backend participant bbe as Bank Backend bbe --> bfe: Provide a JWT token to Bank App bfe ->> sdk: SDK.launch(token, locale) sdk ->> des: validate token opt If unfamiliar `kid` value or JWKS cache expired / invalidated des ->> bbe: GET <jwks_endpoint> bbe -->> des: JWKS end des ->> des: Validation alt invalid des -->> sdk: Unauthorized sdk -->> bfe: completion failure bfe ->> bfe: close down Dreams Web App else valid des -->> sdk: Redirect with Set-Cookie sdk -->> bfe: completion success note over sdk: Impact Finance UX Started end

Example authentication using OpenID Connect​

Although the ID Tokens must adhere to OpenID Connect standard, it's entirely up to you how you choose to create them (through some OpenID Connect standard flow or through some other custom means). Assuming that your Bank App is a native mobile application though, we provide an example using the OpenID Connect Authorization Code Flow with Proof Key for Code Exchange (PKCE) below:

sequenceDiagram participant bfe as Bank App (native or SPA) participant sdk as Impact Finance SDK + Web App Frontend participant des as DES Backend participant as as Authorization Server bfe --> as: (1) Establish session bfe ->> bfe: (2) Generate Code Verifier and Code Challenge bfe ->> as: (3) Authorization Code Request (prompt=none) + Code Challenge as ->> as: Already signed in. prompt=none is ok. as ->> bfe: (4) Redirect to `redirect_uri` with Authorization Code bfe ->> as: (5) Get ID Token using AuthorizationCode + Code Verifier as ->> as: (6) Validate Code Verifier and Challenge as ->> bfe: (7) ID Token response bfe ->> sdk: (8) SDK.launch(IDToken, locale) sdk ->> des: (9) validate ID Token opt If unfamiliar `kid` value or JWKS cache expired / invalidated des ->> as: (10) GET <jwks_endpoint> as -->> des: JWKS end des ->> des: (11) Validation
  1. We assume that the End User is already logged in to your Bank App, and that this means that a session is established with the Authorization Server that will be used to generate ID Tokens for the Impact Finance Web App.
  2. Using PKCE, there is no need to store a client secret in the Bank App, nor use the unsafe implicit flow. Instead, a temporary Code Verifier and a Code Challenge is generated by the Bank App. Furthermore, it's assumed that a dedicated Client ID exists for the purpose of generating tokens for the Impact Finance Web App. (This is important to make sure that the ID Tokens cannot be used for anything else than authentication in DES.)
  3. The Bank App sends an Authorization Code Request to the Authorization Server with the additional code_challenge parameter. To ensure a seamless user experience where the End User is not even aware that the Impact Finance Web App is hosted outside of their Bank App, it is important to make sure that this request can be processed without asking the End User for neither authentication nor consent. Different Authorization Servers handle this differently. In some cases an organization-wide consent can be configured. In others it might be a good idea to specify prompt=none to tell the Authorization Server to skip the consent step. This, together with the assumption that the End User already has an authenticated session established (step 1), should ensure that the Authorization Code Request can be handled fully behind the scenes without involving the End User.
  4. Authorization Server responds with a code.
  5. The Bank App gets the ID Token from the Authorization Server by sending a Token Request with the additional code_verifier parameter.
  6. The Authorization Server verifies the code_verifier before...
  7. ...returning the ID Token.
  8. The Bank App can now launch the Impact Finance Web App, by handing the ID Token to the SDK.
  9. Behind the scenes, this means a POST request to to /users/verify_token with token and locale in the request body.
  10. The DES Backend fetches the public key corresponding to the asymmetric key pair used to sign the ID Token.
  11. The DES Backend validates the token, issues a session cookie and redirects into the Web App upon success.