Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
zulip/docs/subsystems/auth.md

85 lines
3.5 KiB
Markdown
Raw Normal View History

docs: Update headings for development auth documentation. Also, we fix an outdated link from /devtools.
2018-08-21 21:52:28 +02:00
# Authentication in the development environment
This page documents special notes that are useful for configuring
Zulip's various authentication methods for testing in a development
environment.
## Testing OAuth in development
docs: Move docs on testing OAuth to their own page. In some minutes of searching yesterday afternoon on the docs site, I couldn't find docs on how to set up our OAuth integrations for the dev environment -- even though I was pretty sure they should be there somewhere, because I'd just been told that. Wasn't until I considered the problem fresh today, and grepped the docs source instead, that I found them. So, move them to a separate page so they're in the nav.
2017-11-02 21:05:21 +01:00
docs: Reorganize developer docs to improve navigation. This commit helps reduce clutter on the navigation sidebar. Creates new directories and moves relevant files into them. Modifies index.rst, symlinks, and image paths accordingly. This commit also enables expandable/collapsible navigation items, renames files in docs/development and docs/production, modifies /tools/test-documentation so that it overrides a theme setting, Also updates links to other docs, file paths in the codebase that point to developer documents, and files that should be excluded from lint tests. Note that this commit does not update direct links to zulip.readthedocs.io in the codebase; those will be resolved in an upcoming follow-up commit (it'll be easier to verify all the links once this is merged and ReadTheDocs is updated). Fixes #5265.
2017-11-08 17:55:36 +01:00
Among the many [authentication methods](../production/authentication-methods.html)
docs: Move docs on testing OAuth to their own page. In some minutes of searching yesterday afternoon on the docs site, I couldn't find docs on how to set up our OAuth integrations for the dev environment -- even though I was pretty sure they should be there somewhere, because I'd just been told that. Wasn't until I considered the problem fresh today, and grepped the docs source instead, that I found them. So, move them to a separate page so they're in the nav.
2017-11-02 21:05:21 +01:00
we support, a server can be configured to allow users to sign in with
their Google accounts or GitHub accounts, using the OAuth protocol.
Because these authentication methods involve an interaction between
Zulip, an external service, and the user's browser, and particularly
because browsers can (rightly!) be picky about the identity of sites
you interact with, the preferred way to set them up in a development
environment is to set up the real Google and GitHub to process auth
requests for your development environment.
The steps to do this are a variation of the steps documented in
`prod_settings_template.py`. Here are the full procedures for dev:
### Google
docs/oauth: Update for Google UI changes, and for zulipdev.com. The control panel on the Google side doesn't seem to match the instructions we have; it looks pretty 2017 to me, so I imagine it's had a redesign since the instructions were written. Also, in dev, EXTERNAL_HOST is now a port on zulipdev.com, not on localhost. Update these instructions for those developments, and edit lightly. In dev, recommend setting in `dev_settings` instead of in `prod_settings_template`; that feels to me a little more reflective of the actual intent, and the effect should be equivalent.
2017-11-02 21:21:38 +01:00
* Visit https://console.developers.google.com and navigate to "APIs &
services" > "Credentials". Create a "Project" which will correspond
to your dev environment.
docs: Move docs on testing OAuth to their own page. In some minutes of searching yesterday afternoon on the docs site, I couldn't find docs on how to set up our OAuth integrations for the dev environment -- even though I was pretty sure they should be there somewhere, because I'd just been told that. Wasn't until I considered the problem fresh today, and grepped the docs source instead, that I found them. So, move them to a separate page so they're in the nav.
2017-11-02 21:05:21 +01:00
docs/oauth: Update for Google UI changes, and for zulipdev.com. The control panel on the Google side doesn't seem to match the instructions we have; it looks pretty 2017 to me, so I imagine it's had a redesign since the instructions were written. Also, in dev, EXTERNAL_HOST is now a port on zulipdev.com, not on localhost. Update these instructions for those developments, and edit lightly. In dev, recommend setting in `dev_settings` instead of in `prod_settings_template`; that feels to me a little more reflective of the actual intent, and the effect should be equivalent.
2017-11-02 21:21:38 +01:00
* Navigate to "APIs & services" > "Library", and find the "Google+
API". Choose "Enable".
docs: Move docs on testing OAuth to their own page. In some minutes of searching yesterday afternoon on the docs site, I couldn't find docs on how to set up our OAuth integrations for the dev environment -- even though I was pretty sure they should be there somewhere, because I'd just been told that. Wasn't until I considered the problem fresh today, and grepped the docs source instead, that I found them. So, move them to a separate page so they're in the nav.
2017-11-02 21:05:21 +01:00
docs/oauth: Update for Google UI changes, and for zulipdev.com. The control panel on the Google side doesn't seem to match the instructions we have; it looks pretty 2017 to me, so I imagine it's had a redesign since the instructions were written. Also, in dev, EXTERNAL_HOST is now a port on zulipdev.com, not on localhost. Update these instructions for those developments, and edit lightly. In dev, recommend setting in `dev_settings` instead of in `prod_settings_template`; that feels to me a little more reflective of the actual intent, and the effect should be equivalent.
2017-11-02 21:21:38 +01:00
* Return to "Credentials", and select "Create credentials". Choose
"OAuth client ID", and follow prompts to create a consent screen, etc.
For "Authorized redirect URIs", fill in
`https://zulipdev.com:9991/accounts/login/google/done/` .
docs: Move docs on testing OAuth to their own page. In some minutes of searching yesterday afternoon on the docs site, I couldn't find docs on how to set up our OAuth integrations for the dev environment -- even though I was pretty sure they should be there somewhere, because I'd just been told that. Wasn't until I considered the problem fresh today, and grepped the docs source instead, that I found them. So, move them to a separate page so they're in the nav.
2017-11-02 21:05:21 +01:00
docs/oauth: Update for Google UI changes, and for zulipdev.com. The control panel on the Google side doesn't seem to match the instructions we have; it looks pretty 2017 to me, so I imagine it's had a redesign since the instructions were written. Also, in dev, EXTERNAL_HOST is now a port on zulipdev.com, not on localhost. Update these instructions for those developments, and edit lightly. In dev, recommend setting in `dev_settings` instead of in `prod_settings_template`; that feels to me a little more reflective of the actual intent, and the effect should be equivalent.
2017-11-02 21:21:38 +01:00
* You should get a client ID and a client secret. Copy them. In
`dev_settings.py`, set `GOOGLE_OAUTH2_CLIENT_ID` to the client ID,
and in `dev-secrets.conf`, set `google_oauth2_client_secret` to the
client secret.
docs: Move docs on testing OAuth to their own page. In some minutes of searching yesterday afternoon on the docs site, I couldn't find docs on how to set up our OAuth integrations for the dev environment -- even though I was pretty sure they should be there somewhere, because I'd just been told that. Wasn't until I considered the problem fresh today, and grepped the docs source instead, that I found them. So, move them to a separate page so they're in the nav.
2017-11-02 21:05:21 +01:00
### GitHub
* Register an OAuth2 application with GitHub at one of
docs/oauth: Update for Google UI changes, and for zulipdev.com. The control panel on the Google side doesn't seem to match the instructions we have; it looks pretty 2017 to me, so I imagine it's had a redesign since the instructions were written. Also, in dev, EXTERNAL_HOST is now a port on zulipdev.com, not on localhost. Update these instructions for those developments, and edit lightly. In dev, recommend setting in `dev_settings` instead of in `prod_settings_template`; that feels to me a little more reflective of the actual intent, and the effect should be equivalent.
2017-11-02 21:21:38 +01:00
https://github.com/settings/developers or
https://github.com/organizations/ORGNAME/settings/developers.
Specify `http://zulipdev.com:9991/complete/github/` as the callback URL.
docs: Move docs on testing OAuth to their own page. In some minutes of searching yesterday afternoon on the docs site, I couldn't find docs on how to set up our OAuth integrations for the dev environment -- even though I was pretty sure they should be there somewhere, because I'd just been told that. Wasn't until I considered the problem fresh today, and grepped the docs source instead, that I found them. So, move them to a separate page so they're in the nav.
2017-11-02 21:05:21 +01:00
docs/oauth: Update for Google UI changes, and for zulipdev.com. The control panel on the Google side doesn't seem to match the instructions we have; it looks pretty 2017 to me, so I imagine it's had a redesign since the instructions were written. Also, in dev, EXTERNAL_HOST is now a port on zulipdev.com, not on localhost. Update these instructions for those developments, and edit lightly. In dev, recommend setting in `dev_settings` instead of in `prod_settings_template`; that feels to me a little more reflective of the actual intent, and the effect should be equivalent.
2017-11-02 21:21:38 +01:00
* You should get a page with settings for your new application,
showing a client ID and a client secret. In `dev_settings.py`, set
`SOCIAL_AUTH_GITHUB_KEY` to the client ID, and in
`dev-secrets.conf`, set `social_auth_github_secret` to the client secret.
docs: Add fake LDAP auth to subsystems/auth.md. Fixes #10297.
2018-08-18 05:11:19 +02:00
## Testing LDAP in development
Historically, one of the more common classes of bug reports with
Zulip's authentication was users having trouble getting LDAP
authentication working. A big part of the cause was because setting
up a local LDAP server for development was difficult.
We solved this problem for our unit tests long ago by using the
popular [fakeldap](https://github.com/zulip/fakeldap) library. And in
2018, we added convenient support for using fakeldap in the Zulip
development environment as well, so that you can go through all the
actual flows for LDAP configuration.
- To enable fakeldap, set `FAKE_LDAP_MODE` in
`zproject/dev_settings.py` to one of the following options. For more
information on these modes, refer
`zproject/prod_settings_template.py`.:
- `a`: If users' email addresses are in LDAP and used as username.
- `b`: If LDAP only has usernames but email addresses are of the form
username@example.com
- `c`: If LDAP usernames are completely unrelated to email addresses.
- To disable fakeldap, set `FAKE_LDAP_MODE` back to `None`.
- In all fakeldap configurations, users' fake LDAP passwords are equal
to their usernames (e.g. for `ldapuser1@zulip.com`, the password is
`ldapuser1`).
auth: Use different defaults for name and email for fakeldap. Fixes part of #10297. Use FAKE_LDAP_NUM_USERS which specifies the number of LDAP users instead of FAKE_LDAP_EXTRA_USERS which specified the number of extra users.
2018-08-18 02:35:19 +02:00
- `FAKE_LDAP_NUM_USERS` in `zproject/dev_settings.py` can be used to
specify the number of LDAP users to be added. The default value for
the number of LDAP users is 8.