Cuando estás configurando una App de OAuth en GitHub, los alcances solicitados se muestran al usuario en el formato de autorización.
Nota: Si estás creando una GitHub App, no necesitas proporcionar alcances en tu solicitud de autorización. Para obtener más información sobre esto, consulta la sección "Identificar y autorizar usuarios para las GitHub Apps".
Si tu App OAuth no tiene acceso a un buscador, tal como una herramienta de CLI, entonces no necesitarás especificar un alcance para que los usuarios se autentiquen dicha app. Para obtener más información, consulta la sección "Autorizar las Apps de OAuth".
Verifica los encabezados para ver qué alcances de OAuth tienes, y cuáles acepta la acción de la API:
$ curl -H "Authorization: token OAUTH-TOKEN" http(s)://[hostname]/api/v3/users/codertocat -I
HTTP/2 200
X-OAuth-Scopes: repo, user
X-Accepted-OAuth-Scopes: userX-OAuth-Scopeslista los alcances que tu token tiene autorizados.X-Accepted-OAuth-Scopeslista los alcances que revisrá la acción.
Alcances disponibles
| Nombre | Descripción |
|---|---|
(no scope) | Otorga acceso de solo lectura a la información pública (incluyendo la del perfil del usuario, repositorio y gists) |
site_admin | Otorga a los administradores de sitio acceso a las Terminales de la API para la Administración de GitHub Enterprise Server. |
repo | Otorga acceso completo a los repositorios, icnluyendo los privados. Esto incluye acceso de lectura/escritura al código, estados de confirmaciones, proyectos de organización y de repositorio, invitaciones, colaboradores, agregar membrecías de equipo, estados de despliegue y webhooks de repositorio para organizaciones y repositorios. También otorga la capacidad de administrar proyectos de usuario. |
repo:status | Otorga acceso de lectura/escritura para los estados de confirmaciones de repositorios públicos y privados. Este alcance solo se necesita para otorgar a otros usuarios o servicios el acceso a los estados de las confirmaciones en repositorios privados sin otorgarles acceso al código. |
repo_deployment | Otorga acceso a los estados de despliegue para los repositoriospúblicos y privados. Este alcance solo se necesita para otorgar acceso a otros usuarios o servicios para los estados de despliegue, sin otorgar acceso al código. |
public_repo | Limita el acceso a los repositorios públicos. Esto incluye el acceso de lectura/escritura al código, estados de las confirmaciones, proyectos de repositorio, colaboradores y estados de despliegue para los repositorios públicos y para las organizaciones. También se requieren para marcar los repositorios públicos como favoritos. |
repo:invite | Otorga capacidades de aceptar/rechazar las invitaciones para colaborar con un repositorio. Este alcance solo es necesario para otorgar a otros usuarios o servicios acceso a las invitaciones sin otorgar acceso al código. |
security_events | Otorga acceso de lectura y escritura a los eventos de seguridad en la API de escaneo de código. Este alcance solo es necesario para otorgar acceso a los eventos de seguridad a otros usuarios o servicios sin otorgarles acceso al código. |
admin:repo_hook | Otorga acceso de lectura, escritura, ping y borrado para los ganchos de repositorio en los repositorios públicos y privados. El alcance de repo y de public_repo otorgan acceso total a los repositorios, icnluyendo a los ganchos de repositorio. Utiliza el alcance admin:repo_hook para limitar el acceso únicamente a los ganchos de los repositorios. |
write:repo_hook | Otorga acceso de lectura, escritura y ping a los ganchos en los repositorios públicos o privados. |
read:repo_hook | Otorga acceso de lectura y ping a los ganchos en los repositorios públicos o privados. |
admin:org | Para administrar totalmente la organización y sus equipos, proyectos y membrecías. |
write:org | Acceso de lectura y escritura para la membrecía de organización y de los equipos y para los proyectos de la organización. |
read:org | Acceso de solo lectura para la membrecía de organización y de los equipos y para los proyectos de la organización. |
admin:public_key | Administrar totalmente las llaves públicas. |
write:public_key | Crear, listar y ver los detalles de las llaves públicas. |
read:public_key | Listar y ver los detalles para las llaves públicas. |
admin:org_hook | Otorga acceso de lectura, escritura, ping y borrado para los ganchos de la organización. Nota: Los tokens de OAuth solo podrán realizar estas acciones en los ganchos de la organización los cuales haya creado la App de OAuth. Los tokens de acceso personal solo podrán llevar a cabo estas acciones en los ganchos de la organización que cree un usuario. |
gist | Otorga acceso de escritura a los gists. |
notifications | Otorga: acceso de lectura a las notificaciones de un usuario acceso de marcar como leído en los hilos acceso de observar y dejar de observar en un repositorio, y acceso de lectura, escritura y borrado para las suscripciones a los hilos. |
usuario | Otorga acceso de lectura/escritura únicamente para la información de perfil. Este alcance incluye a user:email y user:follow. |
read:user | Otorga acceso para leer los datos de perfil de un usuario. |
user:email | Otorga acceso de lectura para las direcciones de correo electrónico de un usuario. |
user:follow | Otorga acceso para seguir o dejar de seguir a otros usuarios. |
delete_repo | Otorga acceso para borrar los repositorios administrables. |
write:discussion | Permite el acceso de lectura y escritura para los debates de equipo. |
read:discussion | Permite los accesos de lectura y escritura para los debates de equipo. |
admin:gpg_key | Administra las llaves GPG totalmente. |
write:gpg_key | Crea, lista, y visualiza los detalles de las llaves GPG. |
read:gpg_key | Lista y visualiza los detalles de las llaves GPG. |
Nota: Tu App de OAuth puede solicitar los alcances en la redirección inicial. Puedes especificar alcances múltiples si los separas con un espacio utilizando %20:
https://github.com/login/oauth/authorize?
client_id=...&
scope=user%20repo_deployment
Alcances solicitados y otorgados
El atributo scope lista los alcances adjuntos al token que otorgó el usuario. Normalmente, estos alcances serán idénticos a lo que solicitaste. Sin embargo, los usuarios pueden editar sus alcances, lo cual es efectivo para otorgar a tu organización menos accesos de lo que solicitaste originalmente. También, los usuarios puede editar los alcances de los tokens después de completar un flujo de OAuth. Debes estar consciente de esta posibilidad y ajustar el comportamiento de tu aplicación de acuerdo con esto.
Es importante gestionar los casos de error en donde un usuario elige otorgarte menos acceso de lo que solicitaste originalmente. Por ejemplo, las aplicaciones pueden advertir o comunicar de cualquier otra forma a sus usuarios si experimentarán funcionalidad reducida o si serán incapaces de realizar alguna acción.
También, las aplicaciones siempre pueden enviar nuevamente de regreso a los usuarios a través del flujo para obtener permisos adicionales, pero no olvides que dichos usuarios siempre pueden rehusarse a hacerlo.
Revisa la sección Guía de aspectos básicos de la autenticación, la cual proporciona consejos sobre la gestión de alcances modificables de los tokens.
Alcances normalizados
Cuando solicites alcances múltiples, el token se guarda con una lista de alcances normalizada y descarta aquellos que se otro alcance solicitado incluya implícitamente. Por ejemplo, el solicitar user,gist,user:email dará como resultado un token con alcances de user y de gist únicamente, ya que el acceso que se otorga con el alcance user:email se incluye en el alcance user.