Login Hint Tokens

A login hint token is very different from the other tokens because it is created by the client (application) and not by the Authway. This token can be used to identify a user in different Single-sign-on scenarios or during Client Initiated Backchannel Authentication. The purpose of this token is to uniquely identify a user by the client to allow the Authway to sign-in the user in a better way.

Create a Login Hint Token

The login hint token must fullfil these requirements:

  1. A valid JWT token.
  2. Use the HS256 algorithm to sign the token.
  3. Hash the shared client secret with SHA256 and use a base64 encoded hashed value as key when signing the token.
  4. The issuer must be the client id that creates the SSO token.
  5. Include an audience claim with the Identity Provider as audience.
  6. Include an issued at (iat) claim with the time when the client created the SSO token.
  7. Include a sub claim with the unique identifier of the user that should be signed in. If the identity is not knwon to the client (typically in CIBA) other identifiers such as e-mail, phone number or a social security number can be included.
  8. Optionally include a tid claim. This is useful if the unique identifier is not known and passing it in the login hint token is an option to pass it in acr_values.

Sample token (without signature):

{
  "alg": "HS256",
  "typ": "JWT"
}.
{
  "sub": "FEFC9E8B-062B-DF44-FDF0-39FC52AE2B58",
  "iat": 1674050819,
  "iss": "TestTrustedApp",
  "aud": "https://tenant.irmciam.se"
}

C# example of creating a SSO token

var subClaim = new Claim("sub", "FEFC9E8B-062B-DF44-FDF0-39FC52AE2B58"); //Get claim value from signed-in user
var clientId = "TestTrustedApp";
var clientSecret = "W7k1i3EvpYSApLj6CW7pYGkYsFTGdwJ96m0uIh64";
var authority = "https://tenant.irmciam.se";
var key = Encoding.ASCII.GetBytes(clientSecret.Sha256()); //= Client secret

var credentials = new SigningCredentials(new SymmetricSecurityKey(key), SecurityAlgorithms.HmacSha256Signature);
            
var tokenDescriptor = new SecurityTokenDescriptor {
    Subject = new ClaimsIdentity(new Claim[] { subClaim }),
    Issuer = clientId, 
    IssuedAt = DateTime.UtcNow,
    Audience = authority, 
    SigningCredentials = credentials
};
            
var tokenHandler = new JwtSecurityTokenHandler();

var token = (JwtSecurityToken)tokenHandler.CreateToken(tokenDescriptor);

var serializedToken = tokenHandler.WriteToken(token);
public static string Sha256(this string input)
{
    if (input.IsMissing()) return string.Empty;

    using (var sha = SHA256.Create())
    {
        var bytes = Encoding.UTF8.GetBytes(input);
        var hash = sha.ComputeHash(bytes);

        return Convert.ToBase64String(hash);
    }
}

Python example of creating a login hint token

This sample is still not verified.

This example uses of PyJWT (https://pyjwt.readthedocs.io/en/latest/usage.html).

import jwt
import base64
from hashlib import sha256

sub = "FEFC9E8B-062B-DF44-FDF0-39FC52AE2B58"
clientId = "TestTrustedApp"
clientSecret = "W7k1i3EvpYSApLj6CW7pYGkYsFTGdwJ96m0uIh64"
authority = "https://tenant.irmciam.se"
key = sha256(clientSecret.encode("utf-8"))
base64_bytes = base64.b64encode(key)
key = base64_bytes.decode("ascii")

payload = {"sub": sub, "iss": clientId, "aud": authority, "iat": 1674050819}

serializedToken = jwt.encode(payload, key, algorithm="HS256")