Руководство по использованию OAuth 2.0 для доступа к API GitHub

Аутентификация с помощью API GitHub может позволить вашему веб-приложению управлять репозиториями, конвейерами CI/CD и многим другим от имени ваших пользователей. В этой статье я покажу, как настроить приложение для аутентификации с помощью API GitHub с использованием OAuth 2.0; многие показанные примеры будут относиться к настройке интеграции между Infisical и GitHub, но вы сможете адаптировать их к своему собственному варианту использования.

На высоком уровне нам нужно будет настроить приложение OAuth в GitHub и настроить поток OAuth 2.0 в нашем приложении для работы с ним.

Не знаете, что такое OAuth? Ознакомьтесь с букварем здесь.

Общий обзор

Прежде чем мы углубимся в то, как мы можем реализовать OAuth 2.0 с GitHub для доступа к API GitHub, полезно понять высокоуровневый поток, с которым мы будем иметь дело.

(A) Перенаправить пользователя из браузера на GitHub: пользователь нажимает кнопку в браузере и перенаправляется на GitHub, где он может предоставить приложению доступ к своей учетной записи GitHub.
(B) Вернуть пользователя из GitHub обратно в браузер: после предоставления пользователь перенаправляется обратно в браузер с помощью code .
(C) Выполните обмен кодом-токеном: отправьте code из браузера на сервер для обмена с GitHub. После обмена мы должны получить ответ access_token от GitHub.
(D) Используйте токен доступа для отправки запросов к API GitHub:С помощью access_token мы теперь можем отправлять запросы к API GitHub от имени пользователя.

Классные штуки. Теперь мы готовы реализовать OAuth 2.0 с GitHub для доступа к API GitHub.

Настройка приложения OAuth в GitHub

Создайте учетную запись на GitHub здесь: https://github.com
Начните с перехода в «Настройки пользователя» > «Настройки разработчика» > «Приложения OAuth», чтобы создать новое приложение GitHub OAuth.

Обратите внимание: если у вас есть организация GitHub, вы можете создать под ней приложение OAuth в разделе «Настройки вашей организации» > «Настройки разработчика» > «Приложения OAuth» > «Новое приложение OAuth для организации».

3. Создайте приложение OAuth.

В форме укажите URL-адрес домашней страницы для вашего собственного домена https://your-domain.com, а для URL-адреса обратного вызова авторизации — https://your-domain.com/integrations/github/oauth2/callback; вы, конечно, можете выбрать свой собственный URL-адрес перенаправления на основе желаемой структуры маршрутизации. Это URL-адрес, на который GitHub перенаправит пользователя обратно после того, как он разрешит приложению доступ к своей учетной записи GitHub.

4. Получите Идентификатор клиента и создайте новый Секрет клиента для вашего приложения GitHub OAuth; держите их под рукой.

Настройка вашего веб-приложения для работы с приложением GitHub OAuth.

5. Перенаправьте пользователя на GitHub из интерфейса вашего веб-приложения.

Во внешнем интерфейсе вашего веб-приложения создайте кнопку, при нажатии которой инициируется поток OAuth 2.0, перенаправляя пользователей на GitHub, чтобы они могли войти в систему и предоставить веб-приложению доступ к своей учетной записи GitHub. Обработчик кнопки должен содержать следующую логику:

// the client id from github
const client_id = ""

// create a CSRF token and store it locally
const state = crypto.randomBytes(16).toString("hex");
localStorage.setItem("latestCSRFToken", state);
    
// redirect the user to github
const link = `https://github.com/login/oauth/authorize?client_id=${client_id}&response_type=code&scope=repo&redirect_uri=${window.location.origin}/integrations/github/oauth2/callback&state=${state}`;
window.location.assign(link);

Здесь мы генерируем токен CSRF, который будет сохранен в локальном хранилище и отправлен в GitHub в качестве параметра state; это связано с смягчением атаки межсайтовой подделки запросов (CSRF), которая выходит за рамки этой статьи.

Обратите внимание: вам следует заменить redirect_uri в link на тот, который вы зарегистрировали на шаге 2 в GitHub. Когда пользователи нажимают кнопку, они должны быть перенаправлены на GitHub, как показано ниже:

6. Проверьте параметр state при перенаправлении пользователя обратно в веб-приложение и отправьте code на серверную часть.

Поскольку GitHub перенаправит пользователя обратно на redirect_uri после того, как он войдет в систему и предоставит веб-приложению доступ к своей учетной записи GitHub, вам необходимо создать для него страницу для обработки следующей части потока OAuth 2.0. Здесь redirect_uri будет иметь параметры code и state; вам следует проанализировать эти параметры из URL-адреса и убедиться, что параметр state соответствует токену CSRF в локальном хранилище из шага 4. Если все в порядке, вы можете приступить к отправке code в серверную часть веб-приложения для выполнения обмена code-token.

const { code, state } = queryString.parse(router.asPath.split("?")[1]);

// validate the state parameter
if (state !== localStorage.getItem("latestCSRFToken") {
  localStorage.removeItem("latestCSRFToken");
  // send the code to the backend
  const res = await axios.post("/api/oauth-token", {
    code
  });
}

7. Обменяйте code на access_token .

Теперь в серверной части вашего приложения вам следует выполнить обмен токенами кода с конечной точкой API GitHub.

const res = await axios.get(
  "https://github.com/login/oauth/access_token", 
  {
    params: {
      client_id: process.env.GITHUB_CLIENT_ID,
      client_secret: process.env.GITHUB_CLIENT_SECRET,
      code: code,
      redirect_uri: `your-domain/integrations/github/oauth2/callback`,
    },
    headers: {
      "Accept": "application/json",
      "Accept-Encoding": "application/json",
    },
  }
);

const access_token = res.data.access_token;

8. Используйте access_token для доступа к API GitHub от имени пользователя.

Теперь вы можете получить доступ к API GitHub от имени пользователя, включив access_token в запросы, отправляемые к API.

Вот и все!

Теперь вы знаете, как настроить приложение для аутентификации с помощью API GitHub с использованием OAuth.

Советы

Правильная реализация OAuth 2.0 имеет решающее значение для безопасности вашего приложения и пользователей.

Вот несколько практических советов, которые вам следует иметь в виду:

Не записывайте Идентификатор клиента и Секрет клиента для своего приложения где-либо в базе кода. Вместо этого вам следует безопасно хранить как Идентификатор клиента, так и Секрет клиента вашего приложения, предпочтительно в виде переменных среды приложения. Более того, вам следует рассмотреть возможность хранения этих учетных данных в секретном менеджере, таком как Infisical, и возвращать их обратно на сервер во время выполнения.
Не выполняйте обмен кодом-токеном OAuth несколько раз. Обмен должен выполняться один раз, после чего вам следует управлять токенами доступа для выполнения всех последующих запросов к API службы. Поскольку с этими токенами следует обращаться безопасно, как и в моем предыдущем совете, вам также следует рассмотреть возможность хранения их в секретном менеджере.

— -

Infisical — платформа управления секретами с открытым исходным кодом.

Infisical (9,4 тыс.+ ⭐️) помогает тысячам команд и организаций хранить и синхронизировать секреты внутри своей команды и инфраструктуры.

Репозиторий GitHub: https://github.com/Infisical/infisical