|
| 1 | +--- |
| 2 | +kind: change |
| 3 | +title: "An integrator's guide to organization application policies" |
| 4 | +created_at: 2015-01-19 |
| 5 | +author_name: pengwynn |
| 6 | +--- |
| 7 | + |
| 8 | +As we [announced over on the GitHub blog][ann], organization admins can now |
| 9 | +control how third-party applications access their organization data. Allowing |
| 10 | +admins to approve or deny applications will ultimately result in deeper trust |
| 11 | +and increase overall adoption of integrations within organizations on GitHub. |
| 12 | + |
| 13 | +As an integrator, here's what you need to know about organization application |
| 14 | +policies and how this feature could impact your application. |
| 15 | + |
| 16 | +### Guiding principles |
| 17 | + |
| 18 | +We've tried to strike the right balance between organization privacy and the |
| 19 | +user experience for integrators and end users. Organizations should be able to |
| 20 | +prevent applications they do not trust from accessing their organization data |
| 21 | +without creating a multitude of new edge cases for integrators. |
| 22 | + |
| 23 | +With that goal in mind, the feature works this way: **if an organization's |
| 24 | +application policy prevents an application from accessing its resources, the |
| 25 | +API behaves as if the authenticating user is not a member of the |
| 26 | +organization**. Specifically, this means an application authenticating on |
| 27 | +behalf of a user using OAuth will have: |
| 28 | + |
| 29 | +- **Read-only access to public resources.** Organization-owned public |
| 30 | + repositories, issues, and other resources will be visible via the API and |
| 31 | + show up in resource listings, but mutating methods (`POST`, `PATCH`, `PUT`, |
| 32 | + and `DELETE`) will return status `403`. |
| 33 | +- **No access to private resources.** Organization-owned private repositories, |
| 34 | + issues, and other resources will not be visible via the API and will not |
| 35 | + show up in resource [listings][] that co-mingle public and private |
| 36 | + resources. Hooks for these private repositories are muted and will not be |
| 37 | + delivered as long as the application is restricted. |
| 38 | + |
| 39 | +Since applications should already handle the scenario where a user loses access |
| 40 | +to organization resources, this reduces the work integrators need to do. |
| 41 | + |
| 42 | +### Checking organization access |
| 43 | + |
| 44 | +As organization admins adopt application whitelists and restrict third-party |
| 45 | +application access to organization resources, your application may lose access |
| 46 | +to those resources. If an organization member is not aware of the new access |
| 47 | +policy, they may wonder why their private repositories or other resources no |
| 48 | +longer work or show up in your application. |
| 49 | + |
| 50 | +There are a couple of ways to help troubleshoot access for your end users. |
| 51 | + |
| 52 | +- **Via the GitHub UI.** The simplest way to help end users understand how |
| 53 | + organization access policies affect their access to your application is to |
| 54 | + provide a link to their authorization details under their GitHub account |
| 55 | + settings as [described in the OAuth documentation][auth-link]. |
| 56 | + |
| 57 | +- **Via the API.** For an even better user experience, [use the |
| 58 | + API][discovering-guide] to list which user organizations your application |
| 59 | + can access, and provide users with the link mentioned above to request |
| 60 | + access from their organization admins. |
| 61 | + |
| 62 | +### Listing accessible organization resources |
| 63 | + |
| 64 | +In addition to checking access to a user's organizations, you'll want to ensure |
| 65 | +you're discovering their accessible resources in the most efficient way. Recent |
| 66 | +changes to the [Respositories API][listing-repos] might reduce the API calls |
| 67 | +your application needs to make to find a user's repositories across all of |
| 68 | +their organization mememberships. |
| 69 | + |
| 70 | +### Ensuring uninterrupted SSH access |
| 71 | + |
| 72 | +Since many applications access organization-owned repositories via SSH keys, |
| 73 | +organziation application policies apply to those as well. Keys created by OAuth |
| 74 | +applications (or those created before GitHub started tracking that information) |
| 75 | +will not have access to repositories owned by organizations that restrict |
| 76 | +third-party applications. If your application uses keys **created before |
| 77 | +February 24, 2014**, you [should replace those older keys][keys] to ensure |
| 78 | +things keep running smoothly for your application. |
| 79 | + |
| 80 | +### We're here to help |
| 81 | + |
| 82 | +This is a big feature, and we're sure it will impact many of our integrators as |
| 83 | +organizations adopt application whitelists. We also think it provides a huge |
| 84 | +net benefit for integrators as organizations choose to use OAuth integrations |
| 85 | +with more confidence. |
| 86 | + |
| 87 | +If you have any questions or feedback, please [get in touch][contact]. |
| 88 | + |
| 89 | +[ann]: https://github.com/blog |
| 90 | +[auth-link]: /v3/oauth/#directing-users-to-review-their-access-for-an-application |
| 91 | +[list-orgs]: /v3/orgs/#list-your-organizations |
| 92 | +[contact]: https://github.com/contact?form[subject]=Organization+Access+Policies+help+for+integrators |
| 93 | +[listing-repos]: /v3/repos/#list-your-repositories |
| 94 | +[discovering-guide]: /guides/discovering-resources-for-a-user/ |
| 95 | +[keys]: /changes/2014-12-12-replace-older-ssh-keys-created-by-your-application/ |
| 96 | +[listings]: /v3/issues/#list-issues |
0 commit comments