GitHub: создание гранулированного токена доступа
Веб-сервис «GitHub»
Для тех, кто не в курсе, «GitHub» - это крупный (возможно даже, крупнейший в мире на данный момент) веб-сервис для хостинга IT-проектов и их совместной разработки (на самом деле, там никто вас не ограничивает информационными технологиями; там можно хранить любые текстовые файлы, например, писать книгу или хранить файлы своего сайта и так далее). Этот веб-сервис, в первую очередь, привлекает тем, что он является системой управления версиями проекта, построен на базе популярнейшей на сегодня системы управления версиями «Git».
В своих постах, также как и в этом, я часто называю «GitHub» русскоязычной калькой «Гитхаб», так как ее удобнее писать (не нужно переключаться на англоязычную раскладку клавиатуры) и ее можно склонять, это удобно.
Токены (маркеры) доступа
В последние годы веб-сервисы, предназначенные для людей, более-менее разбирающихся в информационных технологиях, стали уделять всё больше внимания так называемым «токенам доступа» (еще их называют «маркерами доступа», по-английски «access token» или «personal access token», сокращенно «PAT»). Токены доступа призваны заменить обычные пароли, но на данный момент все веб-сервисы, на которых я использовал токены доступа, применяют их параллельно с обычными паролями. При этом обычные пароли используются для одних целей, а токены доступа - для других целей, но области их применения могут пересекаться.
Токен доступа, как и обычный пароль, представляет из себя последовательность символов. Только последовательность символов токена доступа в несколько раз длиннее обычного пароля и генерируется автоматически по определенному алгоритму. Также токен доступа обычно имеет более короткий, чем у обычного пароля, срок действия (срок действия обычно назначается при создании токена доступа), это лучше для безопасности. Кроме того, если обычный пароль может использоваться сразу для многих задач, требующих доступа к защищенным паролем данным, то применение токена доступа может иметь более узкий характер, область применения токена доступа может быть настроена при его создании. Еще вы можете создать сразу множество токенов доступа, выдавать их другим людям при совместной работе над проектом, а обычный пароль - один-единственный и выдавать его кому-либо опасно.
Два вида токенов доступа на «Гитхабе»
Токены доступа применяются на «Гитхабе» уже довольно давно. Но, насколько я понимаю, со временем выяснилось, что у имеющейся реализации токенов доступа недостаточно тонкая настройка специализации доступа к разным задачам на «Гитхабе». Из-за этого разработчики «Гитхаба» создали новую реализацию токенов доступа, с более подробной специализацией доступа. Новая реализация токенов доступа уже доступна для использования и рекомендуется в документации «Гитхаба» в качестве приоритетной, но на данный момент еще находится в стадии бета-тестирования.
Чтобы отличать эти две реализации токенов доступа друг от друга, первую называют «классической» реализацией («классические» токены доступа), а вторую называют «более специализированной» или «более гранулированной» реализацией («гранулированные» токены доступа, по-английски «fine-grained token»).
В этом посте речь идет о создании гранулированных токенов доступа.
Токены доступа в меню «Гитхаба»
В интерфейсе и меню «Гитхаба» не всегда можно легко разобраться. Про работу с токенами доступа в документации «Гитхаба» есть отдельная статья: «Managing your personal access tokens» (по-русски «Управление вашими токенами доступа»).
Если вы авторизованы на «Гитхабе», вы можете открыть одно из меню «Гитхаба», нажав на свою аватарку в правом верхнем углу любой страницы веб-сервиса (кстати, дизайн страниц «Гитхаба» недавно в очередной раз поменяли). В этом меню следует выбрать пункт «Settings» (по-русски «Настройки»). На открывшейся странице следует в меню слева выбрать пункт «Developer settings» (это самый последний пункт в меню, по-русски «Настройки для разработчиков»):
Settings / Developer settings
https://github.com/settings/apps
На открывшейся странице слева есть меню из трех пунктов: «GitHub Apps», «OAuth Apps» и «Personal access tokens». Следует выбрать пункт «Personal access tokens». В результате под этим пунктом откроется подменю из двух пунктов:
Personal access tokens
Fine-grained tokens
Tokens (classic)
Следует выбрать подпункт «Fine-grained tokens».
На открывшейся странице будет показан список действующих (созданных ранее) гранулированных токенов доступа, а также есть кнопка «Generate new token», с помощью которой можно создать новый гранулированный токен доступа.
Начало создания нового гранулированного токена доступа
После нажатия на кнопку «Generate new token» веб-сервис запросил у меня пароль моей учетной записи для подтверждения моего права создавать токены доступа, несмотря на то, что я уже ранее авторизовался на веб-сервисе. Вероятно, это делается для дополнительного усиления безопасности. Я ввел свой пароль, и после этого открылась страница с настройками создаваемого гранулированного токена доступа.
Думаю, очевидно, что настройка свойств создаваемого токена доступа зависит от цели его будущего применения. В целях безопасности при настройке токена доступа рекомендуют как можно сильнее ограничивать права, выдаваемые создаваемому токену доступа. Именно для этого создавалась новая реализация токенов доступа, более гранулированная (то есть права, выдаваемые токену, можно настроить более тонко, чем раньше).
В моем случае мне требовался токен доступа для разрешения внесения коммитов в один из моих репозиториев на «Гитхабе».
Среди свойств создаваемого гранулированного токена доступа есть обязательные для заполнения (помечаются звездочкой красного цвета) и необязательные для заполнения. Обязательных для заполнения всего два: «Token name» (название токена) и «Expiration» (срок действия). Часть свойств токена имеет значения по умолчанию, которые будут использованы, если вас не интересует значение (устраивает значение по умолчанию) данного свойства. Вот как я заполнил свойства моего нового токена доступа:
Token name *: Коммиты в learncpp-com-examples (разрешены пробелы и русские буквы)
Expiration *: 30 days (по умолчанию)
Description: по умолчанию пустое, заполнять не стал
Resource owner: ilyachalov (по умолчанию, моё имя пользователя на «Гитхабе»)
Выбор репозитория и разрешений
Конечно, главное в настройке гранулированного токена доступа - это выбор репозитория (или ряда репозиториев), к которым данный токен будет разрешать доступ, а также указание конкретных задач, на которые получатель токена доступа получит разрешение. Это можно сделать в разделах «Repository access» (выбор одного или группы репозиториев) и «Permissions» (указание конкретных задач, на которые вы даёте разрешение) свойств создаваемого гранулированного токена доступа, расположенных ниже вышеописанных общих свойств.
По умолчанию, если свойства в разделах «Repository access» и «Permissions» никак не менять, создаваемый токен не дает никаких разрешений. Такой токен доступа создавать не имеет смысла, поэтому в разделах «Repository access» и «Permissions» в любом случае необходимо будет произвести настройки.
Следует иметь в виду, что состав настроек в разделе «Permissions» зависит от выбора, сделанного в разделе «Repository access». По умолчанию в разделе «Repository access» выбрана опция «Public Repositories (read-only)», из-за этого в разделе «Permissions» присутствует только блок задач «Account permissions» (разрешения на выполнение задач, относящихся к вашей учетной записи), а нужный мне блок задач «Repository permissions» (разрешения на выполнение задач, относящихся к выбранным в разделе «Repository access» репозиториям) отсутствует.
Таким образом, сначала я в разделе «Repository access» выбрал опцию «Only select repositories» (только выбранные репозитории). После выбора под этой опцией появилась кнопка-список «Select repositories» (выбранные репозитории), с помощью которой я выбрал один из моих репозиториев на «Гитхабе», который называется «learncpp-com-examples»:
Repository access
( ) Public Repositories (read-only)
( ) All repositories
(*) Only select repositories
Select repositories:
- ilyachalov/learncpp-com-examples
После этого в разделе «Permissions» присутствуют два блока задач: «Repository permissions» и «Account permissions», которые я уже упоминал выше. Их можно разворачивать (и сворачивать обратно), щелкая мышью на название блока задач.
Каждый из этих блоков задач представляет собой длиннющий список разных отдельных задач, на которые можно дать (включить) разрешение с помощью данного токена доступа. Задач там столько, что поначалу глаза разбегаются. Разобраться в этих списках с первого раза не так-то просто. Для каждой задачи имеется кнопка-список, с помощью которой для данной задачи можно выбрать нужное разрешение (эти разрешения бывают нескольких видов: «No access» (по умолчанию, «доступ не разрешен»), «Read-only» (только чтение), «Read and write» (чтение и запись)).
Для моих нужд (разрешение на внесение коммитов в вышеуказанный репозиторий) я сделал следующую настройку:
Permissions
Repository permissions
Contents: Read and write
Metadata: Read-only
Account permissions
То есть я нашел в блоке задач «Repository permissions» задачу «Contents» (разрешения на доступ к содержимому репозитория, к коммитам, веткам и так далее) и выбрал для нее разрешение (уровень доступа) «Read and write». При этом я не настраивал доступ к задаче «Metadata», это сделал сам «Гитхаб» автоматически после того, как я выбрал разрешение для задачи «Contents». Вероятно, разрешение доступа к задаче «Contents» связано с разрешением доступа к задаче «Metadata».
Разрешения для всех остальных задач в обоих блоках задач «Repository permissions» и «Account permissions» я оставил по умолчанию, то есть со значением «No access» (доступ не разрешен).
Завершение создания нового гранулированного токена доступа
Последний раздел настроек создаваемого токена доступа называется «Overview» (по-русски «обзор сделанных настроек» или «резюме»). В этом разделе нет никаких настроек, а есть только информация о некоторых сделанных вами ключевых настройках для создаваемого токена доступа: список выдаваемых токеном разрешений и срок действия токена. В этом разделе следует убедиться, что вы нигде не совершили ошибки и действительно настроили токен доступа так, как вам требуется. Вот как примерно этот раздел выглядит у меня:
Overview
2 permissions for 1 of your repositories
Contents Access: Read and write
Metadata Access: Read-only
0 Account permissions
This token will expire July 28, 2023.
Под этим разделом на странице находится кнопка «Generate token». Я ее нажал и новый гранулированный токен доступа был создан. После создания токена доступа снова откроется страница со списком имеющихся гранулированных токенов доступа.
Важно отметить, что в этот момент в списке токенов следует сразу скопировать новый токен доступа и сохранить его где-то у себя на компьютере. (Справа от нужной последовательности символов для удобства имеется кнопка, с помощью которой можно скопировать токен в буфер обмена.) Если этого не сделать и, к примеру, обновить страницу, то последовательность символов токена больше не будет доступна для копирования (ее вообще не будет больше видно нигде). Такой подход к работе с токеном доступа продиктован соображениями, касающимися безопасности.
Если вы всё же не скопировали сразу последовательность символов токена доступа, то создавать его заново не требуется. Можно перейти на страницу данного токена, нажав мышью на его название в списке, и на этой странице можно заново сгенерировать последовательность символов токена с помощью кнопки «Regenerate token». В результате предыдущая последовательность символов токена будет аннулирована, а вместо нее будет создана другая последовательность символов токена с теми же настройками и разрешениями.
Заключение
Я проверил полученный токен в деле: отправил коммит в свой репозиторий на «Гитхабе» из командной строки со своего компьютера (git push). Там требуется авторизация с помощью токена доступа. Авторизация прошла успешно, созданный токен доступа сработал, там он используется вместо пароля.
Для тех, кто не в курсе, «GitHub» - это крупный (возможно даже, крупнейший в мире на данный момент) веб-сервис для хостинга IT-проектов и их совместной разработки (на самом деле, там никто вас не ограничивает информационными технологиями; там можно хранить любые текстовые файлы, например, писать книгу или хранить файлы своего сайта и так далее). Этот веб-сервис, в первую очередь, привлекает тем, что он является системой управления версиями проекта, построен на базе популярнейшей на сегодня системы управления версиями «Git».
В своих постах, также как и в этом, я часто называю «GitHub» русскоязычной калькой «Гитхаб», так как ее удобнее писать (не нужно переключаться на англоязычную раскладку клавиатуры) и ее можно склонять, это удобно.
Токены (маркеры) доступа
В последние годы веб-сервисы, предназначенные для людей, более-менее разбирающихся в информационных технологиях, стали уделять всё больше внимания так называемым «токенам доступа» (еще их называют «маркерами доступа», по-английски «access token» или «personal access token», сокращенно «PAT»). Токены доступа призваны заменить обычные пароли, но на данный момент все веб-сервисы, на которых я использовал токены доступа, применяют их параллельно с обычными паролями. При этом обычные пароли используются для одних целей, а токены доступа - для других целей, но области их применения могут пересекаться.
Токен доступа, как и обычный пароль, представляет из себя последовательность символов. Только последовательность символов токена доступа в несколько раз длиннее обычного пароля и генерируется автоматически по определенному алгоритму. Также токен доступа обычно имеет более короткий, чем у обычного пароля, срок действия (срок действия обычно назначается при создании токена доступа), это лучше для безопасности. Кроме того, если обычный пароль может использоваться сразу для многих задач, требующих доступа к защищенным паролем данным, то применение токена доступа может иметь более узкий характер, область применения токена доступа может быть настроена при его создании. Еще вы можете создать сразу множество токенов доступа, выдавать их другим людям при совместной работе над проектом, а обычный пароль - один-единственный и выдавать его кому-либо опасно.
Два вида токенов доступа на «Гитхабе»
Токены доступа применяются на «Гитхабе» уже довольно давно. Но, насколько я понимаю, со временем выяснилось, что у имеющейся реализации токенов доступа недостаточно тонкая настройка специализации доступа к разным задачам на «Гитхабе». Из-за этого разработчики «Гитхаба» создали новую реализацию токенов доступа, с более подробной специализацией доступа. Новая реализация токенов доступа уже доступна для использования и рекомендуется в документации «Гитхаба» в качестве приоритетной, но на данный момент еще находится в стадии бета-тестирования.
Чтобы отличать эти две реализации токенов доступа друг от друга, первую называют «классической» реализацией («классические» токены доступа), а вторую называют «более специализированной» или «более гранулированной» реализацией («гранулированные» токены доступа, по-английски «fine-grained token»).
В этом посте речь идет о создании гранулированных токенов доступа.
Токены доступа в меню «Гитхаба»
В интерфейсе и меню «Гитхаба» не всегда можно легко разобраться. Про работу с токенами доступа в документации «Гитхаба» есть отдельная статья: «Managing your personal access tokens» (по-русски «Управление вашими токенами доступа»).
Если вы авторизованы на «Гитхабе», вы можете открыть одно из меню «Гитхаба», нажав на свою аватарку в правом верхнем углу любой страницы веб-сервиса (кстати, дизайн страниц «Гитхаба» недавно в очередной раз поменяли). В этом меню следует выбрать пункт «Settings» (по-русски «Настройки»). На открывшейся странице следует в меню слева выбрать пункт «Developer settings» (это самый последний пункт в меню, по-русски «Настройки для разработчиков»):
Settings / Developer settings
https://github.com/settings/apps
На открывшейся странице слева есть меню из трех пунктов: «GitHub Apps», «OAuth Apps» и «Personal access tokens». Следует выбрать пункт «Personal access tokens». В результате под этим пунктом откроется подменю из двух пунктов:
Personal access tokens
Fine-grained tokens
Tokens (classic)
Следует выбрать подпункт «Fine-grained tokens».
На открывшейся странице будет показан список действующих (созданных ранее) гранулированных токенов доступа, а также есть кнопка «Generate new token», с помощью которой можно создать новый гранулированный токен доступа.
Начало создания нового гранулированного токена доступа
После нажатия на кнопку «Generate new token» веб-сервис запросил у меня пароль моей учетной записи для подтверждения моего права создавать токены доступа, несмотря на то, что я уже ранее авторизовался на веб-сервисе. Вероятно, это делается для дополнительного усиления безопасности. Я ввел свой пароль, и после этого открылась страница с настройками создаваемого гранулированного токена доступа.
Думаю, очевидно, что настройка свойств создаваемого токена доступа зависит от цели его будущего применения. В целях безопасности при настройке токена доступа рекомендуют как можно сильнее ограничивать права, выдаваемые создаваемому токену доступа. Именно для этого создавалась новая реализация токенов доступа, более гранулированная (то есть права, выдаваемые токену, можно настроить более тонко, чем раньше).
В моем случае мне требовался токен доступа для разрешения внесения коммитов в один из моих репозиториев на «Гитхабе».
Среди свойств создаваемого гранулированного токена доступа есть обязательные для заполнения (помечаются звездочкой красного цвета) и необязательные для заполнения. Обязательных для заполнения всего два: «Token name» (название токена) и «Expiration» (срок действия). Часть свойств токена имеет значения по умолчанию, которые будут использованы, если вас не интересует значение (устраивает значение по умолчанию) данного свойства. Вот как я заполнил свойства моего нового токена доступа:
Token name *: Коммиты в learncpp-com-examples (разрешены пробелы и русские буквы)
Expiration *: 30 days (по умолчанию)
Description: по умолчанию пустое, заполнять не стал
Resource owner: ilyachalov (по умолчанию, моё имя пользователя на «Гитхабе»)
Выбор репозитория и разрешений
Конечно, главное в настройке гранулированного токена доступа - это выбор репозитория (или ряда репозиториев), к которым данный токен будет разрешать доступ, а также указание конкретных задач, на которые получатель токена доступа получит разрешение. Это можно сделать в разделах «Repository access» (выбор одного или группы репозиториев) и «Permissions» (указание конкретных задач, на которые вы даёте разрешение) свойств создаваемого гранулированного токена доступа, расположенных ниже вышеописанных общих свойств.
По умолчанию, если свойства в разделах «Repository access» и «Permissions» никак не менять, создаваемый токен не дает никаких разрешений. Такой токен доступа создавать не имеет смысла, поэтому в разделах «Repository access» и «Permissions» в любом случае необходимо будет произвести настройки.
Следует иметь в виду, что состав настроек в разделе «Permissions» зависит от выбора, сделанного в разделе «Repository access». По умолчанию в разделе «Repository access» выбрана опция «Public Repositories (read-only)», из-за этого в разделе «Permissions» присутствует только блок задач «Account permissions» (разрешения на выполнение задач, относящихся к вашей учетной записи), а нужный мне блок задач «Repository permissions» (разрешения на выполнение задач, относящихся к выбранным в разделе «Repository access» репозиториям) отсутствует.
Таким образом, сначала я в разделе «Repository access» выбрал опцию «Only select repositories» (только выбранные репозитории). После выбора под этой опцией появилась кнопка-список «Select repositories» (выбранные репозитории), с помощью которой я выбрал один из моих репозиториев на «Гитхабе», который называется «learncpp-com-examples»:
Repository access
( ) Public Repositories (read-only)
( ) All repositories
(*) Only select repositories
Select repositories:
- ilyachalov/learncpp-com-examples
После этого в разделе «Permissions» присутствуют два блока задач: «Repository permissions» и «Account permissions», которые я уже упоминал выше. Их можно разворачивать (и сворачивать обратно), щелкая мышью на название блока задач.
Каждый из этих блоков задач представляет собой длиннющий список разных отдельных задач, на которые можно дать (включить) разрешение с помощью данного токена доступа. Задач там столько, что поначалу глаза разбегаются. Разобраться в этих списках с первого раза не так-то просто. Для каждой задачи имеется кнопка-список, с помощью которой для данной задачи можно выбрать нужное разрешение (эти разрешения бывают нескольких видов: «No access» (по умолчанию, «доступ не разрешен»), «Read-only» (только чтение), «Read and write» (чтение и запись)).
Для моих нужд (разрешение на внесение коммитов в вышеуказанный репозиторий) я сделал следующую настройку:
Permissions
Repository permissions
Contents: Read and write
Metadata: Read-only
Account permissions
То есть я нашел в блоке задач «Repository permissions» задачу «Contents» (разрешения на доступ к содержимому репозитория, к коммитам, веткам и так далее) и выбрал для нее разрешение (уровень доступа) «Read and write». При этом я не настраивал доступ к задаче «Metadata», это сделал сам «Гитхаб» автоматически после того, как я выбрал разрешение для задачи «Contents». Вероятно, разрешение доступа к задаче «Contents» связано с разрешением доступа к задаче «Metadata».
Разрешения для всех остальных задач в обоих блоках задач «Repository permissions» и «Account permissions» я оставил по умолчанию, то есть со значением «No access» (доступ не разрешен).
Завершение создания нового гранулированного токена доступа
Последний раздел настроек создаваемого токена доступа называется «Overview» (по-русски «обзор сделанных настроек» или «резюме»). В этом разделе нет никаких настроек, а есть только информация о некоторых сделанных вами ключевых настройках для создаваемого токена доступа: список выдаваемых токеном разрешений и срок действия токена. В этом разделе следует убедиться, что вы нигде не совершили ошибки и действительно настроили токен доступа так, как вам требуется. Вот как примерно этот раздел выглядит у меня:
Overview
2 permissions for 1 of your repositories
Contents Access: Read and write
Metadata Access: Read-only
0 Account permissions
This token will expire July 28, 2023.
Под этим разделом на странице находится кнопка «Generate token». Я ее нажал и новый гранулированный токен доступа был создан. После создания токена доступа снова откроется страница со списком имеющихся гранулированных токенов доступа.
Важно отметить, что в этот момент в списке токенов следует сразу скопировать новый токен доступа и сохранить его где-то у себя на компьютере. (Справа от нужной последовательности символов для удобства имеется кнопка, с помощью которой можно скопировать токен в буфер обмена.) Если этого не сделать и, к примеру, обновить страницу, то последовательность символов токена больше не будет доступна для копирования (ее вообще не будет больше видно нигде). Такой подход к работе с токеном доступа продиктован соображениями, касающимися безопасности.
Если вы всё же не скопировали сразу последовательность символов токена доступа, то создавать его заново не требуется. Можно перейти на страницу данного токена, нажав мышью на его название в списке, и на этой странице можно заново сгенерировать последовательность символов токена с помощью кнопки «Regenerate token». В результате предыдущая последовательность символов токена будет аннулирована, а вместо нее будет создана другая последовательность символов токена с теми же настройками и разрешениями.
Заключение
Я проверил полученный токен в деле: отправил коммит в свой репозиторий на «Гитхабе» из командной строки со своего компьютера (git push). Там требуется авторизация с помощью токена доступа. Авторизация прошла успешно, созданный токен доступа сработал, там он используется вместо пароля.