phorge-phorge/src/docs/configuration/configuring_accounts_and_registration.diviner

@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, GitHub OAuth, and Google 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.

= Managing Accounts from the Command Line =

You can use ##scripts/user/add_user.php## to batch create accounts. Run it
like:

  $ ./add_user.php <username> <email> <realname> <admin>

For example:

  $ ./add_user.php alincoln alincoln@logcabin.com 'Abraham Lincoln' tjefferson

This will create a new ##alincoln## user and send them a "Welcome to
Phabricator" email from ##tjefferson## with instructions on how to log in and
set a password.

= 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

You should set these things in your application:

  - **Site URL**: Set this to your full domain with protocol, like
    "##https://phabricator.example.com/##".
  - **Site Domain**: Set this to the entire domain, like ##example.com##. You
    might be able to get away with including the subdomain if you want to
    scope more tightly.

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

You should set these things in your application:

  - **URL**: Set this to the full domain with protocol, like
    "##https://phabricator.example.com/##".
  - **Callback URL**: Set this to your domain plus "##/oauth/github/login/##",
    like "##https://phabricator.example.com/oauth/github/login/##".

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/

= Configuring Google OAuth =

You can configure Google OAuth to allow login, login and registration, or
nothing (the default).

To configure Google OAuth, create a new Google "API Project":

https://code.google.com/apis/console/

You don't need to enable any **Services**, just go to **API Access**, click
**"Create an OAuth 2.0 client ID..."**, and configure these settings:

  - Click **More Options** next to **Authorized Redirect APIs** and add the
    full domain (with protocol) plus ##/oauth/google/login/## to the list.
    For example, ##https://phabricator.example.com/oauth/google/login/##
  - Click **Create Client ID**.

Once you've created a client ID, edit your Phabricator configuration and set
these keys:

  - **google.auth-enabled**: set this to ##true##.
  - **google.application-id**: set this to your Client ID (from above).
  - **google.application-secret**: set this to your Client Secret (from above).
  - **google.registration-enabled**: set this to ##true## to let users register
    with just Google 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 Google to login, they jus can't create new
    accounts.
  - **google.auth-permanent**: set this to ##true## to prevent unlinking
    Phabricator accounts from Google accounts.

= Next Steps =

Continue by:

  - returning to the @{article:Configuration Guide}.