Hosted Login session checking

Few things in life are as frustrating as logging onto a website, navigating away from that site for a few minutes, then returning to find out that you’re required to log in again. Admittedly, this can sometimes be for your own good: it’s not necessarily a bad idea for your banking web site to require a new authentication each time you access the site. On the other hand, and in cases where the stakes aren’t quite as high, having to log on when you come back to a site, or having to log on if you try to access that same site in another browser tab, can be … frustrating.

As you probably know.

To help alleviate this frustration, Hosted Login includes the sid (session_uuid) claim in each identity token it issues. For example, if you log on to website A, your decoded identity token will look similar to this:

{
    "acr": "urn:akamai-ic:nist:800-63-3:aal:2",
    "amr": [
        "pwd",
        "email",
        "mfa",
        "rba"
    ],
    "at_hash": "ALXc_YDALIO5tZx-ylYSbg",
    "aud": [
        "64430515-01ea-4f5d-82e4-c36161af0093"
    ],
    "auth_time": 1645632102,
    "azp": "64430515-01ea-4f5d-82e4-c36161af0093",
    "exp": 1645635706,
    "global_sub": "capture-v1://se-demos-gstemp.us-dev.janraincapture.com/79y4mqf2rt3bxs378kw5479xdu/GREG_DEMO/1093dc46-ec44-4e23-82c3-b2c22f7302db",
    "iat": 1645632106,
    "iss": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login",
    "jti": "v6k0jxLefT7YkK8hJXjdlvjo",
    "sid": "40446321-b702-4bc0-97dc-fb458cf3dcc8",
    "sub": "1093dc46-ec44-4e23-82c3-b2c22f7302db"
}

The sid claim references the unique identifier assigned to your Hosted Login session. Equally important, that sid remains assigned to you until you log out (or your session otherwise ends). For example, suppose you log on to a Hosted Login website and then navigate away from that site for a while. When you return, Hosted Login can retrieve the sid claim from your identity token, verify that your session is still valid, and allow you back onto the site without having to reauthenticate.

Or at least that happens if your authorization request has the prompt parameter set to none. If the prompt parameter is set to login or to create, then either the sign-in screen or the account creation screen is displayed, just the way you’d expect them to. And what if you don’t have a valid sid? In that case, login fails with a No authenticated session found error, and then you will need to log in again.


📘

However, the sign-in screen won’t automatically be displayed. You’ll need to trap for that error and then submit a new authorization request in order to display the screen.


And if you don’t use the prompt parameter at all? In that case, a user with a valid session will be waved through and a user without a valid session will be stopped. With no prompt parameter, however, the sign-in screen will be displayed and the user can simply log in.


📘

Can’t Hosted Login do this without the sid claim? Yes, it can. But using the sid claim makes session checks faster and more efficient, and cuts down on network traffic.


Incidentally, when you do get readmitted to the site your sid remains the same (in this example, 40446321-b702-4bc0-97dc-fb458cf3dcc8). That’s the whole idea.


📘

One thing we should mention is that this session check is just that: a check to see whether a valid session is still running. What the session check doesn’t do is restart the session clock. For example, suppose you allow sessions to run for 24 hours before they expire. Ten hours after starting a session, a user comes back to your website and a session check is performed. At that point, the user’s session will have 14 hours remaining before it expires: 24 hours minus the 10 hours that the session has been running. The session check does not reset the session to its full 24-hour lifespan.


Now, suppose you open a second browser tab, or even a second browser window (but using the same web browser as your initial session). If you go to back to the Hosted Login website you won’t have to reauthenticate and you’ll be assigned the same sid. And what if you open a second browser tab and you do reauthenticate? (For example, because you clicked an authorization request link where the prompt is set to login?) Well, in that case, you will need to log on again: setting the prompt to login makes that a requirement. But if you log on a second time your new identity token includes the same sid as your original identity token. For example, here's our initial identity token; note the value of the sid claim as well as the value of the jti claim (the unique identifier of the token itself):

"jti": "ZUlobNc91UA5juaudeE8O9pX",
"sid": "09182aa7-b090-4b03-a1ef-74144f03faa8",
"sub": "1093dc46-ec44-4e23-82c3-b2c22f7302db"

And here’s the second token we were issued. As you can see, the jti value differs from the first token; that’s how we know we’re working with two different tokens:

"jti": "i4xOsTA-7fd2jXs-s6RsZa-j",
"sid": "09182aa7-b090-4b03-a1ef-74144f03faa8",
"sub": "1093dc46-ec44-4e23-82c3-b2c22f7302db"

But the sid** **claim? That’s exactly the same value found in our original token. Effectively, all we’ve done is “expand” our session to cover two browser tabs (and two identity tokens).

And what if you log out from either of those browser tabs (or browser windows)? In that case, you’ll be logged out of your session, your siddisappears and your access tokens are revoked. If you return to the site after that, and if you return by using an authorization request that sets the prompt parameter to none, login fails with the No authenticated session found error. At that point all you can do is reauthenticate, at which time you’ll be issued a brand-new set of tokens and, equally important, a brand-new sid.

A few cautions and caveats are in order here. For starters, session checking only works for a specific web browser on a specific piece of hardware. For example, suppose you use Safari to log on to a website, and, after a successful authentication, you’re issued the sid 7edb5e45-ead5-4638-b236-038394c1ad5. Suppose you now open the Edge browser and journey to that same site. In that case, and because it’s a different browser, you won’t be automatically be waved through. Instead, you’ll need to log on, and, when you do, you’ll be issued a different sid (e.g., a29fd33c-f6a3-4f65-9860-16f503fddca7) for the Edge session. Different browsers result in different sessions and different session IDs.


📘

This is also the case if you log on to a site using a regular browser window, then access that same site from a private window. In that case you’ll be asked to log on even though the browser is the same; that’s because session information can’t be exchanged between a regular browser window and that same browser running in a private window.


Similarly, suppose you use the Chrome browser on your computer to log on to a website. You now get out your cell phone and use the Chrome browser on the phone to connect to that same website. As you might have guessed, you’ll need to log on with that cell phone: session information is not shared between different pieces of hardware.

Session checking implementation

By itself, Hosted Login can do basic session checking: Hosted Login can determine whether you have a valid session running on a specified device (i.e., a specific web browser on a specific piece of hardware) and, if so, can allow you access to a website without making you reauthenticate. At the same time, however, there are limits to what Hosted Login can do by itself, limits you need to be aware of.

First, Hosted Login can allow you to bypass authentication if you have a valid session and the prompt parameter in your authorization request is set to none. But what if you don’t have a valid session? In that case, login fails with a No authenticated session found error.

But that’s as far as Hosted Login goes: an error occurs, and the user doesn’t get logged on. Most likely what you’d really like to happen is for a more user-friendly error message and the sign-in screen to be displayed; that way the user has the opportunity to log on (and thus create a new authenticated session). But that’s something you’ll need to code yourself.


📘

Yes, you’ll need to trap for the Hosted Login error. Although there’s a new endpoint that’s used for session checking, that endpoint is for Identity Cloud use only: there’s no way for you to directly query the session checking endpoint.


And one final note. The use of the session ID opens the door to a true single sign-on (SSO) experience: a user with an authenticated session on website A can automatically gain access to website B without having to log on to website B. But, again, that requires at least some coding effort on your part.


Did this page help you?