Использовать модель кода

Библиотека Google Identity Services позволяет пользователям запрашивать код авторизации у Google, используя всплывающее окно в браузере или пользовательский интерфейс Redirect. Это запускает защищенный процесс OAuth 2.0 и приводит к созданию токена доступа, используемого для вызова API Google от имени пользователя.

Сводка потока кода авторизации OAuth 2.0:

  • Владелец учетной записи Google с помощью жеста, например нажатия кнопки, запрашивает в браузере код авторизации у Google.
  • Google отвечает, отправляя уникальный код авторизации либо на обратный вызов в вашем веб-приложении JavaScript, работающем в браузере пользователя, либо напрямую вызывает конечную точку вашего кода авторизации, используя перенаправление браузера.
  • На вашей бэкэнд-платформе размещена конечная точка кода авторизации, и она получает этот код. После проверки этот код обменивается на токены доступа и обновления для каждого пользователя с помощью запроса к конечной точке токена Google.
  • Google проверяет код авторизации, подтверждает, что запрос поступил с вашей защищенной платформы, выдает токены доступа и обновления, а также возвращает токены, вызывая конечную точку входа, размещенную на вашей платформе.
  • Ваша конечная точка входа получает токены доступа и обновления, надежно сохраняя токен обновления для последующего использования.

Предпосылки

Следуйте инструкциям в разделе «Настройка» , чтобы настроить экран согласия OAuth, получить идентификатор клиента и загрузить клиентскую библиотеку.

Инициализировать клиент кода

Метод google.accounts.oauth2.initCodeClient() инициализирует код клиента.

Вы можете поделиться кодом авторизации, используя режим перенаправления или всплывающего окна. В режиме перенаправления вы размещаете конечную точку авторизации OAuth2 на своем сервере, и Google перенаправляет пользователя-агента на эту конечную точку, передавая код авторизации как параметр URL. В режиме всплывающего окна вы определяете обработчик обратного вызова JavaScript, который отправляет код авторизации на ваш сервер. Всплывающий режим можно использовать для обеспечения бесперебойной работы пользователя, не покидая ваш сайт.

Чтобы инициализировать клиент для:

  • Перенаправьте UX-поток, установите для ux_mode значение redirect , а для redirect_uri укажите конечную точку кода авторизации вашей платформы. Значение должно точно соответствовать одному из авторизованных URI перенаправления для клиента OAuth 2.0, настроенных в Google Cloud Console. Оно также должно соответствовать правилам валидации URI перенаправления .

  • В потоке UX-всплывающего окна установите для параметра ux_mode значение popup , а для параметра callback — имя функции, которая будет использоваться для отправки кодов авторизации на вашу платформу. Значение redirect_uri по умолчанию соответствует источнику страницы, вызывающей initCodeClient . Это значение используется далее в потоке при обмене кода авторизации на токен доступа или обновления. Например, https://www.example.com/index.html вызывает initCodeClient , а источник: https://www.example.com — значение redirect_url .

Защита от CSRF-атак

Для предотвращения атак типа «подделка межсайтовых запросов» (CSRF) в режимах Redirect и Popup используются несколько отличающиеся методы взаимодействия между пользовательским интерфейсом. В режиме Redirect используется параметр состояния OAuth 2.0. Подробнее о создании и проверке параметра состояния см. в разделе 10.12 RFC6749 «Подделка межсайтовых запросов» . В режиме Popup вы добавляете к своим запросам собственный HTTP-заголовок, а затем на сервере проверяете его соответствие ожидаемому значению и источнику.

Выберите режим UX, чтобы просмотреть фрагмент кода, показывающий код авторизации и обработку CSRF:

Режим перенаправления

Инициализируйте клиент, при котором Google перенаправляет браузер пользователя на вашу конечную точку аутентификации, передавая код аутентификации в качестве параметра URL.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'redirect',
  redirect_uri: 'https://oauth2.example.com/code',
  state: 'YOUR_BINDING_VALUE'
});

Инициализируйте клиент, в котором пользователь начинает процесс авторизации во всплывающем диалоговом окне. После получения согласия Google возвращает код авторизации в браузер пользователя с помощью функции обратного вызова. Запрос POST от обработчика обратного вызова JS доставляет код авторизации в конечную точку на внутреннем сервере, где он сначала проверяется, а затем выполняется оставшаяся часть процесса OAuth.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'popup',
  callback: (response) => {
    const xhr = new XMLHttpRequest();
    xhr.open('POST', "https://oauth2.example.com/code", true);
    xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
    // Set custom header for CRSF
    xhr.setRequestHeader('X-Requested-With', 'XmlHttpRequest');
    xhr.onload = function() {
      console.log('Auth code response: ' + xhr.responseText);
    };
    xhr.send('code=' + response.code);
  },
});

