@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
Provide contextual help on auth provider configuration
Summary:
Ref T1536.
- Move all the provider-specific help into contextual help in Auth.
- This provides help much more contextually, and we can just tell the user the right values to use to configure things.
- Rewrite account/registration help to reflect the newer state of the word.
- Also clean up a few other loose ends.
Test Plan: {F46937}
Reviewers: chad, btrahan
Reviewed By: chad
CC: aran
Maniphest Tasks: T1536
Differential Revision: https://secure.phabricator.com/D6247
+167
-158
-9
conf/default.conf.php
-9
conf/default.conf.php
···
553
553
554
554
// -- Auth ------------------------------------------------------------------ //
555
555
556
-
// Can users login with a username/password, or by following the link from
557
-
// a password reset email? You can disable this and configure one or more
558
-
// OAuth providers instead.
559
-
'auth.password-auth-enabled' => true,
560
-
561
556
// Maximum number of simultaneous web sessions each user is permitted to have.
562
557
// Setting this to "1" will prevent a user from logging in on more than one
563
558
// browser at the same time.
···
1031
1026
1032
1027
'aphront.default-application-configuration-class' =>
1033
1028
'AphrontDefaultApplicationConfiguration',
1034
-
1035
-
'controller.oauth-registration' =>
1036
-
'PhabricatorOAuthDefaultRegistrationController',
1037
-
1038
1029
1039
1030
// Directory that phd (the Phabricator daemon control script) should use to
1040
1031
// track running daemons.
+12
src/applications/auth/application/PhabricatorApplicationAuth.php
+12
src/applications/auth/application/PhabricatorApplicationAuth.php
···
14
14
return 'authentication';
15
15
}
16
16
17
+
public function getHelpURI() {
18
+
// NOTE: Although reasonable help exists for this in "Configuring Accounts
19
+
// and Registration", specifying a help URI here means we get the menu
20
+
// item in all the login/link interfaces, which is confusing and not
21
+
// helpful.
22
+
23
+
// TODO: Special case this, or split the auth and auth administration
24
+
// applications?
25
+
26
+
return null;
27
+
}
28
+
17
29
public function buildMainMenuItems(
18
30
PhabricatorUser $user,
19
31
PhabricatorController $controller = null) {
+1
-1
src/applications/auth/controller/PhabricatorEmailLoginController.php
+1
-1
src/applications/auth/controller/PhabricatorEmailLoginController.php
+1
-1
src/applications/auth/controller/PhabricatorEmailTokenController.php
+1
-1
src/applications/auth/controller/PhabricatorEmailTokenController.php
···
74
74
unset($unguarded);
75
75
76
76
$next = '/';
77
-
if (!PhabricatorEnv::getEnvConfig('auth.password-auth-enabled')) {
77
+
if (!PhabricatorAuthProviderPassword::getPasswordProvider()) {
78
78
$next = '/settings/panel/external/';
79
79
} else if (PhabricatorEnv::getEnvConfig('account.editable')) {
80
80
$next = (string)id(new PhutilURI('/settings/panel/password/'))
+6
src/applications/auth/controller/config/PhabricatorAuthEditController.php
+6
src/applications/auth/controller/config/PhabricatorAuthEditController.php
···
224
224
->addCancelButton($cancel_uri)
225
225
->setValue($button));
226
226
227
+
$help = $provider->getConfigurationHelp();
228
+
if ($help) {
229
+
$form->appendChild(id(new PHUIFormDividerControl()));
230
+
$form->appendRemarkupInstructions($help);
231
+
}
232
+
227
233
$crumbs = $this->buildApplicationCrumbs();
228
234
$crumbs->addCrumb(
229
235
id(new PhabricatorCrumbView())
+4
src/applications/auth/provider/PhabricatorAuthProvider.php
+4
src/applications/auth/provider/PhabricatorAuthProvider.php
+18
src/applications/auth/provider/PhabricatorAuthProviderOAuthDisqus.php
+18
src/applications/auth/provider/PhabricatorAuthProviderOAuthDisqus.php
···
7
7
return pht('Disqus');
8
8
}
9
9
10
+
public function getConfigurationHelp() {
11
+
$login_uri = $this->getLoginURI();
12
+
13
+
return pht(
14
+
"To configure Disqus OAuth, create a new application here:".
15
+
"\n\n".
16
+
"http://disqus.com/api/applications/".
17
+
"\n\n".
18
+
"Create an application, then adjust these settings:".
19
+
"\n\n".
20
+
" - **Callback URL:** Set this to `%s`".
21
+
"\n\n".
22
+
"After creating an application, copy the **Public Key** and ".
23
+
"**Secret Key** to the fields above (the **Public Key** goes in ".
24
+
"**OAuth App ID**).",
25
+
$login_uri);
26
+
}
27
+
10
28
protected function newOAuthAdapter() {
11
29
return new PhutilAuthAdapterOAuthDisqus();
12
30
}
+19
src/applications/auth/provider/PhabricatorAuthProviderOAuthFacebook.php
+19
src/applications/auth/provider/PhabricatorAuthProviderOAuthFacebook.php
···
9
9
return pht('Facebook');
10
10
}
11
11
12
+
public function getConfigurationHelp() {
13
+
$uri = new PhutilURI(PhabricatorEnv::getProductionURI('/'));
14
+
return pht(
15
+
'To configure Facebook OAuth, create a new Facebook Application here:'.
16
+
"\n\n".
17
+
'https://developers.facebook.com/apps'.
18
+
"\n\n".
19
+
'You should use these settings in your application:'.
20
+
"\n\n".
21
+
" - **Site URL**: Set this to your full domain with protocol. For ".
22
+
" this Phabricator install, the correct value is: `%s`\n".
23
+
" - **Site Domain**: Set this to the full domain without a protocol. ".
24
+
" For this Phabricator install, the correct value is: `%s`\n\n".
25
+
"After creating your new application, copy the **App ID** and ".
26
+
"**App Secret** to the fields above.",
27
+
(string)$uri,
28
+
$uri->getDomain());
29
+
}
30
+
12
31
public function getDefaultProviderConfig() {
13
32
return parent::getDefaultProviderConfig()
14
33
->setProperty(self::KEY_REQUIRE_SECURE, 1);
+21
src/applications/auth/provider/PhabricatorAuthProviderOAuthGitHub.php
+21
src/applications/auth/provider/PhabricatorAuthProviderOAuthGitHub.php
···
7
7
return pht('GitHub');
8
8
}
9
9
10
+
public function getConfigurationHelp() {
11
+
$uri = PhabricatorEnv::getProductionURI('/');
12
+
$callback_uri = $this->getLoginURI();
13
+
14
+
return pht(
15
+
"To configure GitHub OAuth, create a new GitHub Application here:".
16
+
"\n\n".
17
+
"https://github.com/settings/applications/new".
18
+
"\n\n".
19
+
"You should use these settings in your application:".
20
+
"\n\n".
21
+
" - **URL:** Set this to your full domain with protocol. For this ".
22
+
" Phabricator install, the correct value is: `%s`\n".
23
+
" - **Callback URL**: Set this to: `%s`\n".
24
+
"\n\n".
25
+
"Once you've created an application, copy the **Client ID** and ".
26
+
"**Client Secret** into the fields above.",
27
+
$uri,
28
+
$callback_uri);
29
+
}
30
+
10
31
protected function newOAuthAdapter() {
11
32
return new PhutilAuthAdapterOAuthGitHub();
12
33
}
+21
src/applications/auth/provider/PhabricatorAuthProviderOAuthGoogle.php
+21
src/applications/auth/provider/PhabricatorAuthProviderOAuthGoogle.php
···
7
7
return pht('Google');
8
8
}
9
9
10
+
public function getConfigurationHelp() {
11
+
$login_uri = $this->getLoginURI();
12
+
13
+
return pht(
14
+
"To configure Google OAuth, create a new 'API Project' here:".
15
+
"\n\n".
16
+
"https://code.google.com/apis/console/".
17
+
"\n\n".
18
+
"You don't need to enable any Services, just go to **API Access**, ".
19
+
"click **Create an OAuth 2.0 client ID...**, and configure these ".
20
+
"settings:".
21
+
"\n\n".
22
+
" - During initial setup click **More Options** (or after creating ".
23
+
" the client ID, click **Edit Settings...**), then add this to ".
24
+
" **Authorized Redirect URIs**: `%s`\n".
25
+
"\n\n".
26
+
"After completing configuration, copy the **Client ID** and ".
27
+
"**Client Secret** to the fields above.",
28
+
$login_uri);
29
+
}
30
+
10
31
protected function newOAuthAdapter() {
11
32
return new PhutilAuthAdapterOAuthGoogle();
12
33
}
+18
src/applications/auth/provider/PhabricatorAuthProviderPassword.php
+18
src/applications/auth/provider/PhabricatorAuthProviderPassword.php
···
9
9
return pht('Username/Password');
10
10
}
11
11
12
+
public function getConfigurationHelp() {
13
+
return pht(
14
+
'You can select a minimum password length by setting '.
15
+
'`account.minimum-password-length` in configuration.');
16
+
}
17
+
12
18
public function getDescriptionForCreate() {
13
19
return pht(
14
20
'Allow users to login or register using a username and password.');
···
225
231
public function willRegisterAccount(PhabricatorExternalAccount $account) {
226
232
parent::willRegisterAccount($account);
227
233
$account->setAccountID($account->getUserPHID());
234
+
}
235
+
236
+
public static function getPasswordProvider() {
237
+
$providers = self::getAllEnabledProviders();
238
+
239
+
foreach ($providers as $provider) {
240
+
if ($provider instanceof PhabricatorAuthProviderPassword) {
241
+
return $provider;
242
+
}
243
+
}
244
+
245
+
return null;
228
246
}
229
247
230
248
}
+1
-1
src/applications/base/controller/PhabricatorController.php
+1
-1
src/applications/base/controller/PhabricatorController.php
···
101
101
102
102
if ($this->shouldRequireLogin() && !$user->getPHID()) {
103
103
$login_controller = new PhabricatorAuthStartController($request);
104
-
$login_controller->setCurrentApplication(
104
+
$this->setCurrentApplication(
105
105
PhabricatorApplication::getByClass('PhabricatorApplicationAuth'));
106
106
return $this->delegateToController($login_controller);
107
107
}
-13
src/applications/config/option/PhabricatorAuthenticationConfigOptions.php
-13
src/applications/config/option/PhabricatorAuthenticationConfigOptions.php
···
13
13
14
14
public function getOptions() {
15
15
return array(
16
-
$this->newOption(
17
-
'auth.password-auth-enabled', 'bool', true)
18
-
->setBoolOptions(
19
-
array(
20
-
pht("Allow password authentication"),
21
-
pht("Don't allow password authentication")
22
-
))
23
-
->setSummary(pht("Enables password-based authentication."))
24
-
->setDescription(
25
-
pht(
26
-
"Can users login with a username/password, or by following the ".
27
-
"link from a password reset email? You can disable this and ".
28
-
"configure one or more OAuth providers instead.")),
29
16
$this->newOption('auth.sessions.web', 'int', 5)
30
17
->setSummary(
31
18
pht("Number of web sessions a user can have simultaneously."))
-6
src/applications/config/option/PhabricatorExtendingPhabricatorConfigOptions.php
-6
src/applications/config/option/PhabricatorExtendingPhabricatorConfigOptions.php
···
47
47
->setBaseClass('AphrontApplicationConfiguration')
48
48
// TODO: This could probably use some better documentation.
49
49
->setDescription(pht("Application configuration class.")),
50
-
$this->newOption(
51
-
'controller.oauth-registration',
52
-
'class',
53
-
'PhabricatorOAuthDefaultRegistrationController')
54
-
->setBaseClass('PhabricatorOAuthRegistrationController')
55
-
->setDescription(pht("OAuth registration controller.")),
56
50
);
57
51
}
58
52
+1
-1
src/applications/people/storage/PhabricatorUser.php
+1
-1
src/applications/people/storage/PhabricatorUser.php
···
612
612
$new_username = $this->getUserName();
613
613
614
614
$password_instructions = null;
615
-
if (PhabricatorEnv::getEnvConfig('auth.password-auth-enabled')) {
615
+
if (PhabricatorAuthProviderPassword::getPasswordProvider()) {
616
616
$uri = $this->getEmailLoginURI();
617
617
$password_instructions = <<<EOTXT
618
618
If you use a password to login, you'll need to reset it before you can login
+1
-1
src/applications/settings/panel/PhabricatorSettingsPanelPassword.php
+1
-1
src/applications/settings/panel/PhabricatorSettingsPanelPassword.php
+5
-2
src/docs/configuration/configuration_guide.diviner
+5
-2
src/docs/configuration/configuration_guide.diviner
···
150
150
continue setup. The rest of this document contains additional instructions for
151
151
specific setup steps.
152
152
153
-
When you see the login screen, continue with @{article:Configuring Accounts and
154
-
Registration}.
153
+
When you resolve any issues and see the welcome screen, enter credentials to
154
+
create your initial administrator account. After you log in, you'll want to
155
+
configure how other users will be able to log in or register -- until you do,
156
+
no one else will be able to sign up or log in. For more information, see
157
+
@{article:Configuring Accounts and Registration}.
155
158
156
159
= Storage: Configuring MySQL =
157
160
+38
-123
src/docs/configuration/configuring_accounts_and_registration.diviner
+38
-123
src/docs/configuration/configuring_accounts_and_registration.diviner
···
5
5
6
6
= Overview =
7
7
8
-
Phabricator supports a number of login systems, like traditional
9
-
username/password, Facebook OAuth, GitHub OAuth, and Google OAuth. You can
10
-
enable or disable these systems to configure who can register for and access
11
-
your install, and how users with existing accounts can login.
8
+
Phabricator supports a number of login systems. You can enable or disable these
9
+
systems to configure who can register for and access your install, and how users
10
+
with existing accounts can login.
11
+
12
+
Methods of logging in are called **Authentication Providers**. For example,
13
+
there is a "Username/Password" authentication provider available, which allows
14
+
users to log in with a traditional username and password. Other providers
15
+
support logging in with other credentials. For example:
12
16
13
-
By default, only username/password auth is enabled, and there are no valid
14
-
accounts. Start by creating a new account with the
15
-
##phabricator/bin/accountadmin## script.
17
+
- **Username/Password:** Users use a username and password to log in or
18
+
register.
19
+
- **LDAP:** Users use LDAP credentials to log in or register.
20
+
- **OAuth:** Users use accounts on a supported OAuth2 provider (like
21
+
GitHub, Facebook, or Google) to log in or register.
22
+
- **Other Providers:** More providers are available, and Phabricator
23
+
can be extended with custom providers. See the "Auth" application for
24
+
a list of available providers.
16
25
17
-
= Using accountadmin =
26
+
By default, no providers are enabled. You must use the "Auth" application to
27
+
add one or more providers after you complete the installation process.
18
28
19
-
##accountadmin## is a user-friendly command line interface for creating and
20
-
editing accounts. To use ##accountadmin##, just run the script:
29
+
After you add a provider, you can link it to existing accounts (for example,
30
+
associate an existing Phabricator account with a GitHub OAuth account) or users
31
+
can use it to register new accounts (assuming you enable these options).
21
32
22
-
$ ./phabricator/bin/accountadmin
23
-
Enter a username to create a new account or edit an existing account.
33
+
= Recovering Administrator Accounts =
24
34
25
-
Enter a username:
35
+
If you accidentally lock yourself out of Phabricator, you can use the `bin/auth`
36
+
script to recover access to an administrator account. To recover access, run:
26
37
27
-
This will walk you through the process of creating an initial user account.
28
-
Once you've created an account, you can login with it and use the web console
29
-
to create and manage accounts more easily (provided you make your first account
30
-
an administrator).
38
+
phabricator/ $ ./bin/auth recover <username>
31
39
32
-
You can use this script later to create or edit accounts if you, for example,
33
-
accidentally remove your admin flag.
40
+
...where `<username>` is the admin account username you want to recover access
41
+
to. This will give you a link which will log you in as the specified
42
+
administrative user.
34
43
35
44
= Managing Accounts with the Web Console =
36
45
···
38
47
##/people/## or click "People" on the homepage. Provided you're an admin,
39
48
you'll see options to create or edit accounts.
40
49
41
-
= Managing Accounts from the Command Line =
42
-
43
-
You can use ##scripts/user/add_user.php## to batch create accounts. Run it
44
-
like:
45
-
46
-
$ ./add_user.php <username> <email> <realname> <admin>
47
-
48
-
For example:
49
-
50
-
$ ./add_user.php alincoln alincoln@logcabin.com 'Abraham Lincoln' tjefferson
51
-
52
-
This will create a new ##alincoln## user and send them a "Welcome to
53
-
Phabricator" email from ##tjefferson## with instructions on how to log in and
54
-
set a password.
55
-
56
-
= Configuring Facebook OAuth =
57
-
58
-
You can configure Facebook OAuth to allow login, login and registration, or
59
-
nothing (the default). If registration is not allowed, users must have an
60
-
existing account in order to link a Facebook account to it, but can use
61
-
Facebook to login once the accounts are linked.
50
+
= Manually Creating New Accounts =
62
51
63
-
To configure Facebook OAuth, create a new Facebook Application:
52
+
There are two ways to manually create new accounts: via the web UI using
53
+
the "People" application (this is easiest), or via the CLI using the
54
+
`accountadmin` binary (this has a few more options).
64
55
65
-
https://developers.facebook.com/apps
56
+
To use the CLI script, run:
66
57
67
-
You should set these things in your application:
58
+
phabricator/ $ ./bin/accountadmin
68
59
69
-
- **Site URL**: Set this to your full domain with protocol, like
70
-
"##https://phabricator.example.com/##".
71
-
- **Site Domain**: Set this to the entire domain, like ##example.com##. You
72
-
might be able to get away with including the subdomain if you want to
73
-
scope more tightly.
74
-
75
-
Once that is set up, edit your Phabricator configuration and set these keys:
76
-
77
-
- **facebook.auth-enabled**: set this to ##true##.
78
-
- **facebook.application-id**: set to your Facebook application's ID. Make
79
-
sure you set this as a string.
80
-
- **facebook.application-secret**: set to your Facebook application's
81
-
secret key.
82
-
- **facebook.registration-enabled**: set this to ##true## to let users
83
-
register for your install with a Facebook account (this is a very open
84
-
setting) or ##false## to prevent users from registering with Facebook.
85
-
- **facebook.auth-permanent**: you can set this to prevent account unlinking.
86
-
It is unlikely you want to prevent it, but Facebook's internal install uses
87
-
this option since Facebook uses Facebook as its only auth mechanism.
88
-
89
-
= Configuring GitHub OAuth =
90
-
91
-
You can configure GitHub OAuth to allow login, login and registration, or
92
-
nothing (the default).
93
-
94
-
To configure GitHub OAuth, create a new GitHub Application:
95
-
96
-
https://github.com/settings/applications/new
97
-
98
-
You should set these things in your application:
99
-
100
-
- **URL**: Set this to the full domain with protocol, like
101
-
"##https://phabricator.example.com/##".
102
-
- **Callback URL**: Set this to your domain plus "##/oauth/github/login/##",
103
-
like "##https://phabricator.example.com/oauth/github/login/##".
104
-
105
-
Once you've created an application, edit your Phabricator configuration and
106
-
set these keys:
107
-
108
-
- **github.auth-enabled**: set this to ##true##.
109
-
- **github.application-id**: set this to your application/client ID.
110
-
- **github.application-secret**: set this to your application secret.
111
-
- **github.registration-enabled**: set to ##true## to let users register with
112
-
just GitHub credentials (this is a very open setting) or ##false## to
113
-
prevent users from registering. If set to ##false##, users may still link
114
-
existing accounts and use GitHub to login, they just can't create new
115
-
accounts.
116
-
- **github.auth-permanent**: set to ##true## to prevent unlinking Phabricator
117
-
accounts from GitHub accounts.
118
-
119
-
= Configuring Google OAuth =
120
-
121
-
You can configure Google OAuth to allow login, login and registration, or
122
-
nothing (the default).
123
-
124
-
To configure Google OAuth, create a new Google "API Project":
125
-
126
-
https://code.google.com/apis/console/
127
-
128
-
You don't need to enable any **Services**, just go to **API Access**, click
129
-
**"Create an OAuth 2.0 client ID..."**, and configure these settings:
130
-
131
-
- Click **More Options** next to **Authorized Redirect APIs** and add the
132
-
full domain (with protocol) plus ##/oauth/google/login/## to the list.
133
-
For example, ##https://phabricator.example.com/oauth/google/login/##
134
-
- Click **Create Client ID**.
135
-
136
-
Once you've created a client ID, edit your Phabricator configuration and set
137
-
these keys:
138
-
139
-
- **google.auth-enabled**: set this to ##true##.
140
-
- **google.application-id**: set this to your Client ID (from above).
141
-
- **google.application-secret**: set this to your Client Secret (from above).
142
-
- **google.registration-enabled**: set this to ##true## to let users register
143
-
with just Google credentials (this is a very open setting) or ##false## to
144
-
prevent users from registering. If set to ##false##, users may still link
145
-
existing accounts and use Google to login, they jus can't create new
146
-
accounts.
147
-
- **google.auth-permanent**: set this to ##true## to prevent unlinking
148
-
Phabricator accounts from Google accounts.
60
+
Some options (like setting passwords and changing certain account flags) are
61
+
only available from the CLI. You can also use this script to make a user
62
+
an administrator (if you accidentally remove your admin flag) or create an
63
+
administrative account.
149
64
150
65
= Next Steps =
151
66