Single Sign-On (SSO) with pre shared key
The Single Sign On (SSO) feature enables automatic login from an existing web page. It can be used for instance from an existing intranet page sending the user via a specially crafted link to automatically log them in.
It works by sending a link like the following:
/sso_login?email=user@example.com&signature=207641267b7139d4b8abcc7e33598c5eba3013b1bec6aaf7ac032fa284275bb5
The signature is a SHA-256 hash of the login details combined with your secret key. From v4.3 the recommended format labels each field, so the values have unambiguous boundaries and can't run together:
sha256('email:"the_email" group:"" timestamp:"the_timestamp" secret:"the_sso_secret_key"')
Use the exact field order, double quotes and single spaces shown above, with no commas, and
group:"" when you are not assigning a group. To assign the user to a group, put the group
name in the group field:
sha256('email:"the_email" group:"the_group" timestamp:"the_timestamp" secret:"the_sso_secret_key"')
The email and group values used in the labelled format must not contain
double quotes or backslashes.
Legacy format (deprecated). Links generated with the older, unlabelled
format — sha256(email + timestamp + sso_secret_key), or
sha256(email + group + timestamp + sso_secret_key) when assigning a group — are
still accepted, so existing integrations keep working without changes. New integrations should use
the labelled format above; the unlabelled format may be removed in a future release.
| parameter | description |
|---|---|
| The email (or shortname if you're logging in with LDAP) | |
| timestamp | The current UTC (GMT) time in format YYYYMMDDHHMM. So if the clock is 3:20 AM 21st of September 2011 in San Francisco (UTC-8h +1h for daylight savings), the timestamp would be 201109211020 which is 11:20 Sep 21, 2011 in UTC. |
| sso_secret_key | The SSO secret key needs to be secret between the LiquidFiles appliance and the system generating the login key. Anyone who knows the SSO secret key can login as anyone. It is configured in Admin → Settings. From v4.3 each domain must use its own unique secret key — the same key cannot be configured on more than one domain, so a link signed for one domain can never be used on another. |
| name | Optional parameter which is used when creating users with the SSO login |
| group | Optional parameter which is used when creating users with the SSO login. If specified — and
included in the signature, with the group name in the group field of the
labelled format (or as sha256(email + group + timestamp + sso_secret_key) in the legacy
format) — the new user will be assigned to the specified group (matched by group name or slug). A
group parameter that is not covered by the signature is ignored, and the
user is automatically assigned to their group based on the standard matching for any user. For security,
an administrator group is never assigned through this parameter. Please test by going to Admin →
Groups on your LiquidFiles system and entering usernames/email in the user test to validate that users
will be assigned to the group you intend them to. |
So in the example above, the email is user@example.com, the timestamp 201109211011 and the secret key cRkhmn6egNLz5Bbv2uY1CB, giving the labelled string email:"user@example.com" group:"" timestamp:"201109211011" secret:"cRkhmn6egNLz5Bbv2uY1CB". This leads to the signature being: 207641267b7139d4b8abcc7e33598c5eba3013b1bec6aaf7ac032fa284275bb5.
The SSO login system also have a +-1 minute grace period so if it's 1:12, it will also check 1:11 and 1:13, just in case one of the clocks is a few seconds off.
Each signed link is single-use. From v4.3, a signature is consumed the first time it is presented with a valid signature, so the same link cannot be replayed — even within the grace period above. Generate a fresh link for every login.
Because of this, deliver the link through a server-side redirect from your intranet or portal at the moment of login — do not email these links. Enterprise link scanners (for example Microsoft Safe Links or Proofpoint URL Defense) fetch and follow links when the mail is delivered and would consume the single-use signature before the recipient, locking out the intended user.
Creating Accounts
The SSO login will try to match the user in the following order:
- Check if the user already exists on the system.
- Check if the user exists in LDAP (if configured) and create the user as an LDAP authenticated user if the user exists. The email parameter is matched against the LDAP search attribute, same as on a normal login. Name is grabbed from LDAP if none is provided.
- Create the user as a locally authenticated user (without password) with the optional name from the name parameter