Cookies and Domains

Cookies

By default, V3 uses a single cookie designed for internal use.  However, you can instruct V3 to publish a second Client Domain Cookie that is usable by your application to determine if the current user is logged in and to obtain the user's profile data.  To turn on this second cooke, go to Platform Config > API Security.

Once turned on, the Client Domain Cookie will be inserted into your user's browser after they login.  This cookie is accessible by any web application running on the same domain as your V3 Community.  For example, if your V3 Community is running on community.yourdomain.com, your application could be on wiki.yourdomain.com.

The Client Domain Cookie is named V3ID and its content follows the format:

<CONTACT-ID>:<LOGIN-TIME>:<BASE64-HASH>

Where:

• <CONTACT-ID> is a UUID generated by V3 which never changes for the life of this user and uniquely identifies the user within the V3 Platform.  This UUID is a 36 character string consisting of 5 groups of 8, 4, 4, 4, and 12 hexidecimal digits separated by hyphens.  Example: "ecab4877-4dce-43ed-a22d-5c14190ab721".

• <LOGIN-TIME> is a number value (long integer) representing the UNIX epoch time (in milliseconds) at which the user successfully logged in.
• <BASE64-HASH> is a Base64 encoded string containing the SHA-1 hash of the first two values concatenated together as strings, salted with your organization's API Key.  The API Key can be obtained in V3 HQ under Admin --> External Integration --> Widgets/APIs.

The three tokens are always delimited by colons and always appear in order specified above.

The following code checked the validity of the cookie:

	/**
* Verifies that the cookieContent is valid V3 Domain Cookie 
* content for the given hashSalt.
*
*
* @param cookieContent (String) the full content of the cookie, as a String
* @param hashSalt (String) the Organization specific Domain Cookie salt, the
*           shared secret of the hash. This value is shared between Mobilization Labs
*           and any trusted application developer.
*/ 
function verifyCookie($cookieContent, $apiKey) {
    //Make sure we actually have some cookie content to verify
    if ($cookieContent == NULL || strlen($cookieContent) == 0) {
        return false;
    }

    //break the cookie content into pieces, delimited by ":"
    //the cookie is expected to have 3 pieces - if it doesn't, it fails verification.
    $pieces = explode(“:”, $cookieContent);
    if(sizeof($pieces) != 3) {
        return false;
    }

    //the hash specified in the content, possibly invalid/foraged
    $actualHash = $pieces[2];
    //the expected hash is the base64 encoded bytes of the sha1 hash of the salt,
    //the username (from $pieces[0]), and the login time (from $pieces[1])
    $expectedHash = base64_encode(sha1($hashSalt.$pieces[0].$pieces[1]));
        
    //the cookie content is valid if the expected hash and the actual hash are
    // lexographically equal
    return 0 == strcmp($actualHash, $expectedHash);
}

Login Redirect Domains

V3 can be setup to allow the login page to accept redirect requests.  This allows you to forward the user to the V3 login screen, and upon a successful login, send the user back to the page they were attempting to access.  As user are successfully logged in, V3 inserts a V3ID cookie for use by your other applications.

To use, pass a parameter to the V3 login screen using the following URL format:

http://v3.yourdomain.com/an/login?r=<REDIRECT-URL>

Due to the potential for abuse (phishing schemes, etc.), you must specify a list of "trusted redirect domains" in Platform Config > API Security.