|
| 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 |