docs/oauth-scopes.md

   1 # OAuth Scopes
   2
   3 ## GitLab
   4
   5 You can sign in via GitLab. Your username will have a `_gitlab` suffix. You can track [this issue for getting rid of the suffix and being able to change your username](https://gitlab.com/gitterHQ/webapp/-/issues/1851).
   6
   7 We request following GitLab OAuth scopes:
   8
   9 - `read_user` - to be able to fetch your username, display name, and email for unread email notifications
  10 - `api` - to be able to fetch your groups/projects when you try to create a community/room and decorate issues to show whether they are open/closed
  11
  12 The `api` scope is pretty far reaching and we wish we could just have [`read` access to the API](https://gitlab.com/gitlab-org/gitlab/-/issues/21909). GitLab also does not have a way to [restrict access to certain groups/projects yet](https://gitlab.com/gitlab-org/gitlab/issues/22115).
  13
  14 Ideally, we could have a split OAuth scope and upgrade flow like we have for GitHub. This way users could start out with just `read_user` scope granted. But our code doesn't support upgrade flows for providers other than GitHub at the moment. The other providers are implemented in a generic way with a single token.
  15
  16 You can see how we have the GitLab OAuth application settings configured:
  17
  18 ![](https://i.imgur.com/G9n4LOs.png)
  19
  20
  21 ### Twitter
  22
  23 You can sign in via Twitter. Your username will have a `_twitter` suffix. You can track [this issue for getting rid of the suffix and being able to change your username](https://gitlab.com/gitterHQ/webapp/-/issues/1851).
  24
  25 For Twitter, we are requesting the bare minimum `Read-only` permissions. We add the email permission so we can send unread notification emails. You can see how we have permissions configured in our Twitter developer dashboard:
  26
  27 ![](https://i.imgur.com/RjOO5eu.png)
  28
  29
  30 ## GitHub
  31
  32 For a quick rundown on how to sort out your GitHub OAuth scopes to get your GitHub organization/repo to appear, [see our FAQ section on **"Why isn't my GitHub organisation or repos appearing?"**](./faq.md#why-isnt-my-github-organisation-or-repos-appearing)
  33
  34 For GitHub, we split permissions to initially only include public repo information and user email for unread notification emails. This falls under the `Gitter Public Repo Access` OAuth application.
  35
  36 For the private repos, it's a separate scope (`Gitter Private Repo Access`) you can optionally [grant after the fact](#grant-private-repo-access). The only time we ever "write" to a private repo is to add a webhook integration. We will never ever modify your code. Ever. Just like you, we're developers and entirely respect the privacy of your code.
  37
  38 GitHub is also nice and allows you to choose on a per-org basis what you want to share ([organization access control](https://help.github.com/en/github/setting-up-and-managing-organizations-and-teams/approving-oauth-apps-for-your-organization)).
  39
  40
  41 **Gitter Public Repo Access**:
  42
  43 For a [description of these scopes see the GitHub docs](https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/):
  44
  45  - `user:email`
  46  - `read:org`
  47
  48 **Gitter Private Repo Access**:
  49
  50 For a [description of these scopes see the GitHub docs](https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/):
  51
  52  - `repo`
  53  - `user:email`
  54  - `read:org`
  55
  56
  57 ### Grant Private Repo Access
  58
  59 If you don't see **Gitter Private Repo Access** listed in your [personal application settings](https://github.com/settings/applications), you can start the process in Gitter via the user dropdown menu in the top-right.
  60
  61 ![](https://i.imgur.com/hn4dRO1.png)
  62
  63 You can also use this link which will redirect you to add the private repo permission: https://gitter.im/login/upgrade?scopes=repo
  64
  65
  66 ### Organisation Access Control
  67
  68 GitHub introduced [organization-approved applications](https://blog.github.com/2015-01-19-organization-approved-applications/) which significantly changes how organisations interact with the API. This new feature means that organisations can block OAuth Applications and access needs to be requested/enabled. If you don't want Gitter to have access to a particular organisation for whatever reason, please ensure this is turned on or revoke Gitter's access to this organisation. You need to have admin access to the org in order to do this.
  69
  70 ---
  71
  72 We normally request organisation access during sign-up so existing users creating/joining new organisations will run into a few snags.
  73
  74 There are one of two things you can do:
  75
  76 **Disable the setting**. If you visit `https://github.com/organizations/YOURORG/settings/oauth_application_policy` you can disable the restriction from this page.
  77
  78 **Manually grant access**
  79
  80 Visit your [personal application settings](https://github.com/settings/applications) and find any Gitter applications there, click on the name of the application and you should see the list of organisations that allow access to the application and you can grant access here.
  81
  82 Please note that if you enable Gitter for access to private repositories, you will need to do this for the "Gitter Private Repo Access" application as well. If you don't see "Gitter Private Repo Access" listed in your personal application settings, see the ["Private Repositories"](#private-repositories) section above.
  83
  84 ![](https://i.imgur.com/9GtNmUP.png)
  85
  86 ![](https://i.imgur.com/HpCotUq.png) ![](https://i.imgur.com/Ljlb4nf.png)