Authorization wrapper of the data4life JavaScript SDK

The data4life JavaScript SDK uses the OAuth 2.0 Authorization Code Grant flow for web clients. Part of this flow is a client that has a client secret and communicates safely with the authorization server. To reduce your implementation time of the data4life SDK, we provide an OAuth client that handles the access token life cycle and stores additional information dependent upon the session of the user agent. The authorization wrapper for the data4life JavaScript SDK is developed to enable the communication with this OAuth Client__. Therefore, the setup details for the data4life JavaScript SDK differ slightly.

Read this SDK documentation together with the data4life web SDK README file. You can find more details there.

Before you start

To use the authorization wrapper with the data4life JavaScript SDK, you must have a client ID and a client secret. To obtain them to implement our SDK, please write to us at we@data4life.care.

Using the authorization wrapper

Instead of calling the setup method of the data4life JavaScript SDK, call the setup method of the authorization wrapper. The authorization wrapper automatically sets up the data4life JavaScript SDK with a private key and an access token. The wrapper also maintains their lifetime during the session with the user agent.

To use the the authorization wrapper, follow these steps:

  1. Get our Docker container that maintains the user agent’s access token and private key lifecycle during a session. If it is not yet open-sourced, please write to we@data4life.care.

  2. Configure the Docker container in your backend.

  3. Import the JavaScript file from the provided URL (see example below).

<script src="${url}/healthcloud_sdk.js"></script>

The script inserts a GC object into the global namespace. It contains the data4life JavaScript SDK and the authorization wrapper.

GC = { SDK, AUTH };

  1. Initialize the SDK by calling the authorization wrapper with your client ID and the URL to the OAuth client from step 1 and step 2.

Example:

// When your domain is your-domain.com and the is path /oauth redirects to the __OAuth Client__
const clientURL = 'your-domain.com/oauth';
const clientId = '123';

GC.AUTH.config({
    clientId: `${ clientId }`,
    clientURL: `${ clientURL }`,
});

The configuration returns a promise that contains the result of the data4life JavaScript SDK.

  1. Login

    a) If the user has a valid session with the OAuth client from step 1 and step 2, it receives its access token and private key. The user is logged in.

    b) If the user has no valid session with the OAuth client from step 1 and step 2. The user must be redirected with the login method of the authorization wrapper. Beware that it triggers a redirect of the user agent. If the login succeeds, the OAuth client redirects the user agent to the URL you configured. The user now has a valid session and is logged in as defined in step 5.a).

    GC.AUTH.login();

Verifying if users are logged in

To check if users are logged in, call, for example:

GC.AUTH.loggedIn.then((isLoggedIn) => {
    if (isLoggedIn) {
        doSomething();
        return;
    }

    GC.AUTH.login();
});

For the use of the data4life JavaScript SDK, also see the README file.