Skip to main content

Authentication with iframes

To embed part of the SkillSpring console in an iframe, like the embeddable expert video, first an OAuth client needs to be enabled and then some code needs to be added to the parent frame to share authentication tokens.

Prerequisites​

Before implementing authentication for an iframe, make sure that an OAuth client has been created for your account and that your parent frame can use the standard OAuth token exchange to authenticate your users and get an access token for the SkillSpring OAuth client.

How to implement​

If you are embedding part of the SkillSpring console in an iframe, the parent frame will need to provide authentication tokens so that the iframe can access the SkillSpring APIs. The DOM postMessage and message event handler is the method of providing tokens to the iframe.

The protocol between the parent frame and the child is this:

  1. When the iframe loads, it requests tokens from the parent with a startSendingAccessTokens message and the parent should respond by watching for that message:

    window.addEventListener('message', function (event) {
        if (
            event.data.source === 'SkillSpring' &&
            event.data.message === 'startSendingAccessTokens'
        ) {
            // Respond to the message as described in step 2 below
        }
    });

  2. The parent should send a message to the child providing the access token:

    // Get the iframe element.
    const iframe = document.getElementById('...');
    // Set the access token using `postMessage(...).
    iframe.contentWindow.postMessage(
       {
           target: 'SkillSpring',
           message: 'setAccessToken',
           token: '<tokenvalue>',
       },
       'https://console.us.skillspring.com'
    );

  3. If the access token changes in the parent, it can resend the message from step 2 to update the iframe.

  4. If the iframe hits an authentication problem with the token that it is given from the parent, then it might request the token be refreshed with a refreshAuth message. The parent should listen for refreshAuth requests and use a setAccessToken message to send an updated token:

    window.addEventListener('message', function (event) {
        if (
            event.data.target === 'SkillSpring' &&
            event.data.message === 'refreshAuth'
        ) {
            // Refresh the auth token and eventually send an updated token to
            // the frame with the example from step 2
        }
    });