VZ-Login-Tutorial

From VZ Developer Wiki
Revision as of 15:03, 30 November 2010 by Seba (talk | contribs) (Step 4: Start coding)
Jump to: navigation, search

A Step-by-Step Guide to using VZ as Your Login Handler

Why VZ-ID?

If your website requires authenticated users which have to sign up in first place, this process is usually considered as a conversion killer. Users are more likely to sign up if they can use their already existing credentials. This is where VZ-ID comes into play. It offers an easy-to-use API which integrates with your website's user management. The following guide will describe how the integration can be achieved with a few lines of code.

The following guide was created using a MeinVZ developer account, but it will work for the other platforms in the same fashion.

Step 1: Go to the developer section

Before you can integrate VZ-ID you are required to sign in as a developer on either one of the following platforms: StudiVZ, MeinVZ or SchülerVZ. Your account will be activated after it went though our validation and approval process.

Step 2: Create a new service

Before you can use the API, you will be requested to create a "service" which contains information about your website that is about to use VZ-ID.

  • Service Name is just an identifier to help you to identify your current website among other websites and services you already created or you might create in future
  • Description describes the nature of your website
  • Callback URL must be an accessible URL within your domain. You will copy an HTML file there which will be provided later in this tutorial

Step1.png

Step 3: Copy your access data

A successfully completed service creation will guide you to the following interface. It shows all credentials which you will need in order to integrate VZ-ID on your website.

  • Copy your key and your secret to the clipboard, you will need it during the next step.

Step2.png

Step 4: Start coding

<?php
    $consumerKey = 'consumer key';
    $consumerSecret = 'consumer secret';
    $cookieKey = 'vz_' . $consumerKey;
    $requiredFields = array('name', 'emails');
    $redirectUrl = 'http://path/to/vzid-democlient/callback.html';
    $registrationUrl = 'http://path/to/vzid-democlient/registration.php';
?>
<html>
    <head>
        <title>Index</title>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    </head>
    <body>
        <script src="http://static.pe.studivz.net/Js/id/v2/library.js"
        data-authority="platform-redirect.vz-modules.net/r"
        data-authorityssl="platform-redirect.vz-modules.net/r" type="text/javascript">
        </script>
    </body>
    <script type="text/javascript">
    function logResponse(c) {
        if (c.error) {
            console.log(c);
            return;
        }

        var parameters = 'access_token=' + c.access_token;
        parameters += '&user_id=' + c.user_id;
        parameters += '&signature=' + c.signature;
        parameters += '&issued_at=' + c.issued_at;

        document.cookie = '<?php echo $cookieKey ?>' + '=' +  encodeURIComponent(parameters);
        document.location.href = '<?php echo $registrationUrl ?>';
    }
    </script>
    
    <script type="vz/login">
       client_id : <?php echo $consumerKey . PHP_EOL ?>
       redirect_uri : <?php echo $redirectUrl . PHP_EOL ?>
       callback : logResponse
       fields : <?php echo implode(',', $requiredFields) . PHP_EOL ?>
    </script>
</html>

Step 5: callback.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <title>Callback</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  </head>
  <body>
      <script type="text/javascript">
        opener.vz.id.authStorage.setAuthParameterHash(location.hash.substr(1));
        window.close();
      </script>
  </body>
</html>

Step 6: Signature verification

<?php
    $consumerKey = 'consumer key';
    $consumerSecret = 'consumer secret';
    $cookieKey = 'vz_' . $consumerKey;


    if ($loggedInWithVzId = isset($_COOKIE[$cookieKey])) {
        // check if VZ-ID cookie exists and is valid
        $cookie = array();
        parse_str($_COOKIE[$cookieKey], $cookie);

        $baseString = $cookie['access_token'] . $cookie['issued_at'] . $cookie['user_id'];
        $signature = base64_encode(hash_hmac('sha1', $baseString, $consumerSecret, true));
        $retrievedSignature = $cookie['signature'];

        // check if given signature equals calculated signature which used the
        // consumer secret in order to avoid user id manipulation
        if ($signature !== $retrievedSignature) {
            throw new Exception('invalid cookie signature');
        }
    }   
?>

Step 7: Acces the user data

<html>
    <head>
        <title>Registration</title>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    </head>
    <body>
       <?php if ($loggedInWithVzId): ?>
        <h1>Successuflly logged in with VZ-ID</h1>
        <?php

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $cookie['user_id'] . '?oauth_token=' . $cookie['access_token']);
        curl_setopt($ch, CURLOPT_HTTPGET, true);
        curl_setopt($ch, CURLOPT_HEADER, 0);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        $ret = curl_exec($ch);
        curl_close($ch);

        $userData = json_decode($ret, true);
        var_dump($userData['entry']);
        ?>
       <?php else: ?>
        <h1>Please register or log in</h1>
        <!--
       <?php endif ?>
    </body>
</html>