Поток кода триггера OAuth 2.0

Вызовите метод requestCode() клиента кода, чтобы запустить поток пользователя:

<button onclick="client.requestCode();">Authorize with Google</button>

Для этого пользователю потребуется войти в учетную запись Google и дать согласие на совместное использование отдельных областей, прежде чем возвращать код авторизации либо в конечную точку перенаправления, либо в обработчик обратных вызовов.

Обработка кода авторизации

Google генерирует уникальный код авторизации для каждого пользователя, который вы получаете и проверяете на своем внутреннем сервере.

Для режима Popup обработчик, указанный параметром callback , работающий в браузере пользователя, передает код авторизации в конечную точку, размещенную на вашей платформе.

В режиме перенаправления GET запрос отправляется на конечную точку, указанную в redirect_uri , с кодом авторизации в параметре URL code . Чтобы получить код авторизации:

  • Создайте новую конечную точку авторизации , если у вас нет существующей реализации, или

  • Обновите существующую конечную точку, чтобы она принимала запросы GET и параметры URL. Ранее использовался запрос PUT со значением кода авторизации в полезной нагрузке.

Конечная точка авторизации

Конечная точка вашего кода авторизации должна обрабатывать запросы GET со следующими параметрами строки запроса URL:

Имя Ценить
authuser Запрос на аутентификацию при входе пользователя в систему
код Код авторизации OAuth2, сгенерированный Google
hd Размещенный домен учетной записи пользователя
быстрый Диалог согласия пользователя
объем Список из одной или нескольких областей OAuth2, подлежащих авторизации, разделенных пробелами
состояние Переменная состояния CRSF

Пример запроса GET с параметрами URL к конечной точке с именем auth-code , размещенной на example.com:

Request URL: https://www.example.com/auth-code?state=42a7bd822fe32cc56&code=4/0AX4XfWiAvnXLqxlckFUVao8j0zvZUJ06AMgr-n0vSPotHWcn9p-zHCjqwr47KHS_vDvu8w&scope=email%20profile%20https://www.googleapis.com/auth/calendar.readonly%20https://www.googleapis.com/auth/photoslibrary.readonly%20https://www.googleapis.com/auth/contacts.readonly%20openid%20https://www.googleapis.com/auth/userinfo.email%20https://www.googleapis.com/auth/userinfo.profile&authuser=0&hd=example.com&prompt=consent

Когда поток кода авторизации инициируется более ранними библиотеками JavaScript или прямыми вызовами конечных точек Google OAuth 2.0, используется запрос POST .

Пример POST запроса, содержащего код авторизации в качестве полезной нагрузки в теле HTTP-запроса:

Request URL: https://www.example.com/auth-code
Request Payload: 4/0AX4XfWhll-BMV82wi4YwbrSaTPaRpUGpKqJ4zBxQldU\_70cnIdh-GJOBZlyHU3MNcz4qaw

Подтвердить запрос

Чтобы избежать CSRF-атак, выполните на своем сервере следующие действия.

Проверьте значение параметра состояния для режима перенаправления.

Убедитесь, что заголовок X-Requested-With: XmlHttpRequest установлен для всплывающего режима.

Затем вам следует приступить к получению токенов обновления и доступа от Google, только если вы предварительно успешно подтвердили запрос кода авторизации.

Получить доступ и обновить токены

После того как ваша внутренняя платформа получит код авторизации от Google и проверит запрос, используйте код авторизации для получения доступа и обновления токенов от Google для выполнения вызовов API.

Следуйте инструкциям, начиная с Шага 5: Обмен кода авторизации на токены обновления и доступа из руководства Использование OAuth 2.0 для приложений веб-сервера .

Управление токенами

Ваша платформа безопасно хранит токены обновления. Удаляйте сохранённые токены обновления при удалении учётных записей пользователей или отзыве их согласия через google.accounts.oauth2.revoke или напрямую через https://myaccount.google.com/permissions .

При желании вы можете рассмотреть возможность использования RISC для защиты учетных записей пользователей с помощью Cross-Account Protection .

Как правило, ваша бэкенд-платформа обращается к API Google, используя токен доступа. Если ваше веб-приложение также будет напрямую обращаться к API Google из браузера пользователя, необходимо реализовать способ передачи токена доступа вашему веб-приложению. Это выходит за рамки данного руководства. При использовании этого подхода и клиентской библиотеки Google API для JavaScript используйте gapi.client.SetToken() для временного хранения токена доступа в памяти браузера и разрешите библиотеке вызывать API Google.