Auth SDK Embed in iframe

Integrating iframe

1. Configure the URL for the iframe

First you need to get your Temporary Token. After you have it append the URL parameter api_key=${TEMPORARY_TOKEN} and the URL parameter iframe=true to your authentication link. This will make sure that the response message is sent via postMessage to the parent window.
Another mandatory parameter is externalUserId which is the ID of the user in your system. This is used to identify the user in the Finsquid system. It should be a unique string.

const AUTH_URL = new URL("https://sdk-staging.finsquid.io/auth");
AUTH_URL.searchParams.set("api_key", TEMPORARY_TOKEN);
AUTH_URL.searchParams.set("externalUserId", USER_ID);
AUTH_URL.searchParams.set("iframe", true);

const AUTH_LINK = AUTH_URL.toString();

2. Additional params (Optional)

You can specify the exact bank to connect to by passing the providerId parameter. To obtain the required provider ID, you should use the GET v1/providers endpoint. The request must be authenticated using your temporary token.
```
curl -X GET 'https://gateway-staging.finsquid.io/v1/providers' \
-H 'Authorization: Bearer {TEMPORARY_TOKEN}'
```
You will receive a list of providers with IDs, and you can pass the required provider ID to the Auth SDK link.
```
AUTH_URL.searchParams.set("providerId", "99");
```

You can also pass the credentials for the bank you want to connect to by passing the loginOptions parameter. The value of the parameter should be a JSON string with the following format:

const loginOptions: SDKLoginOptions = [
  {
    loginMethod: "bankidSSN",
    userId: "098709870987",
  },
  {
    loginMethod: "usernamePassword",
    username: "098709870987",
    password: "password",
  },
];
AUTH_URL.searchParams.set("loginOptions", JSON.stringify(loginOptions));

In this case, every bank that utilizes the following login methods will have these values prepopulated.

3. Add the URL to an iframe element

Add the authentication link as the src parameter of an <iframe> HTML element.

<iframe src="{AUTH_LINK}" />;

An iframe will by default be 300px wide and 150px tall. To allow the iframe to seamlessly adapt its size to the containing element, make sure to apply appropriate sizing either by css or inline-styles. Using the width attribute will give the iframe a static width, which is not recommended when targeting mobile devices.

<!-- ❌ not recommended for mobile devices -->
<iframe src="{AUTH_LINK}" width="400" />

<!-- ✅ adapt to the size of the parent element -->
<iframe src="{AUTH_LINK}" style="width:100%;" />

4. Add a listener to your app

All communication between an iframed Finsquid Auth and the parent host is done via postMessage. Register a listener to start receiving messages. How you do this is up to you, but the code below shows the basics.

window.addEventListener("message", handlePostMessage);

const handlePostMessage = (event: any) => {
  if (event.origin !== AUTH_LINK.origin) return;

  const { type, data, error } = JSON.parse(event.data);

  if (type === "success") {
    // This is the provider object that contains sid that should be used in headers for API requests
    console.log(`Auth SDK returned with provider object: ${data}`);
  } else if (type === "error") {
    // Handle error response from Auth SDK
    console.log(
      `Auth SDK returned with error type: ${error.type} and error message: ${error.message}.`
    );
  }
};

Also, as with all web development, make sure to take the necessary security precautions. You can read more about postMessage here.

5. Authenticate and see if it works

Go through the authentication inside the integrated iframe flow. If all is successful, you should receive the provider object.

{
  //You should use this sid in headers for API requests
  sid: "0a2c72e0-9e20-4c99-ac6c-91299623043d",
  name: "nordnet",
  iconUrl: "https://gateway-staging.finfollow.com/resources/nordnet.png",
},

Reference

If you integrate Finsquid Auth in your application via an iframe, the result will be delivered as JSON object via postMessage to the parent window.