Implicit Flow

The Implicit Flow is used by API Clients that run in a browser using a scripting language. Mainly javascript web applications such as Single-Page Applications (SPAs). The Access Token is returned directly to the API Client (browser).

In this flow, the client browser is redirected to Stems Accounts login page for authentication. If the current user already has an active session then Stems Accounts issues an Access Token and redirects the user back to the API Client.

Authentication Request

An API Client that uses the Implicit Flow will first need to redirect the user to Stems Accounts Authorization endpoint with the following url querystring parameters:

A typical Implicit Flow request to the authorization endpoint would look like the following:

GET /auth/connect/authorize?
client_id=YOUR_CLIENT_ID
&redirect_uri=http:%2F%2Fcontoso.com
&response_type=id_token token
&scope=openid email roles resources_accounts_api
&state=sdfkjhfafsaff
&nonce=sd9f789sdf79dsafa79s7f9sa HTTP/1.1

Host: accounts.stems.com.au

If everything goes well after the request to the authorization endpoint, Stems Accounts will redirect the user back to the redirect_uri with the following url-encoded fragment values:

Assuming that the redirect_uri of your client application is https://contoso.com, a typical Implicit Flow authorization response would look like the following:

GET #id_token=eyJ0eXATG9udtr2vGu6AC22j9L
&access_token=62003456fa10f473a530315fb3c1e
&token_type=Bearer&expires_in=1800
&scope=openid%20email%20roles%20resources_accounts_api
&state=234567878
&session_state=V5l2k_5CPvVDTpejgkkgN_FdbK5MzUUrrGfrQpJdykg HTTP/1.1

Host: contoso.com

Note

The id_token and session_state parameter are usually longer than the examples above. The values have been truncated for better clarity

The Authorization Endpoint could return errors if the API Client is not setup properly or the request had invalid or missing parameters. When an error occurs, the Authorization Endpoint will return to the API Client's redirect_uri with an error parameter containing an error code and an optional error_description fragment parameter with details about the error.

ID Token Validation

Once you have received the Access Token and ID Token, you MUST validate the ID Token to make sure it hasn't been tampered with as a result of a replay attack.

The process of validating an ID Token is exactly the same as when using the Authorization Code flow. Please refer to the ID Token Validation section to read about how you can validate an ID Token.

Access Token Expiration

Because Implicit Flow clients cannot receive a refresh token, once the access token has expired you will have to request a new one by issuing an Authentication Request.

This can be achieved by implementing a mechanism that keeps track of the access token expiration. Similar to the snippet below that checks the validity of the Access Token every 30 seconds

var tokenTimer;

tokenTimer = setInterval(function() {
        var session = getSession();
        //no existing session
        if (!session) {
        clearInterval(tokenTimer);
        //either issue a request to the Authorization endpoint or a "Login" UI
    }

        //access token expiring in one minute or less
        else if(session.expiration.setMinutes(-1) < new Date()){
        //issue a request to the Authorization endpoint on a hidden iframe 
        //so it is transparent to the user
    }

}, 30 * 1000);

If the Access Token has expired or is about to expire you can issue an Authentication Request in a hidden iframe to avoid disturbing the user interaction with the application.

You will also want to pass the prompt query string parameter with the value of none. This will prevent Stems Accounts from rendering a login page if there's no active session in Stems Accounts

Ideally, you will also pass a different (and valid) redirect_uri so that Stems Accounts redirects back to a page in your application that processes the request and renews the session automatically without interfering with the user. Don't forget that the redirect_uri must be a valid url registered with the API Client.

Monitoring Session Status

The previous section explains how you can monitor the validity of the Access Token so that your Implicit Flow application can renew it before it expires, even if the current user is actively utilizing the application.

However, there are many cases where the same user might have logged out of Stems Accounts. When this happens, you'll want your application to reflect the fact that the user has already logged out and there should not be an active session. To handle this scenario, you would need an invisible iframe on your application pointing a separate page/view as below.

<iframe id="checkSessionIframe" src="check_session.html" style="display: none"></iframe>

The only responsibility of this page/view is to poll the Check Session endpoint in Stems Accounts to query the status of the current user's session with the help of an invisible iframe.

<iframe id="iodc-check-session" src="https://accounts.stems.com.au/auth/connect/checksession" style="display: none"></iframe>

Once you have this iframe in place, you can reload it periodically to determine whether the current session has changed.

<script>
    var client_id = "YOUR_API_CLIENT_ID";
    var oidc_origin = "https://accounts.stems.com.au";
    var timer_id;

    window.addEventListener("message", receive_message, false);

    function check_session() {
        var msg = '${client_id} ${session_state}';
	var  iframe = document.getElementById("iodc-check-session");

	if(iframe){
	    iframe.contentWindow.postMessage(msg, oidc_origin);
	}
    }

    function monitor_session() {
        //executes check_session every 10 seconds
        timer_id = setInterval(check_session, 10 * 1000);
    }

    function receive_message(e) {
        if (e.origin !== oidc_origin) {
            return;
        }

        if (e.data === "changed") {
            clearInterval(timer_id);

            //clear the application session and log the current user out
        }
        else if(e.data === "unchanged"){
	    //the user's session is still valid/active in Stems Accounts
	}
    }

    monitor_session();
</script>

A status with value of "changed" means that the user has logged out of Stems Accounts and you need to carry out the necessary actions to invalid the current user's session in your application such as logging the user out, clearing the current session, etc.

For more information, check out the OpenID Connect Session Management specifications. We can also provide a sample application through our Support System.

Logging Out

To log out the current user from both your application and Stems Accounts, all you need to do is:

• Clear your application's session
• Redirect the user to the Logout page in Stems Accounts

https://accounts.stems.com.au/logout