jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-22 03:16:52 -05:00
Code Issues Projects Releases Wiki Activity
Files
fe812048a4a80550ba5c4b51da6048aa13d83cff
docs/content/developers/apps/identifying-and-authorizing-users-for-github-apps.md
Felicity Chapman 0f100dabe9 Fix broken links in report #2697 (#15921)
2020-10-13 10:02:08 +01:00

52 KiB
Raw Blame History

title, intro, redirect_from, versions
title intro redirect_from versions
Identifying and authorizing users for GitHub Apps {% data reusables.shortdesc.identifying_and_authorizing_github_apps %}
/early-access/integrations/user-identification-authorization/
/apps/building-integrations/setting-up-and-registering-github-apps/identifying-users-for-github-apps/
/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps
free-pro-team enterprise-server
* *

{% data reusables.pre-release-program.expiring-user-access-tokens-beta %}

When your GitHub App acts on behalf of a user, it performs user-to-server requests. These requests must be authorized with a user's access token. User-to-server requests include requesting data for a user, like determining which repositories to display to a particular user. These requests also include actions triggered by a user, like running a build.

{% data reusables.apps.expiring_user_authorization_tokens %}

Identifying users on your site

To authorize users for standard apps that run in the browser, use the web application flow.

{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" %} To authorize users for headless apps without direct access to the browser, such as CLI tools or Git credential managers, use the device flow. The device flow uses the OAuth 2.0 Device Authorization Grant. {% endif %}

Web application flow

Using the web application flow, the process to identify users on your site is:

  1. Users are redirected to request their GitHub identity
  2. Users are redirected back to your site by GitHub
  3. Your GitHub App accesses the API with the user's access token

If you select Request user authorization (OAuth) during installation when creating or modifying your app, step 1 will be completed during app installation. For more information, see "Authorizing users during installation."

1. Request a user's GitHub identity

GET {% data variables.product.oauth_host_code %}/login/oauth/authorize

When your GitHub App specifies a login parameter, it prompts users with a specific account they can use for signing in and authorizing your app.

Parameters
Name Type Description
client_id string Required. The client ID for your GitHub App. You can find this in your GitHub App settings when you select your app.
redirect_uri string The URL in your application where users will be sent after authorization. This must be an exact match to the URL you provided in the User authorization callback URL field when setting up your GitHub App and can't contain any additional parameters.
state string This should contain a random string to protect against forgery attacks and could contain any other arbitrary data.
login string Suggests a specific account to use for signing in and authorizing the app.

{% note %}

Note: You don't need to provide scopes in your authorization request. Unlike traditional OAuth, the authorization token is limited to the permissions associated with your GitHub App and those of the user.

{% endnote %}

2. Users are redirected back to your site by GitHub

If the user accepts your request, GitHub redirects back to your site with a temporary code in a code parameter as well as the state you provided in the previous step in a state parameter. If the states don't match, the request was created by a third party and the process should be aborted.

{% note %}

Note: If you select Request user authorization (OAuth) during installation when creating or modifying your app, GitHub returns a temporary code that you will need to exchange for an access token. The state parameter is not returned when GitHub initiates the OAuth flow during app installation.

{% endnote %}

Exchange this code for an access token. {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" %} When expiring tokens are enabled, the access token expires in 8 hours and the refresh token expires in 6 months. Every time you refresh the token, you get a new refresh token. For more information, see "Refreshing user-to-server access tokens."

Expiring user tokens are currently part of the user-to-server token expiration beta and subject to change. To opt-in to the user-to-server token expiration beta feature, see "Activating beta features for apps."{% endif %}

POST {% data variables.product.oauth_host_code %}/login/oauth/access_token
Parameters
Name Type Description
client_id string Required. The client ID for your GitHub App.
client_secret string Required. The client secret for your GitHub App.
code string Required. The code you received as a response to Step 1.
redirect_uri string The URL in your application where users are sent after authorization.
state string The unguessable random string you provided in Step 1.
Response

{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" %}

By default, the response takes the following form. The response parameters expires_in, refresh_token, and refresh_token_expires_in are only returned when you enable the beta for expiring user-to-server access tokens.

{
  "access_token": "e72e16c7e42f292c6912e7710c838347ae178b4a",
  "expires_in": "28800",
  "refresh_token": "r1.c1b4a2e77838347a7e420ce178f2e7c6912e1692",
  "refresh_token_expires_in": "15811200",
  "scope": "",
  "token_type": "bearer"
}

{% else %}

By default, the response takes the following form:

access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&token_type=bearer

{% endif %}

3. Your GitHub App accesses the API with the user's access token

The user's access token allows the GitHub App to make requests to the API on behalf of a user.

Authorization: token OAUTH-TOKEN
GET {% data variables.product.api_url_code %}/user

For example, in curl you can set the Authorization header like this:

curl -H "Authorization: token OAUTH-TOKEN" {% data variables.product.api_url_pre %}/user

{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" %}

Device flow

{% note %}

Note: The device flow is in public beta and subject to change.{% if currentVersion == "free-pro-team@latest" %} To enable this beta feature, see "Activating beta features for apps."{% endif %}

{% endnote %}

The device flow allows you to authorize users for a headless app, such as a CLI tool or Git credential manager.

For more information about authorizing users using the device flow, see "Authorizing OAuth Apps".

{% endif %}

Check which installation's resources a user can access

{% if currentVersion != "free-pro-team@latest" and currentVersion ver_lt "enterprise-server@2.22" %} {% data reusables.pre-release-program.machine-man-preview %} {% data reusables.pre-release-program.api-preview-warning %} {% endif %}

Once you have an OAuth token for a user, you can check which installations that user can access.

Authorization: token OAUTH-TOKEN
GET /user/installations

You can also check which repositories are accessible to a user for an installation.

Authorization: token OAUTH-TOKEN
GET /user/installations/:installation_id/repositories

More details can be found in: List app installations accessible to the user access token and List repositories accessible to the user access token.

Handling a revoked GitHub App authorization

If a user revokes their authorization of a GitHub App, the app will receive the github_app_authorization webhook by default. GitHub Apps cannot unsubscribe from this event. {% data reusables.webhooks.authorization_event %}

User-level permissions

You can add user-level permissions to your GitHub App to access user resources, such as user emails, that are granted by individual users as part of the user authorization flow. User-level permissions differ from repository and organization-level permissions, which are granted at the time of installation on an organization or user account.

You can select user-level permissions from within your GitHub App's settings in the User permissions section of the Permissions & webhooks page. For more information on selecting permissions, see "Editing a GitHub App's permissions."

When a user installs your app on their account, the installation prompt will list the user-level permissions your app is requesting and explain that the app can ask individual users for these permissions.

Because user-level permissions are granted on an individual user basis, you can add them to your existing app without prompting users to upgrade. You will, however, need to send existing users through the user authorization flow to authorize the new permission and get a new user-to-server token for these requests.

User-to-server requests

While most of your API interaction should occur using your server-to-server installation access tokens, certain endpoints allow you to perform actions via the API using a user access token. Your app can make the following requests using GraphQL v4 or REST v3 endpoints.

Supported endpoints

{% if currentVersion == "free-pro-team@latest" %}

Actions Runners
Actions Secrets

{% if currentVersion == "free-pro-team@latest" %}

Artifacts
Check Runs
Check Suites
Codes Of Conduct
Deployment Statuses
Deployments
Events
Feeds
Git Blobs
Git Commits
Git Refs
Git Tags
Git Trees
Gitignore Templates
Installations

{% if currentVersion == "free-pro-team@latest" %}

Interaction Limits
Issue Assignees
Issue Comments
Issue Events
Issue Timeline
Issues

{% if currentVersion == "free-pro-team@latest" %}

Jobs
Labels
Licenses
Markdown
Meta
Milestones
Organization Hooks

{% if currentVersion == "free-pro-team@latest" %}

Organization Invitations
Organization Members
Organization Outside Collaborators

{% if currentVersion != "free-pro-team@latest" %}

Organization Pre Receive Hooks

{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.20" %}

Organization Team Projects
Organization Team Repositories

{% if currentVersion == "free-pro-team@latest" %}

Organization Team Sync
Organization Teams
Organizations

{% if currentVersion == "free-pro-team@latest" %}

Organizations Credential Authorizations

{% if currentVersion == "free-pro-team@latest" %}

Organizations Scim

{% if currentVersion == "free-pro-team@latest" %}

Source Imports
Project Collaborators
Projects
Pull Comments
Pull Request Review Events
Pull Request Review Requests
Pull Request Reviews
Pulls
Reactions

{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.20" %}* Delete a reaction{% else %}* Delete a reaction{% endif %}

Repositories
Repository Activity

{% if currentVersion == "free-pro-team@latest" %}

Repository Automated Security Fixes
Repository Branches
Repository Collaborators
Repository Commit Comments
Repository Commits
Repository Community
Repository Contents

{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.20" %}

Repository Event Dispatches
Repository Hooks
Repository Invitations
Repository Keys
Repository Pages

{% if currentVersion != "free-pro-team@latest" %}

Repository Pre Receive Hooks
Repository Releases
Repository Stats

{% if currentVersion == "free-pro-team@latest" %}

Repository Vulnerability Alerts
Root
Search
Statuses
Team Discussions
Topics

{% if currentVersion == "free-pro-team@latest" %}

Traffic

{% if currentVersion == "free-pro-team@latest" %}

User Blocking
User Emails

{% if currentVersion == "free-pro-team@latest" %}

User Followers
User Gpg Keys
User Public Keys
Users

{% if currentVersion == "free-pro-team@latest" %}

Workflow Runs

{% if currentVersion == "free-pro-team@latest" %}

Workflows
Reference in New Issue View Git Blame Copy Permalink