WordPress.com Connect

A secure and easy way for millions of WordPress.com users to log in to your website or app. By integrating with WordPress.com Connect, WordPress.com users can quickly log in and start using your service. Their profile information is shared with your app saving you the hassle of collecting name, email address, etc. You even get their Gravatar profile picture.

Benefits

Millions Of Users – WordPress.com consists of millions of users and is growing every day. By adding WordPress.com Connect you will become part of a large family that makes it easy for WordPress.com users to explore new services.

Compatible with your existing sign-in system – WordPress.com Connect can be used on its own or as a complimentary sign-in option to your existing registration system. Once a user connects, you will get access to their profile information which you can use in your own app.

Trusted Relationship – Allow users to sign-in with the same credentials they use every day on WordPress.com. This takes the pain out of having to remember and manage a new log-in for another service.

Get Started

The first thing you need to do is create a new WordPress.com Application, this will give you a chance to describe your application and how we should communicate with it. You should give your app the same title as your website as that information is used in the login form users see. Once configured you will receive your CLIENT ID and CLIENT SECRET to identify your app.

Integrate with your app using the below instructions or use the code examples in this Github Project for implementing in other languages (PHP, Python, Node.js, maybe others in the future).

PHP Example Integration

Here is a simple example of how you can connect a WordPress.com user to your app or website and then get back their profile information.

When you created your WordPress.com Application above you will have received a number of items back. Let’s set those as constants to make them easy to reference. (Please replace the values of the CLIENT_ID, CLIENT_SECRET and REDIRECT_URL with those values from your WordPress.com Application)

define( 'CLIENT_ID', 1234 );
define( 'CLIENT_SECRET', 'XXXXXXXXXXXX' );
define( 'REDIRECT_URL', 'http://example.com/wpcc.php' );
define( 'REQUEST_TOKEN_URL', 'https://public-api.wordpress.com/oauth2/token' );
define( 'AUTHENTICATE_URL', 'https://public-api.wordpress.com/oauth2/authenticate' );

Create a Connect button

In the following code snippets we will just use the constant CLIENT_ID etc. to denote the values that are unique to your WordPress.com Application. First up we need to generate the button that your users will click in order to connect to WordPress.com. An anti-forgery “state” token is required to protect the security of your users. Create the variable with a good random number generator and save it on your server. The token is sent back to your server after the user authenticates and you must verify that the tokens match. The button’s link should navigate a visitor to the authentication URL and include query parameters describing your application.

<?php

session_start();
$wpcc_state = md5( mt_rand() );
$_SESSION[ 'wpcc_state' ] = $wpcc_state;

$url_to = AUTHENTICATE_URL . '?' . http_build_query( array(
	'response_type' => 'code',
	'client_id'     => CLIENT_ID,
	'state'         => $wpcc_state,
	'redirect_uri'  => REDIRECT_URL
) );

echo '<a href="' . $url_to . '"><img src="//s0.wp.com/i/wpcc-button.png" width="231" /></a>';

This will output a button like so:

Request an Access Token

When the user clicks on the Connect button they will be brought to a form that asks them to log in and explains what information will be revealed to your app.

oauth-approve

Once they complete this they will be sent to the “redirect URL” you have set in your WordPress.com Application (which is the value of the REDIRECT_URL constant above). When this URL is loaded please check that the state variable returned matches the one stored locally and also look for the code parameter. Using that code variable your app then sends a request to WordPress.com looking for a permanent access_token which you can use from then on to reference this user. You can store the access_token in your app for future use.

<?php

require_once dirname( __FILE__ ) . '/defines.php';

if ( ! isset( $_GET[ 'code' ] ) ) {
	die( 'Warning! Visitor may have declined access or navigated to the page without being redirected.' );
}

session_start();
if ( $_GET[ 'state' ] !== $_SESSION[ 'wpcc_state' ] ) {
	die( 'Warning! State mismatch. Authentication attempt may have been compromised.' );  	
}

$curl = curl_init( REQUEST_TOKEN_URL );
curl_setopt( $curl, CURLOPT_POST, true );
curl_setopt( $curl, CURLOPT_POSTFIELDS, array(
	'client_id'     => CLIENT_ID,
	'redirect_uri'  => REDIRECT_URL,
	'client_secret' => CLIENT_SECRET,
	'code'          => $_GET[ 'code' ],
	'grant_type'    => 'authorization_code'
) );

curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1 );
$auth = curl_exec( $curl );
$secret = json_decode( $auth );

$secret is an object that contains the access_token that you will use to query the users profile information.

stdClass Object 
(
    [access_token] => XXXXXXXXXXXXXXXXXXXXXXXXXXXX
    [token_type] => bearer
    [blog_id] => 0
    [blog_url] => http://public-api.wordpress.com
    [scope] => auth
)

Request user profile information

After you get an access_token you must authenticate the user on your local site. You use the access_token to request their profile information through the /me/ endpoint on WordPress.com.

<?php
$access_token = $secret->access_token;

$curl = curl_init( 'https://public-api.wordpress.com/rest/v1/me/' );
curl_setopt( $curl, CURLOPT_HTTPHEADER, array( 'Authorization: Bearer ' . $access_token ) );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1 );
$me = json_decode( curl_exec( $curl ) );

A typical request for profile information would return JSON encoded data with the following profile information in an object:

{
  "ID": 1,
  "display_name": "Bob",
  "username": "bobsmith",
  "email": "bob@example.com",
  "primary_blog": 1,
  "avatar_URL": "http://gravatar.com/avatar/xxxx?s=96",
  "profile_URL": "http://en.gravatar.com/xxxx",
  "verified": true
}

Authenticate the User

The verified flag in the profile is true when the user has verified their email address on WordPress.com. You should take this into consideration before using the profile. If it is false be wary of trusting the information and using it in an automated way.
With this information you should query your user database and log the user in if a record exists. Otherwise you may auto-generate a new account or redirect the user to a signup form. You should pre-populate as many fields as possible from the profile information above.

Limits of Login Apps

If you already have WordPress.com apps do not use one app for both login and interacting with a WordPress.com blog. Access tokens generated through the authenticate endpoint used in login requests only have access to the /me/ endpoint. Your users will not be able to access their blogs if they attempt to login through the same app.