Enterprise Single Sign-On (SSO) Protocol Standard

Updated: 2017-02-20

Objective

The goal of this protocol is to allow users who are already logged into an enterprise's internal system to seamlessly log into the Fileshow platform with a single click, without needing to re-enter their username and password. This protocol can also be used for client-side login integration.

Restrictions

Only accounts synchronized through external account data sources (such as AD and LDAP) or those added via the Department and Member Operations API are permitted to use this protocol for login.

Steps

  1. The user logs into the enterprise's internal system.
  2. The user clicks the "Log in to Fileshow" button within the enterprise's internal system.
  3. The internal system passes the user's login information as a parameter to Fileshow by redirecting to a specified URL (see the next section for the URL definition).
  4. Fileshow retrieves the account information and verifies the signature.
  5. Upon successful verification, the user is automatically logged into Fileshow.

Request Format

The request to log in via SSO is made using the following format:

GET /account/autologin/entgrant?client_id={client_id}&ticket={ticket}&returnurl={url}&format={format} HTTP/1.1
Host: app.fileshow.com

Parameters

Parameter Required Description
client_id Yes The client_id from the enterprise management console, added under Authorization Management. Where is Authorization Management?
ticket Yes A value generated by the enterprise's internal system representing the current logged-in user's account information (the algorithm for generating this value is described in the next section).
returnurl No The URL to redirect to after successful login. This URL must be URL-encoded as per RFC3986. If omitted, the default page is used. When the format parameter is set to json, this parameter is ignored.
format No The format of the returned data. If set to json, a JSON response is returned with a structure like {"gkkey": "random_string"}. This can be used to obtain an access_token for client-side login integration via the Login and Authorization API with grant_type=gkkey.

Example Request:

http://app.fileshow.com/account/autologin/entgrant?client_id=xxxxxxxx&ticket=xxxxxxxx

Algorithm for ticket Parameter Value

The ticket parameter value is a JSON string in its raw form:

{
    "account": "user_account",
    "n": "6_random_characters",
    "t": "unix_current_timestamp",
    "sign": "signature"
}

Here's how to calculate the sign value:

  1. Combine the Values: Concatenate the values of account, n, and t with newline characters (\n). For example, consider the following JSON:

    {
    "account": "fileshow",
    "n": "abcdef",
    "t": 1356019200
}

    The combined string would be:

    "fileshow\nabcdef\n1356019200"

  2. Generate the Signature: Use the client_secret (associated with client_id in the Authorization Management) as the key to perform HMAC-SHA1 encryption on the combined string. Then, encode the result in base64.

    sign = base64_encode(hmac-sha1("fileshow\nabcdef\n1356019200", {client_secret}))

  3. Encode the JSON Payload:

    • Base64 encode the original JSON string.
    • Apply URL encoding (according to rfc3986).

This process ensures the secure transmission of the ticket parameter by validating the sign value, which verifies the authenticity and integrity of the data.