Autorización de aplicaciones de OAuth

Nota:

Considera la posibilidad de crear una GitHub App en lugar de una OAuth app.

Tanto las OAuth apps como las GitHub Apps usan OAuth 2.0.

Las GitHub Apps pueden actuar en nombre de un usuario, de forma parecida a una OAuth app, o bien en su propio nombre, lo que resulta ventajoso para las automatizaciones que no requieren que el usuario introduzca datos. Además, las GitHub Apps usan la personalización avanzada de permisos, proporcionan al usuario más control sobre los repositorios a los que puede acceder la aplicación y usan tokens de corta duración. Para más información, consulta Diferencias entre aplicaciones de GitHub y aplicaciones de OAuth y Acerca de la creación de aplicaciones de GitHub.

La implementación OAuth de GitHub admite el tipo de concesión de código de autorización estándar y la concesión de autorización de dispositivos de OAuth 2.0 para aplicaciones que no tienen acceso a un explorador web.

Si quiere omitir la autorización de la aplicación de la manera estándar, como al probar la aplicación, puede usar el flujo de aplicación no web.

Para autorizar tu OAuth app, considera qué flujo de autorización quede mejor para tu aplicación.

        [Flujo de aplicaciones web](#web-application-flow): se usa para autorizar a los usuarios para las OAuth apps estándar que se ejecutan en el explorador. (No se admite el [tipo de concesión implícita](https://tools.ietf.org/html/rfc6749#section-4.2)).

        [flujo de dispositivo](#device-flow): se usa para aplicaciones sin encabezado, como herramientas de la CLI.

Flujo de aplicaciones Web

Nota:

Si va a compilar una aplicación de GitHub, puede seguir usando el flujo de aplicación web de OAuth, pero la configuración tiene algunas diferencias importantes. Para obtener más información, consulta Autenticación con una aplicación de GitHub en nombre de un usuario.

El flujo web de aplicaciones para autorizar a los usuarios en tu app es:

Se redirige a los usuarios para solicitar su identidad de GitHub
Los usuarios son redirigidos de nuevo a tu sitio por GitHub
Tu aplicación accede a la API con el token de acceso del usuario

1. Solicitar la identidad de GitHub de un usuario

GET http(s)://HOSTNAME/login/oauth/authorize

Este punto de conexión toma los siguientes parámetros de entrada.

Parámetro de consulta	Tipo	¿Necesario?	Descripción
`client_id`	`string`	Obligatorio	El id. de cliente que ha recibido de GitHub al registrarse.
`redirect_uri`	`string`	Se recomienda encarecidamente	La URL en tu aplicación a donde se enviará a los usuarios después de la autorización. Vea los detalles siguientes sobre las URL de redireccionamiento.
`login`	`string`	Opcionales	Sugiere una cuenta específica para utilizar para registrarse y autorizar la app.
`scope`	`string`	Dependiente del contexto	Lista de ámbitos delimitada por espacios. Si no se proporciona, de manera predeterminada `scope` será una lista vacía para los usuarios que no han autorizado ningún ámbito para la aplicación. Para los usuarios que han autorizado permisos para la aplicación, no se mostrará al usuario la página de autorización de OAuth con la lista de permisos. En vez de esto, este paso del flujo se completara automáticamente con el conjunto de alcances que el usuario haya autorizado para la aplicación. Por ejemplo, si un usuario ya ha realizado el flujo web dos veces y ha autorizado un token con ámbito `user` y otro con ámbito `repo`, un tercer flujo web que no proporcione un valor `scope` recibirá un token con el ámbito `user` y `repo`.
`state`	`string`	Se recomienda encarecidamente	Una secuencia aleatoria indescifrable. Se utiliza para protegerte contra los ataques de falsificación de solicitudes entre sitios.
`allow_signup`	`string`	Opcionales	Si los usuarios no autenticados se ofrecerán o no una opción para registrarse para GitHub durante el flujo de OAuth. El valor predeterminado es `true`. Use `false` cuando una directiva prohíba los registros.
`prompt`	`string`	Opcionales	Obliga a que el selector de cuentas aparezca si se configura como `select_account`. El selector de cuentas también aparecerá si la aplicación tiene un URI de redirección no HTTP o si el usuario tiene varias cuentas iniciadas.

Los parámetros PKCE (Proof Key for Code Exchange, es decir, Clave de prueba para intercambio de código) code_challenge y code_challenge_method no se admiten en este momento. Actualmente no se admiten las solicitudes anteriores al lanzamiento de CORS (OPCIONES).

2. Los usuarios son redirigidos de nuevo a su sitio por GitHub.

Si el usuario acepta tu solicitud, GitHub le redirige a tu sitio con un valor code temporal en un parámetro de código y con el estado que hayas proporcionado en el paso anterior en un parámetro state. El código temporal caducará después de 10 minutos. Si los estados no coinciden, entonces un tercero creó la solicitud, y debes abortar el proceso.

Intercambie este valor code por un token de acceso:

POST http(s)://HOSTNAME/login/oauth/access_token

Este punto de conexión toma los siguientes parámetros de entrada.

Nombre de parámetro	Tipo	¿Necesario?	Descripción
`client_id`	`string`	Obligatorio	El ID de cliente que has recibido de GitHub para tu aplicación OAuth app.
`client_secret`	`string`	Obligatorio	El secreto de cliente que ha recibido de GitHub para la OAuth app.
`code`	`string`	Obligatorio	Código que ha recibido como respuesta al paso 1.
`redirect_uri`	`string`	Se recomienda encarecidamente	La URL en tu aplicación, hacia la cual se envía a los usuarios después de su autorización. Podemos usar esto para buscar coincidencias con el URI proporcionado originalmente cuando `code` se emitió, para evitar ataques contra el servicio.

Predeterminadamente, la respuesta toma la siguiente forma:

access_token=gho_16C7e42F292c6912E7710c838347Ae178B4a&scope=repo%2Cgist&token_type=bearer

También puede recibir la respuesta en diferentes formatos si proporciona el formato en el encabezado Accept. Por ejemplo, Accept: application/json o Accept: application/xml:

Accept: application/json
{
  "access_token":"gho_16C7e42F292c6912E7710c838347Ae178B4a",
  "scope":"repo,gist",
  "token_type":"bearer"
}

Accept: application/xml
<OAuth>
  <token_type>bearer</token_type>
  <scope>repo,gist</scope>
  <access_token>gho_16C7e42F292c6912E7710c838347Ae178B4a</access_token>
</OAuth>

3. Uso del token de acceso para acceder a la API

El token de acceso te permite hacer solicitudes a la API a nombre de un usuario.

Authorization: Bearer OAUTH-TOKEN
GET http(s)://HOSTNAME/api/v3/user

Por ejemplo, en curl, puedes configurar el encabezado de autorización de la siguiente manera:

curl -H "Authorization: Bearer OAUTH-TOKEN" http(s)://HOSTNAME/api/v3/user

Cada vez que recibas un token de acceso, debes usar el token para volver a validar la identidad del usuario. Un usuario puede cambiar la cuenta en la que están conectados cuando usted los envía para autorizar su aplicación, y corre el riesgo de mezclar datos del usuario si no valida la identidad del usuario después de cada inicio de sesión.

Flujo de dispositivos

El flujo del dispositivo te permite autorizar usuarios para una aplicación sin interfaz gráfica, como una herramienta de línea de comandos o el Administrador de Credenciales de Git.

Antes de que puedas utilizar el flujo de dispositivos para autorizar e identificar usuarios, primero debes habilitarlo en los ajustes de tu app. Para obtener más información sobre cómo habilitar el flujo de dispositivo en la aplicación, consulta Modificación de un registro de aplicación de GitHub para GitHub Apps y Modificación de una aplicación de OAuth para OAuth apps.

Resumen del flujo de dispositivos

Tu app solicita los códigos de verificación de dispositivo y de usuario y obtiene la URL de autorización donde el usuario deberá ingresar su código de verificación.
La app pide al usuario ingresar un código de verificación de usuario en http(s)://HOSTNAME/login/device.
La app sondea el estado de autenticación del usuario. Una vez que el usuario haya autorizado el dispositivo, la app podrá hacer llamadas a la API con un token de acceso nuevo.

Paso 1: La aplicación solicita los códigos de verificación del dispositivo y del usuario de GitHub

POST http(s)://HOSTNAME/login/device/code

Tu app debe solicitar un código de verificación de usuario y una URL de verificación que la app utilizará para indicar al usuario que se autentique en el siguiente paso. Esta solicitud también devuelve un código de verificación de dispositivo que debe utilizar la app para recibir un token de acceso y verificar así el estado de la autenticación del usuario.

El punto de conexión toma los siguientes parámetros de entrada.

Nombre de parámetro	Tipo	Descripción
`client_id`	`string`

          **Obligatorio.** El id. de cliente que has recibido de GitHub para la aplicación.

scope | string | Lista delimitada por espacios de los ámbitos a los que la aplicación solicita acceso. Para más información, consulta Ámbitos para las aplicaciones de OAuth.

Predeterminadamente, la respuesta toma la siguiente forma:

device_code=3584d83530557fdd1f46af8289938c8ef79f9dc5&expires_in=900&interval=5&user_code=WDJB-MJHT&verification_uri=https%3A%2F%2FHOSTNAME%2Flogin%2Fdevice

Nombre de parámetro	Tipo	Descripción
`device_code`	`string`	El código de verificación de dispositivo es de 40 caracteres y se utiliza para verificar dicho dispositivo.
`user_code`	`string`	El código de verificación de usuario se muestra en el dispositivo para que el usuario pueda ingresar dicho código en un buscador. El código es de 8 caracteres con un guión medio a la mitad.
`verification_uri`	`string`	URL de verificación en la que los usuarios deben escribir el valor `user_code`: `http(s)://HOSTNAME/login/device`.
`expires_in`	`integer`	Número de segundos antes de que `device_code` y `user_code` expiren. La cantidad predeterminada es de 900 segundos o 15 minutos.
`interval`	`integer`	Número mínimo de segundos que deben pasar antes de poder realizar una nueva solicitud de token de acceso (`POST http(s)://HOSTNAME/login/oauth/access_token`) para completar la autorización del dispositivo. Por ejemplo, si el intervalo es 5, entonces no puedes hacer una solicitud nueva hasta que hayan transcurrido 5 segudos. Si realiza más de una solicitud en estos 5 segundos, alcanzará el límite de frecuenta y se producirá un error `slow_down`.

También puede recibir la respuesta en diferentes formatos si proporciona el formato en el encabezado Accept. Por ejemplo, Accept: application/json o Accept: application/xml:

Accept: application/json
{
  "device_code": "3584d83530557fdd1f46af8289938c8ef79f9dc5",
  "user_code": "WDJB-MJHT",
  "verification_uri": "http(s)://HOSTNAME/login/device",
  "expires_in": 900,
  "interval": 5
}

Accept: application/xml
<OAuth>
  <device_code>3584d83530557fdd1f46af8289938c8ef79f9dc5</device_code>
  <user_code>WDJB-MJHT</user_code>
  <verification_uri>http(s)://HOSTNAME/login/device</verification_uri>
  <expires_in>900</expires_in>
  <interval>5</interval>
</OAuth>

Paso 2: Indicar al usuario ingresar el código de usuario en un buscador

Tu dispositivo mostrará el código de verificación de usuario y pedirá al usuario ingresar el código en la http(s)://HOSTNAME/login/device.

Paso 3: La aplicación sondea GitHub para comprobar si el usuario autorizó el dispositivo

POST http(s)://HOSTNAME/login/oauth/access_token

La aplicación realizará solicitudes de autorización de dispositivo que sondean POST http(s)://HOSTNAME/login/oauth/access_token hasta que expiren los códigos de usuario y dispositivo, o el usuario haya autorizado correctamente la aplicación con un código de usuario válido. La aplicación debe usar el sondeo interval mínimo recuperado en el paso 1 para evitar errores de límite de frecuencia. Para más información, consulta Límites de frecuencia para el flujo del dispositivo.

El usuario debe ingresar un código válido dentro de los 15 minutos (o 900 segundos) siguientes. Después de 15 minutos, tendrá que solicitar un nuevo código de autorización de dispositivo con POST http(s)://HOSTNAME/login/device/code.

Ya que el usuario lo haya autorizado, la app recibirá un token de acceso que se puede utilizar para hacer solicitudes a la API en nombre de un usuario.

El punto de conexión toma los siguientes parámetros de entrada.

Nombre de parámetro	Tipo	Descripción
`client_id`	`string`

          **Obligatorio.** El ID de cliente que has recibido de GitHub para tu aplicación OAuth app.

device_code | string | Obligatorio. El device_code que recibió de la solicitud POST http(s)://HOSTNAME/login/device/code. grant_type | string | Obligatorio. El tipo de concesión debe ser urn:ietf:params:oauth:grant-type:device_code.

Predeterminadamente, la respuesta toma la siguiente forma:

access_token=gho_16C7e42F292c6912E7710c838347Ae178B4a&token_type=bearer&scope=repo%2Cgist

También puede recibir la respuesta en diferentes formatos si proporciona el formato en el encabezado Accept. Por ejemplo, Accept: application/json o Accept: application/xml:

Accept: application/json
{
 "access_token": "gho_16C7e42F292c6912E7710c838347Ae178B4a",
  "token_type": "bearer",
  "scope": "repo,gist"
}

Accept: application/xml
<OAuth>
  <access_token>gho_16C7e42F292c6912E7710c838347Ae178B4a</access_token>
  <token_type>bearer</token_type>
  <scope>gist,repo</scope>
</OAuth>

Límites de velocidad para el flujo de dispositivo

Cuando un usuario emite el código de verificación en el buscador, hay un límite de tasa de 50 emisiones en una hora por aplicación.

Si realiza más de una solicitud de token de acceso (POST http(s)://HOSTNAME/login/oauth/access_token) dentro del período mínimo necesario entre las solicitudes (o interval), alcanzará el límite de frecuencia y recibirá una respuesta de error slow_down. La respuesta de error slow_down agrega 5 segundos al último interval. Para más información, vea Códigos de error para el flujo del dispositivo.

Códigos de error para el flujo del dispositivo

Código de error	Descripción
`authorization_pending`	Este error ocurre cuando la solicitud de autorización se encuentra pendiente y el usuario no ha ingresado el código de usuario aún. Se espera que la aplicación continúe sondeando la solicitud `POST http(s)://HOSTNAME/login/oauth/access_token` sin superar el límite `interval`, lo cual requiere un número mínimo de segundos entre cada solicitud.
`slow_down`	Cuando recibe el error `slow_down`, se agregan 5 segundos adicionales al valor `interval` mínimo o período de tiempo necesario entre las solicitudes mediante `POST http(s)://HOSTNAME/login/oauth/access_token`. Por ejemplo, si en el intervalo de inicio se necesitaban al menos 5 segundos entre solicitudes y recibe una respuesta de error `slow_down`, ahora tendrá que esperar al menos 10 segundos antes de poder realizar una nueva solicitud para un token de acceso de OAuth. La respuesta de error incluye el nuevo valor `interval` que debe usar.
`expired_token`	Si el código del dispositivo ha expirado, verá el error `token_expired`. Debes hacer una nueva solicitud para un código de dispositivo.
`unsupported_grant_type`	El tipo de concesión debe ser `urn:ietf:params:oauth:grant-type:device_code` e incluirse como parámetro de entrada al sondear la solicitud de token de OAuth `POST http(s)://HOSTNAME/login/oauth/access_token`.
`incorrect_client_credentials`	Para el flujo de dispositivos, debes pasar la ID de cliente de tu app, la cual puedes encontrar en la página de configuración de la misma.

          `client_secret` no es necesario para el flujo del dispositivo.

| incorrect_device_code | El device_code que se proporcionó es inválido. | access_denied | Cuando un usuario hace clic en Cancelar durante el proceso de autorización, recibirá un error de access_denied y el usuario no podrá volver a utilizar el código de verificación. | device_flow_disabled | El flujo de dispositivos no ha sido habilitado en la configuración de la aplicación. Para más información, consulta Flujo de dispositivos.

Para más información, consulta Concesión de autorización de dispositivos de OAuth 2.0.

Flujo de aplicaciónes no web

La autenticación no web está disponible para situaciones limitadas, como las pruebas. Si lo necesitas, puede usar la autenticación básica para crear un personal access token en la página de configuración de personal access token. Esta técnica le permite al usuario revocar el acceso en cualquier momento.

URL de redireccionamiento

El redirect_uri parámetro es opcional. Si se excluye, GitHub redireccionará a los usuarios a la URL de devolución de llamada configurada en la OAuth app. Si se proporciona, el host (excluyendo los subdominios) y el puerto de la URL de redireccionamiento deben coincidir exactamente con los de la URL de devolución de llamada. La ruta de la URL de redireccionamiento debe hacer referencia a un subdirectorio de la URL de retorno.

CALLBACK: http://example.com/path

GOOD: http://example.com/path
GOOD: http://example.com/path/subdir/other
GOOD: http://oauth.example.com/path
GOOD: http://oauth.example.com/path/subdir/other
BAD:  http://example.com/bar
BAD:  http://example.com/
BAD:  http://example.com:8080/path
BAD:  http://oauth.example.com:8080/path
BAD:  http://example.org

Direcciones URL de redireccionamiento de bucle invertido

El parámetro opcional redirect_uri también se puede usar para las direcciones URL de bucle invertido, lo que resulta útil para las aplicaciones nativas que se ejecutan en un equipo de escritorio. Si la aplicación especifica una URL de bucle invertido y un puerto, los usuarios serán redirigidos a la URL y el puerto proporcionados después de autorizar la aplicación. No es necesario que redirect_uri coincida con el puerto especificado en la dirección URL de devolución de llamada de la aplicación.

Para la dirección URL de devolución de llamada http://127.0.0.1/path, puede usar esta redirect_uri si la aplicación está escuchando en el puerto 1234:

http://127.0.0.1:1234/path

Recuerda que en la especificación RFC de OAuth se recomienda no usar localhost, sino usar el literal de bucle invertido 127.0.0.1 o la IPv6 ::1.

Creación de múltiples tokens para OAuth apps

Puedes crear tokens múltiples para una combinación de usuario/aplicación/alcance para crear tokens para casos de uso específicos.

Esto es útil si tu OAuth app es compatible con un flujo de trabajo que utilice GitHub para registrarse y requiera solo información básica del usuario. Otro flujo de trabajo podría requerir acceso a los repositorios privados del usuario. Al utilizar tokens múltiples, tu OAuth app podrá llevar a cabo el flujo web para cada caso de uso, solicitando únicamente los alcances que necesite. Si un usuario utiliza tu aplicación únicamente para iniciar sesión, nunca se les requerirá otorgar acceso a tu OAuth app para sus repositorios privados.

Hay un límite de diez tokens que se emiten por combinación de usuario/aplicación/ámbito y un límite de frecuencia de diez tokens creados por hora. Si una aplicación crea más de diez tokens para el mismo usuario y los mismos alcances, se revocarán los tokens más antiguos con la misma combinación de usuario/aplicación/alcance. Sin embargo, alcanzar el límite de volumen por hora no revocará el token más antiguo. En su lugar, desencadenará una solicitud de nueva autorización en el explorador, y se pedirá al usuario que compruebe los permisos que concede a la aplicación. Este mensaje está pensado interrumpir cualquier bucle infinito posible en el que la aplicación está atrapada, ya que hay pocos o ningún motivo para que una aplicación solicite diez tokens al usuario en un plazo de una hora.

Advertencia

Si revocas todos los permisos de una OAuth app, se eliminarán todas las claves SSH generadas por la aplicación en nombre del usuario, incluidas las claves de implementación.

Dirigir a los usuarios para revisar su acceso

Puedes vincular a la información de autorización para una OAuth app para que los usuarios puedan revisar y revocar sus autorizaciones de la aplicación.

Para crear este vínculo, necesitarás el client_id de las OAuth app que has recibido de GitHub al registrar la aplicación.

http(s)://HOSTNAME/settings/connections/applications/:client_id

Sugerencia

Para obtener más información sobre los recursos de un usuario a los que puede acceder la OAuth app, consulte Descubrir los recursos para un usuario.

Solución de problemas

        [AUTOTITLE](/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-authorization-request-errors)

        [AUTOTITLE](/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-oauth-app-access-token-request-errors)

        [Errores de flujo de dispositivo](#error-codes-for-the-device-flow)

        [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation)

Información adicional

        [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-authentication-to-github)

En este artículo