Improve CLI script for account creation and document account/reg setup process

Summary:
There was an old "create_user.php" script but it really was only useful for
creating agents. Provide a more user-friendly script for creating the first
account.

Depends on D278.

Test Plan:
Used 'accountadmin' to create and edit accounts. Read documentation.

Reviewed By: tuomaspelkonen
Reviewers: jungejason, tuomaspelkonen, aran
CC: ccheever, aran, tuomaspelkonen
Differential Revision: 279

bin/accountadmin

@@ -0,0 +1 @@
+../scripts/user/account_admin.php

scripts/user/account_admin.php

@@ -0,0 +1,121 @@
+#!/usr/bin/env php
+<?php
+
+/*
+ * Copyright 2011 Facebook, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+$root = dirname(dirname(dirname(__FILE__)));
+require_once $root.'/scripts/__init_script__.php';
+require_once $root.'/scripts/__init_env__.php';
+
+phutil_require_module('phutil', 'console');
+
+echo "Enter a username to create a new account or edit an existing account.";
+
+$username = phutil_console_prompt("Enter a username:");
+if (!strlen($username)) {
+  echo "Cancelled.\n";
+  exit(1);
+}
+
+$user = id(new PhabricatorUser())->loadOneWhere(
+  'username = %s',
+  $username);
+
+if (!$user) {
+  echo "There is no existing user account '{$username}'.\n";
+  $ok = phutil_console_confirm(
+    "Do you want to create a new '{$username}' account?",
+    $default_no = false);
+  if (!$ok) {
+    echo "Cancelled.\n";
+    exit(1);
+  }
+  $user = new PhabricatorUser();
+  $user->setUsername($username);
+} else {
+  echo "There is an existing user account '{$username}'.\n";
+  $ok = phutil_console_confirm(
+    "Do you want to edit the existing '{$username}' account?",
+    $default_no = false);
+  if (!$ok) {
+    echo "Cancelled.\n";
+    exit(1);
+  }
+}
+
+$original = clone $user;
+
+$user_realname = $user->getRealName();
+if (strlen($user_realname)) {
+  $realname_prompt = ' ['.$user_realname.']';
+} else {
+  $realname_prompt = '';
+}
+$realname = nonempty(
+  phutil_console_prompt("Enter user real name{$realname_prompt}:"),
+  $user_realname);
+$user->setRealName($realname);
+
+$user_email = $user->getEmail();
+if (strlen($user_email)) {
+  $email_prompt = ' ['.$user_email.']';
+} else {
+  $email_prompt = '';
+}
+$email = nonempty(
+  phutil_console_prompt("Enter user email address{$email_prompt}:"),
+  $user_email);
+$user->setEmail($email);
+
+$changed_pass = false;
+$password = phutil_console_prompt(
+  "Enter a password for this user [blank to leave unchanged]:");
+if (strlen($password)) {
+  $user->setPassword($password);
+  $changed_pass = true;
+}
+
+$is_admin = $user->getIsAdmin();
+$set_admin = phutil_console_confirm(
+  'Should this user be an administrator?',
+  $default_no = !$is_admin);
+$user->setIsAdmin($set_admin);
+
+echo "\n\nACCOUNT SUMMARY\n\n";
+$tpl = "%12s   %-30s   %-30s\n";
+printf($tpl, null, 'OLD VALUE', 'NEW VALUE');
+printf($tpl, 'Username', $original->getUsername(), $user->getUsername());
+printf($tpl, 'Real Name', $original->getRealName(), $user->getRealName());
+printf($tpl, 'Email', $original->getEmail(), $user->getEmail());
+printf($tpl, 'Password', null, $changed_pass ? 'Updated' : 'Unchanged');
+
+printf(
+  $tpl,
+  'Admin',
+  $original->getIsAdmin() ? 'Y' : 'N',
+  $user->getIsAdmin() ? 'Y' : 'N');
+
+echo "\n";
+
+if (!phutil_console_confirm("Save these changes?", $default_no = false)) {
+  echo "Cancelled.\n";
+  exit(1);
+}
+
+$user->save();
+
+echo "Saved changes.\n";

scripts/user/create_user.php

@@ -1,49 +0,0 @@
-#!/usr/bin/env php
-<?php
-
-/*
- * Copyright 2011 Facebook, Inc.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *   http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-$root = dirname(dirname(dirname(__FILE__)));
-require_once $root.'/scripts/__init_script__.php';
-require_once $root.'/scripts/__init_env__.php';
-
-if ($argc < 4) {
-  echo "usage: create_user.php <user_name> <real_name> <email> [--agent]\n";
-  die(1);
-}
-
-$username = $argv[1];
-$realname = $argv[2];
-$email    = $argv[3];
-$user = id(new PhabricatorUser())->loadOneWhere(
-  'userName = %s',
-  $username);
-if ($user) {
-  echo "User already exists!\n";
-  die(1);
-}
-
-$user = new PhabricatorUser();
-$user->setUserName($username);
-$user->setRealName($realname);
-$user->setEmail($email);
-if (isset($argv[4]) && $argv[4] == '--agent') {
-  $user->setIsSystemAgent(true);
-}
-$user->save();
-
-echo "Created user.\n";

src/docs/configuration_guide.diviner

@@ -136,6 +136,8 @@ update the code in the future.
 Continue by:
 
   - upgrading the database schema with @{article:Upgrading Schema}; or
+  - setting up your admin account and login/registration with
+    @{article:Configuring Accounts and Registration}; or
   - configuring Phabricator so it can send mail with
     @{article:Configuring Outbound Email}; or
   - configuring inbound mail with @{article:Configuring Inbound Email}; or

src/docs/configuring_accounts_and_registration.diviner

@@ -0,0 +1,98 @@
+@title Configuring Accounts and Registration
+@group config
+
+Describes how to configure user access to Phabricator.
+
+= Overview =
+
+Phabricator supports a number of login systems, like traditional
+username/password, Facebook OAuth, and GitHub OAuth. You can enable or disable
+these systems to configure who can register for and access your install, and
+how users with existing accounts can login.
+
+By default, only username/password auth is enabled, and there are no valid
+accounts. Start by creating a new account with the
+##phabricator/bin/accountadmin## script.
+
+= Using accountadmin =
+
+##accountadmin## is a user-friendly command line interface for creating and
+editing accounts. To use ##accountadmin##, just run the script:
+
+  $ ./phabricator/bin/accountadmin
+  Enter a username to create a new account or edit an existing account.
+
+    Enter a username:
+
+This will walk you through the process of creating an initial user account.
+Once you've created an account, you can login with it and use the web console
+to create and manage accounts more easily (provided you make your first account
+an administrator).
+
+You can use this script later to create or edit accounts if you, for example,
+accidentally remove your admin flag.
+
+= Managing Accounts with the Web Console =
+
+To manage accounts from the web, login as an administrator account and go to
+##/people/## or click "People" on the homepage. Provided you're an admin,
+you'll see options to create or edit accounts.
+
+= Configuring Facebook OAuth =
+
+You can configure Facebook OAuth to allow login, login and registration, or
+nothing (the default). If registration is not allowed, users must have an
+existing account in order to link a Facebook account to it, but can use
+Facebook to login once the accounts are linked.
+
+To configure Facebook OAuth, create a new Facebook Application:
+
+https://www.facebook.com/developers/createapp.php
+
+Once that is set up, edit your Phabricator configuration and set these keys:
+
+  - **facebook.auth-enabled**: set this to ##true##.
+  - **facebook.application-id**: set to your Facebook application's ID. Make
+    sure you set this as a string.
+  - **facebook.application-secret**: set to your Facebook application's
+    secret key.
+  - **facebook.registration-enabled**: set this to ##true## to let users
+    register for your install with a Facebook account (this is a very open
+    setting) or ##false## to prevent users from registering with Facebook.
+  - **facebook.auth-permanent**: you can set this to prevent account unlinking.
+    It is unlikely you want to prevent it, but Facebook's internal install uses
+    this option since Facebook uses Facebook as its only auth mechanism.
+
+= Configuring GitHub OAuth =
+
+You can configure GitHub OAuth to allow login, login and registration, or
+nothing (the default).
+
+To configure GitHub OAuth, create a new GitHub Application:
+
+https://github.com/account/applications/new
+
+Once you've created an application, edit your Phabricator configuration and
+set these keys:
+
+  - **github.auth-enabled**: set this to ##true##.
+  - **github.application-id**: set this to your application/client ID.
+  - **github.application-secret**: set this to your application secret.
+  - **github.registration-enabled**: set to ##true## to let users register with
+    just GitHub credentials (this is a very open setting) or ##false## to
+    prevent users from registering. If set to ##false##, users may still link
+    existing accounts and use GitHub to login, they just can't create new
+    accounts.
+  - **github.auth-permanent**: set to ##true## to prevent unlinking Phabricator
+    accounts from GitHub accounts.
+
+Note that you can see a list of your GitHub applications here, although it's not
+immediately clear how to get there via the UI:
+
+https://github.com/account/applications/
+
+= Next Steps =
+
+Continue by:
+
+  - returning to the @{article:Configuration Guide}.