README

A library for User management in Openclerk, supporting password, OpenID and OAuth2 login.

Installing

Include openclerk/users as a requirement in your project composer.json, and run composer update to install it into your project:

{
  "require": {
    "openclerk/users": "dev-master"
  },
  "repositories": [{
    "type": "vcs",
    "url": "https://github.com/openclerk/users"
  }]
}

Make sure that you run all of the migrations that can be discovered through component-discovery; see the documentation on openclerk/db for more information.

$migrations = new AllMigrations(db());
if ($migrations->hasPending(db())) {
  $migrations->install(db(), $logger);
}

Features

Automatic session management
Autologin
Optionally require emails for all non-password users with users_require_email config parameter
Forgot password/reset password functionality
Users can optionally have multiple OpenID/OAuth2 identities and one password associated with an account

Using

This project uses openclerk/db for database management and openclerk/config for config management.

First configure the component with site-specific values:

Openclerk\Config::merge(array(
  "users_require_email" => false,
  "user_password_reset_expiry" => "3 days",
  "user_password_salt" => "abc123",
  "autologin_expire_days" => 30,
  "openid_host" => "localhost",
  "oauth2_google_client_id" => "abc123.apps.googleusercontent.com",
  "oauth2_google_client_secret" => "abc123",
  "oauth2_facebook_app_id" => "1234567",
  "oauth2_facebook_app_secret" => "abc123",
));

session_start();

You can now register and login users using a variety of authentication methods. The component assumes that only one user can own any one email address, and that all users need to define an email address as their primary key.

// get current user
$user = Users\User::getInstance(db());

// logout any current user
Users\User::logout(db());

// get a user instance
$user = Users\User::findUser(db(), $user_id);

Password

// signup
$user = Users\UserPassword::trySignup(db(), $email /* may not be null */, $password);
if ($user) {
  echo "<h2>Signed up successfully</h2>";
}

// login
$user = Users\UserPassword::tryLogin(db(), $email /* may not be null */, $password);
if ($user) {
  echo "<h2>Logged in successfully as $user</h2>";
  $user->persist(db());
}

// forgot password
$secret = Users\UserPassword::forgottenPassword(db(), $email);
echo "Secret = $secret\n";

// complete forgot password
Users\UserPassword::completePasswordReset(db(), $email, $secret, $new_password);

// add password to existing user
$user = Users\User::getInstance(db());
$result = Users\UserPassword::addPassword(db(), $user, $password);

OpenID

You need to set a redirect value for all the OpenID callbacks, normally the same URL as the current script.

// signup
$user = Users\UserOpenID::trySignup(db(), $email /* may be null */, $openid, "http://localhost/register.php");
if ($user) {
  echo "<h2>Signed up successfully</h2>";
}

// login
$user = Users\UserOpenID::tryLogin(db(), $openid, "http://localhost/login.php");
if ($user) {
  echo "<h2>Logged in successfully as $user</h2>";
  $user->persist(db());
}

// add identity to existing user
$user = Users\User::getInstance(db());
$result = Users\UserOpenID::addIdentity(db(), $user, $openid, "http://localhost/add.php");

OAuth2

For Google OAuth2, login to your Google Developers Console, create a new Project, and visit APIs & Auth:

APIs: Enable Contacts API and Google+ API
Credentials: create a new Client ID of type web applicaton, setting your permissible Redirect URI to the login and redirect URLs used in your application. Use the generated Client ID and Client Secret in your site configuration (above).

For Facebook OAuth2, login to your Facebook Developers Console, create a new App, and visit the Dashboard page for this app to get your App ID and App Secret.

For GitHub OAuth2, register a new GitHub application, and use the generated Client ID and Client Secret in your site configuration (above).

// signup
$user = Users\UserOAuth2::trySignup(db(), Users\OAuth2Providers::google("http://localhost/register.php"));
if ($user) {
  echo "<h2>Signed up successfully</h2>";
}

// login
$user = Users\UserOAuth2::tryLogin(db(), Users\OAuth2Providers::google("http://localhost/login.php"));
if ($user) {
  echo "<h2>Logged in successfully as $user</h2>";
  $user->persist(db());
}

// add identity to existing user
$user = Users\User::getInstance(db());
$result = Users\UserOAuth2::addIdentity(db(), $user, Users\OAuth2Providers::google("http://localhost/add.php"));

More OAuth2 providers provided by default will be coming soon.

Events

openid_validate

Triggered when OpenID validation occurs, after the user has returned with an OpenID mode. If any event returns false, OpenID validation will be cancelled.

Event parameter: $light object

oauth2_auth

Triggered when OpenID authentication occurs, after the user has returned with an OAuth2 code. If any event returns false, OpenID validation will be cancelled.

Event parameter: $provider object

user_deleted

Triggered when a user is deleted through User::delete().

TODO

Track last_login
Removing identities
Tests
Publish on Packagist
Add user names, other user properties
Documentation on adding additional user parameters
Documentation on autologin with cookies
How to add, change, remove email addresses
More events

openclerk / users

Maintainers

Details