OpenID Connect

Конечная точка OpenID Connect от Google сертифицирована OpenID.

API OAuth 2.0 от Google можно использовать как для аутентификации, так и для авторизации. В этом документе описывается наша реализация OAuth 2.0 для аутентификации, которая соответствует спецификации OpenID Connect и сертифицирована OpenID . Документация, содержащаяся в разделе Использование OAuth 2.0 для доступа к API Google, также применима к этой службе. Если вы хотите изучить этот протокол в интерактивном режиме, мы рекомендуем Google OAuth 2.0 Playground . Чтобы получить помощь на Stack Overflow , помечайте свои вопросы тегом «google-oauth».

Настройка OAuth 2.0

Прежде чем ваше приложение сможет использовать систему аутентификации Google OAuth 2.0 для входа пользователей, вам необходимо настроить проект в для получения учетных данных OAuth 2.0, установите URI перенаправления и (необязательно) настройте информацию о брендинге, которую ваши пользователи видят на экране согласия пользователя. Вы также можете использовать для с��зд��ния ��четной записи служб��, включения выставления счетов, настройки фильтрации и выполнения других задач. Для получения более подробной информации см. Помощь .

Получите учетные данные OAuth 2.0

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

Чтобы просмотреть идентификатор клиента и секрет клиента для заданных учетных данных OAuth 2.0, щелкните следующий текст: Выберите учетные данные . В открывшемся окне выберите свой проект и необходимые учетные данные, затем нажмите « Просмотр» .

Или просмотрите свой идентификатор клиента и секрет клиента со страницы учетных данных в API Console :

  1. Go to the Credentials page.
  2. Нажмите на имя вашего удостоверения или значок карандаша ( ). Ваш идентификатор клиента и секретные данные находятся вверху страницы.

Установить URI перенаправления

URI перенаправления, который вы установили в определяет, куда Google отправляет ответы на ваши запросы аутентификации .

Чтобы создать, просмотреть или изменить URI перенаправления для заданных учетных данных OAuth 2.0, выполните следующие действия:

  1. Go to the Credentials page.
  2. В разделе идентификаторов клиентов OAuth 2.0 на странице щелкните учетные данные.
  3. Просмотр или редактирование URI перенаправления.

Если на странице «Учетные данные» нет раздела идентификаторов клиентов OAuth 2.0 , значит, у вашего проекта нет учетных данных OAuth. Чтобы создать его, нажмите « Создать учетные данные» .

Настройте экран согласия пользователя

Для ваших пользователей опыт аутентификации OAuth 2.0 включает экран согласия, который описывает информацию, которую пользователь раскрывает, и условия, которые применяются. Например, когда пользователь входит в систему, ��го могут попросить предоставить вашему приложению доступ к его адресу электронной почты и базовой информации об учетной записи. Вы запрашиваете доступ к этой информации с помощью параметра scope , который ваше приложение включает в свой запрос аутентификации . Вы также можете использовать scopes для запроса доступа к другим API Google.

Экран согласия пользователя также представляет информацию о брендинге, такую ​​как название вашего продукта, логотип и URL домашней страницы. Вы контролируете информацию о брендинге в .

Чтобы включить экран согласия вашего проекта:

  1. Откройте Consent Screen page в Google API Console .
  2. If prompted, select a project, or create a new one.
  3. Заполните форму и нажмите Сохранить .

В следующем диалоговом окне согласия показано, что увидит пользователь, если в запросе присутствует комбинация областей действия OAuth 2.0 и Google Drive. (Этот общий диалог был создан с использованием Google OAuth 2.0 Playground , поэтому он не включает в себя информацию о брендинге, которая будет установлена ​​в .)

Пример страницы согласия
Рисунок 1. Скриншот страницы согласия

Доступ к услуге

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

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

Аутентификация пользователя

Аутентификация пользователя включает получение токена ID и его проверку. Токены ID — это стандартизированная функция OpenID Connect , разработанная для использования при обмене утверждениями об идентичности в Интернете.

Наиболее часто используемые подходы для аутентификации пользователя и получения токена ID называются потоком «сервера» и потоком «неявного» сервера. Поток сервера позволяет внутреннему серверу приложения проверять личность человека с помощью браузера или мобильного устройства. Неявный поток используется, когда клиентскому приложению (обычно приложению JavaScript, работающему в браузере) необходимо получить доступ к API напрямую, а не использовать свой внутренний сервер.

В этом документе описывается, как выполнить серверный поток для аутентификации пользователя. Неявный поток значительно сложнее из-за рисков безопасности при обработке и использовании токенов на стороне клиента. Если вам необходимо реализовать неявный поток, мы настоятельно рекомендуем использовать Google Identity Services .

Поток сервера

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

  1. Создать государственный токен, защищающий от подделки
  2. Отправить запрос аутентификации в Google
  3. Подтвердите токен состояния защиты от подделки
  4. Обмен code на токен доступа и идентификационный токен
  5. Получить информацию о пользователе из токена ID
  6. Аутентификация пользователя

1. Создать государственный токен, защищающий от подделки

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

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

Следующий код демонстрирует генерацию уникальных токенов сеанса.

PHP

Чтобы использовать этот пример, вам необходимо загрузить клиентскую библиотеку Google API для PHP .

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
$state = bin2hex(random_bytes(128/8));
$app['session']->set('state', $state);
// Set the client ID, token state, and application name in the HTML while
// serving it.
return $app['twig']->render('index.html', array(
    'CLIENT_ID' => CLIENT_ID,
    'STATE' => $state,
    'APPLICATION_NAME' => APPLICATION_NAME
));

Ява

Чтобы использовать этот пример, вам необходимо загрузить клиентскую библиотеку Google API для Java .

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
String state = new BigInteger(130, new SecureRandom()).toString(32);
request.session().attribute("state", state);
// Read index.html into memory, and set the client ID,
// token state, and application name in the HTML before serving it.
return new Scanner(new File("index.html"), "UTF-8")
    .useDelimiter("\\A").next()
    .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID)
    .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state)
    .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}",
    APPLICATION_NAME);

Питон

Чтобы использовать этот пример, вам необходимо загрузить клиентскую библиотеку Google API для Python .

# Create a state token to prevent request forgery.
# Store it in the session for later validation.
state = hashlib.sha256(os.urandom(1024)).hexdigest()
session['state'] = state
# Set the client ID, token state, and application name in the HTML while
# serving it.
response = make_response(
    render_template('index.html',
                    CLIENT_ID=CLIENT_ID,
                    STATE=state,
                    APPLICATION_NAME=APPLICATION_NAME))

2. Отправьте запрос на аутентификацию в Google

Следующий шаг — формирование HTTPS-запроса GET с соответствующими параметрами URI. Обратите внимание на использование HTTPS вместо HTTP на всех этапах этого процесса; HTTP-подключения отклоняются. Вам следует получить базовый URI из документа Discovery, используя значение метаданных authorization_endpoint . В следующем обсуждении предполагается, что базовый URI — https://accounts.google.com/o/oauth2/v2/auth .

Для базового запроса укажите следующие параметры:

  • client_id , который вы получаете из .
  • response_type , который в базовом запросе потока кода авторизации должен быть code . (Подробнее см. в response_type .)
  • scope , которая в базовом запросе должна быть openid email . (Подробнее см. в scope .)
  • redirect_uri должен быть конечной точкой HTTP на вашем сервере, которая получит ответ от Google. Значение должно точно соответствовать одному из авторизованных URI перенаправления для клиента OAuth 2.0, который вы настроили в Credentials page. Если это значение не соответствует авторизованному URI, запрос завершится ошибкой redirect_uri_mismatch .
  • state должен включать значение уникального токена сеанса, защищающего от подделки, а также любую другую информацию, необходимую для восстановления контекста, когда пользователь возвращается в ваше приложение, например, начальный URL-адрес. (Подробнее см. в state .)
  • nonce — это случайное значение, генерируемое вашим приложением, которое при наличии включает защиту от повторного воспр��изведения.
  • login_hint может быть адресом электронной почты пользователя или sub , которая эквивалентна идентификатору Google пользователя. Если вы не предоставите login_hint и пользователь войдет в систему, экран согласия будет включать запрос на одобрение для передачи адреса электронной почты пользователя в ваше приложение. (Подробнее см. на login_hint .)
  • Используйте параметр hd для оптимизации потока OpenID Connect для пользователей определенного домена, связанного с организацией Google Workspace или Cloud (подробнее см. на hd ).

Вот пример полного URI аутентификации OpenID Connect с переносами строк и пробелами для удобства чтения:

https://accounts.google.com/o/oauth2/v2/auth?
 response_type=code&
 client_id=424911365001.apps.googleusercontent.com&
 scope=openid%20email&
 redirect_uri=https%3A//oauth2.example.com/code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=jsmith@example.com&
 nonce=0394852-3190485-2490358&
 hd=example.com

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

3. Подтвердите статус токена защиты от подделки

Ответ отправляется на redirect_uri , который вы указали в запросе . Все ответы возвращаются в строке запроса:

https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email

На сервере вы должны подтвердить, что state полученное от Google, соответствует токену сеанса, созданному вами на шаге 1. Эта круговая проверка помогает убедиться, что запрос делает пользователь, а не вредоносный скрипт.

Следующий код демонстрирует подтверждение токенов сеанса, созданных на шаге 1:

PHP

Чтобы использовать этот пример, вам необходимо загрузить клиентскую библиотеку Google API для PHP .

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if ($request->get('state') != ($app['session']->get('state'))) {
  return new Response('Invalid state parameter', 401);
}

Ява

Чтобы использовать этот пример, вам необходимо загрузить клиентскую библиотеку Google API для Java .

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if (!request.queryParams("state").equals(
    request.session().attribute("state"))) {
  response.status(401);
  return GSON.toJson("Invalid state parameter.");
}

Питон

Чтобы использовать этот пример, вам необходимо загрузить клиентскую библиотеку Google API для Python .

# Ensure that the request is not a forgery and that the user sending
# this connect request is the expected user.
if request.args.get('state', '') != session['state']:
  response = make_response(json.dumps('Invalid state parameter.'), 401)
  response.headers['Content-Type'] = 'application/json'
  return response

4. Обмен code на токен доступа и идентификационный токен

Ответ включает параметр code , одноразовый код авторизации, который ваш сервер может обменять на токен доступа и токен идентификатора. Ваш сервер выполняет этот обмен, отправляя запрос HTTPS POST . Запрос POST отправляется в конечную точку токена, которую вы должны получить из документа Discovery с помощью значения метаданных token_endpoint . В следующем обсуждении предполагается, что конечная точка — https://oauth2.googleapis.com/token . Запрос должен включать следующие параметры в теле POST :

Поля
code Код авторизации, возвращаемый из первоначального запроса .
client_id Идентификатор клиента, который вы получаете от , как описано в разделе Получение учетных данных OAuth 2.0 .
client_secret Секрет клиента, который вы получаете от , как описано в разделе Получение учетных данных OAuth 2.0 .
redirect_uri Авторизованный URI перенаправления для данного client_id , указанного в , как описано в разделе Установка URI перенаправления .
grant_type Это поле должно содержать значение authorization_code , как определено в спецификации OAuth 2.0 .

Фактический запрос может выглядеть следующим образом:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your-client-id&
client_secret=your-client-secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

Успешный ответ на этот запрос содержит следующие поля в массиве JSON:

Поля
access_token Токен, который можно отправить в API Google.
expires_in Оставшееся время жизни токена доступа в секундах.
id_token JWT , содержащий идентификационную информацию о пользователе, имеющую цифровую подпись Google.
scope Области доступа, предоставляемые access_token , выраженные в виде списка разделенных пробелами строк с учетом регистра.
token_type Определяет тип возвращаемого токена. В настоящее время это поле всегда имеет значение Bearer .
refresh_token (необязательный)

Это поле присутствует только в том случае, если параметр access_type был установлен на offline в запросе аутентификации . Подробности см. в разделе Refresh tokens .

5. Получить информацию о пользователе из токена ID

Идентификационный токен — это JWT (JSON Web Token), то есть криптографически подписанный объект JSON, закодированный в Base64. Обычно крайне важно, чтобы вы проверили идентификационный токен перед его использованием, но поскольку вы напрямую общаетесь с Google по каналу HTTPS без посредников и используете свой клиентский секрет для аутентификации в Google, вы можете быть уверены, что полученный вами токен действительно исходит от Google и является действительным. Если ваш сервер передает идентификационный токен другим компонентам вашего приложения, крайне важно, чтобы другие компоненты проверили токен перед его использованием.

Поскольку большинство библиотек API объединяют проверку с работой по декодированию значений, закодированных в base64url, и анализом JSON внутри, вам, скорее всего, в любом случае придется проверять токен при доступе к утверждениям в токене ID.

Полезная нагрузка токена ID

Идентификационный токен — это объект JSON, содержащий набор пар имя/значение. Вот пример, отформатированный для удобства чтения:

{
  "iss": "https://accounts.google.com",
  "azp": "1234987819200.apps.googleusercontent.com",
  "aud": "1234987819200.apps.googleusercontent.com",
  "sub": "10769150350006150715113082367",
  "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
  "hd": "example.com",
  "email": "jsmith@example.com",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

Токены Google ID могут содержать следующие поля (известные как утверждения ):

Требовать Предоставил Описание
aud всегда Аудитория, для которой предназначен этот токен ID. Это должен быть один из идентификаторов клиента OAuth 2.0 вашего приложения.
exp всегда Время истечения срока действия, после которого токен ID не должен быть принят. Представлено в формате Unix epoch time (целое число секунд).
iat всегда Время выдачи токена ID. Представлено в формате Unix epoch time (целое число секунд).
iss всегда Идентификатор эмитента для эмитента ответа. Всегда https://accounts.google.com или accounts.google.com для токенов Google ID.
sub всегда Идентификатор пользователя, уникальный среди всех учетных записей Google и никогда не используемый повторно. Учетная запись Google может иметь несколько адресов электронной почты в разные моменты времени, но значение sub никогда не меняется. Используйте sub в своем приложении в качестве уникального идентификатора ключа для пользователя. Максимальная длина 255 символов ASCII с учетом регистра.
at_hash Хэш токена доступа. Обеспечивает проверку того, что токен доступа привязан к токену идентификации. Если токен идентификатора выдается со значением access_token в потоке сервера, это утверждение всегда включается. Это утверждение можно использовать в качестве альтернативного механизма для защиты от атак с подделкой межсайтовых запросов, но если вы выполните шаги 1 и 3, то нет необходимости проверять токен доступа.
azp client_id авторизованного докладчика. Это утверждение необходимо только в том случае, если сторона, запрашивающая токен ID, не совпадает с аудиторией токена ID. Это может быть в случае с гибридными приложениями Google, где веб-приложение и приложение Android имеют разные OAuth 2.0 client_id , но совместно используют один и тот же проект API Google.
email Адрес электронной почты пользователя. Предоставляется только в том случае, если вы включили область действия email в свой запрос. Значение этого утверждения может быть не уникальным для этой учетной записи и может меняться со временем, поэтому вам не следует использовать это значение в качестве основного идентификатора для ссылки на вашу запись пользователя. Вы также не можете полагаться на домен утверждения email для идентификации пользователей организаций Google Workspace или Cloud; вместо этого используйте утверждение hd .
email_verified True, если адрес электронной почты пользователя проверен; в противном случае false.
family_name Фамилия(и) или имя(и) пользователя. Может быть предоставлено, если присутствует претензия name .
given_name Имя(имена) или первое(имена) пользователя. Может быть предоставлено, если присутствует претензия name .
hd Домен, связанный с организацией Google Workspace или Cloud пользователя. Предоставляется только в том случае, если пользователь принадлежит к организации Google Cloud. Вы должны проверить это утверждение при ограничении доступа к ресурсу только для членов определенных доменов. Отсутстви�� этого утверждения у��а��ы��ает ��а то, что учетная запись не принадлежит к домену, размещенному Google.
locale Локаль пользователя, представленная тегом языка BCP 47. Может быть предоставлена ​​при наличии заявки name .
name Полное имя пользователя в отображаемой форме. Может быть предоставлено, когда:
  • В область запроса включена строка «профиль»
  • Идентификационный токен возвращается из обновления токена.

Когда присутствуют утверждения name , вы можете использовать их для обновления записей пользователя вашего приложения. Обратите внимание, что это утверждение никогда не гарантируется.

nonce Значение nonce , предоставленное вашим приложением в запросе аутентификации. Вы должны защититься от атак повторного воспроизведения, представив это значение только один раз.
picture URL-адрес изображения профиля пользователя. Может быть предоставлен, когда:
  • В область запроса включена строка «профиль»
  • Идентификационный токен возвращается из обновления токена.

Когда присутствуют претензии picture , вы можете использовать их для обновления записей пользователей вашего приложения. Обратите внимание, что это требование никогда не гарантируется.

profile URL страницы профиля пользователя. Может быть предоставлен, когда:
  • В область запроса включена строка «профиль»
  • Идентификационный токен возвращается из обновления токена.

При наличии утверждений profile вы можете использовать их для обновления записей пользователя вашего приложения. Обратите внимание, что это утверждение никогда не гарантируется.

6. Аутентификация пользователя.

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

Если пользователь отсутствует в вашей базе данных пользователей, вам следует перенаправить пользователя на страницу регистрации нового пользователя. Вы можете автоматически зарегистрировать пользователя на основе информации, которую вы получаете от Google, или, по крайней мере, вы можете предварительно заполнить многие поля, которые вам требуются в вашей регистрационной форме. В дополнение к информации в токене ID вы можете получить дополнительную информацию о профиле пользователя в наших конечных точках профиля пользователя.

Продвинутые темы

В следующих разделах более подробно описывается API Google OAuth 2.0. Эта информация предназначена для разработчиков с расширенными требованиями к аутентификации и авторизации.

Доступ к другим API Google

Одним из преимуществ использования OAuth 2.0 для аутентификации является то, что ваше приложение может получить разрешение на использование других API Google от имени пользователя (например, YouTube, Google Drive, Calendar или Contacts) одновременно с аутентификацией пользователя. Для этого включите другие необходимые области в запрос аутентификаци�� , который вы отправляете в Google. Например, чтобы добавить возрастную группу пользователя в ваш запрос аутентификации, передайте параметр области openid email https://www.googleapis.com/auth/profile.agerange.read . Пользователь получает соответствующий запрос на экране согласия . Токен доступа, который вы получите обратно от Google, позволит вашему приложению получить доступ ко всем API, связанным с областями доступа, которые вы запросили и получили.

Обновить токены

В вашем запросе на доступ к API вы можете запросить токен обновления, который будет возвращен во время обмена code . Токен обновления обеспечивает вашему приложению непрерывный доступ к API Google, пока пользователь не присутствует в вашем приложении. Чтобы запросить токен обновления, добавьте параметр access_type в offline в вашем запросе аутентификации .

Соображения:

  • Обязательно сохраните токен обновления в безопасном и постоянном месте, поскольку получить токен обновления можно только при первом выполнении процедуры обмена кодами.
  • Существуют ограничения на количество выдаваемых токенов обновления: один лимит на комбинацию клиент/пользователь и еще один на пользователя по всем клиентам. Если ваше приложение запрашивает слишком много токенов обновления, оно может столкнуться с этими ограничениями, и в этом случае старые токены обновления перестанут работать.

Для получения дополнительной информации см. Обновление токена доступа (автономный доступ) .

Вы можете предложить пользователю повторно авторизовать ваше приложение, установив параметр prompt на consent в вашем запросе аутентификации . Если prompt=consent включен, экран согласия отображается каждый раз, когда ваше приложение запр��шивает авторизацию областей доступа, даже если все области ранее были предоставлены вашему проекту API Google. По этой причине включайте prompt=consent только при необходимости.

Дополнительную информацию о параметре prompt см. в разделе prompt в таблице параметров URI аутентификации .

Параметры URI аутентификации

В следующей таблице приведены более полные описания параметров, принимаемых API аутентификации Google OAuth 2.0.

Параметр Необходимый Описание
client_id (Необходимый) Строка идентификатора клиента, которую вы получаете от , как описано в разделе Получение учетных данных OAuth 2.0 .
nonce (Необходимый) Случайное значение, генерируемое вашим приложением, которое включает защиту от повторного воспроизведения.
response_type (Необходимый) Если значение равно code , запускает поток Basic authorization code , требующий POST к конечной точке токена для получения токенов. Если значение равно token id_token или id_token token , запускает неявный поток , требующий использования JavaScript в URI перенаправления для получения токенов из URI #fragment identifier .
redirect_uri (Необходимый) Определяет, куда отправляется ответ. Значение этого параметра должно точно соответствовать одному из разрешенных значений перенаправления, которые вы установили в (включая схему HTTP или HTTPS, регистр и завершающий символ «/», если таковой имеется).
scope (Необходимый)

Параметр области действия должен начинаться со значения openid , а затем включать значение profile , значение email или и то, и другое.

Если значение области действия profile присутствует, токен идентификатора может (но не гарантируется) включать ��т��ер��дения profile пользователя по умолчанию.

Если значение области действия email присутствует, токен идентификатора включает утверждения email и email_verified .

В дополнение к этим специфичным для OpenID областям действия ваш аргумент области действия может также включать другие значения области действия. Все значения области действия должны быть разделены пробелами. Например, если вы хотите пофайловый доступ к Google Диску пользователя, ваш параметр области действия может быть openid profile email https://www.googleapis.com/auth/drive.file .

Информацию о доступных областях действия см. в разделе Области действия OAuth 2.0 для API Google или в документации по API Google, который вы хотели бы использовать.

state (Необязательно, но настоятельно рекомендуется)

Непрозрачная строка, которая передается по протоколу; то есть она возвращается как параметр URI в базовом потоке и как идентификатор URI #fragment в неявном потоке.

state может быть полезным для сопоставления запросов и ответов. Поскольку ваш redirect_uri можно угадать, использование значения state может повысить вашу уверенность в том, что входящее соединение является результатом запроса аутентификации, инициированного вашим приложением. Если вы сгенерируете случайную строку или закодируете хэш некоторого состояния клиента (например, cookie) в этой переменной state , вы можете проверить ответ, чтобы убедиться, что запрос и ответ были созданы в одном и том же браузере. Это обеспечивает защиту от атак, таких как подделка межсайтовых запросов.

access_type (Необязательный) Допустимые значения — offline и online . Эффект задокументирован в Offline Access ; если запрашивается токен доступа, клиент не получает токен обновления, если не указано значение offline .
display (Необязательный) Строковое значение ASCII для указания того, как сервер авторизации отображает страницы пользовательского интерфейса аутентификации и согласия. Следующие значения указаны и приняты серверами Google, но не оказывают никакого влияния на поведение потока протокола: page , popup , touch и wap .
hd (Необязательный)

Оптимизируйте процесс входа для учетных записей, принадлежащих организации Google Cloud. Включив домен организации Google Cloud (например, mycollege.edu ), вы можете указать, что пользовательский интерфейс выбора учетной записи должен быть оптимизирован для учетных записей в этом домене. Чтобы оптимизировать учетные записи организации Google Cloud в целом, а не только для одного домена организации Google Cloud, задайте значение звездочки ( * ): hd=* .

Не полагайтесь на эту оптимизацию пользовательского интерфейса для управления тем, кто может получить доступ к вашему приложению, поскольку запросы на стороне клиента могут быть изменены. Обязательно проверьте , что возвращаемый токен ID имеет значение утверждения hd , которое соответствует вашим ожиданиям (например, mycolledge.edu ). В отличие от параметра запроса, утверждение hd токена ID содержится в токене безопасности от Google, поэтому этому значению можно доверять.

include_granted_scopes (Необязательный) Если этот параметр имеет значение true и запрос на авторизацию удовлетворен, то авторизация будет включать все предыдущие авторизации, предоставленные этой комбинации пользователя/приложения для других областей действия; см. Инкрементная авторизация .

Обратите внимание, что вы не можете выполнить инкрементную авторизацию с помощью потока установленных приложений.

login_hint (Необязательный) Когда ваше приложение знает, какого пользователя оно пытается аутентифицировать, оно может предоставить этот параметр в качестве подсказки серверу аутентификации. Передача этой подсказки подавляет выбор учетной записи и либо предварительно заполняет поле электронной почты �� форме входа, либо выбирает правильный сеанс (если пользователь использует множественный вход ), что может помочь вам избежать проблем, которые могут возникнуть, если ваше приложение входит в неправильную учетную запись пользователя. Значением может быть либо адрес электронной почты, либо sub , которая эквивалентна идентификатору Google пользователя.
prompt (Необязательный) Список строковых значений, разделенных пробелами, который определяет, запрашивает ли сервер авторизации у пользователя повторную аутентификацию и согласие. Возможные значения:
  • none

    Сервер авторизации не отображает экраны аутентификации или согласия пользователя; он вернет ошибку, если пользователь еще не аутентифицирован и не настроил предварительно согласие для запрошенных областей. Вы можете использовать none для проверки существующей аутентификации и/или согласия.

  • consent

    Сервер авторизации запрашивает у пользователя согласие, прежде чем вернуть информацию клиенту.

  • select_account

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

Если значение не указано и пользователь ранее не авторизовал доступ, то пользователю будет показан экран согласия.

Проверка идентификационного токена

Вам необходимо проверить все токены ID на вашем сервере, если вы не уверены, что они пришли напрямую от Google. Например, ваш сервер должен проверить как подлинные любые токены ID, которые он получает от ваших клиентских приложений.

Ниже приведены распространенные ситуации, в которых вы можете отправлять идентификационные токены на свой сервер:

  • Отправка токенов ID с запросами, которые необходимо аутентифицировать. Токены ID сообщают вам, какой именно пользователь сделал запрос и какому клиенту был предоставлен этот токен ID.

Идентификационные токены являются конфиденциальными и могут быть использованы не по назначению в случае перехвата. Вы должны гарантировать, что эти токены обрабатываются безопасно, передавая их ��олько по HTTPS и используя только данные POST или в заголовках запросов. Если вы храните идентификационные токены на своем сервере, вы также должны хранить их безопасно.

Одной из вещей, которая делает токены ID полезными, является тот факт, что вы можете передавать их между различными компонентами вашего приложения. Эти компоненты могут использовать токен ID как легкий механизм аутентификации, аутентифицирующий приложение и пользователя. Но прежде чем вы сможете использовать информацию в токене ID или полагаться на нее как на утверждение, что пользователь прошел аутентификацию, вы должны ее проверить.

Проверка идентификационного токена требует нескольких шагов:

  1. Проверьте, что токен ID правильно подписан эмитентом. Токены, выпущенные Google, подписаны с использованием одного из сертификатов, найденных в URI, указанном в значении метаданных jwks_uri документа Discovery .
  2. Убедитесь, что значение утверждения iss в токене идентификатора равно https://accounts.google.com или accounts.google.com .
  3. Убедитесь, что значение утверждения aud в токене ID равно идентификатору клиента вашего приложения.
  4. Убедитесь, что срок действия ( exp claim) токена ID не истек.
  5. Если вы указали значение параметра hd в запросе, убедитесь, что токен ID имеет утверждение hd , которое соответствует принятому домену, связанному с организацией Google Cloud.

Шаги 2–5 включают только сравнение строк и дат, что довольно просто, поэтому мы не будем их здесь подробно описывать.

Первый шаг более сложен и включает проверку криптографической подписи. Для отладки вы можете использовать конечную точку tokeninfo от Google для сравнения с локальной обработкой, реализованной на вашем сервере или устройстве. Предположим, что значение вашего токена ID равно XYZ123 . Затем вы разыменовываете URI https://oauth2.googleapis.com/tokeninfo?id_token= XYZ123 . Если подпись токена действительна, ответом будет полезная нагрузка JWT в ее декодированной форме объекта JSON.

Конечная точка tokeninfo полезна для отладки, но для производственных целей извлеките открытые ключи Google из конечной точки ключей и выпол��ите ��роверку ��окально. ��ам следует извлечь URI ключей из документа Discovery, используя значение метаданных jwks_uri . Запросы к конечной точке отладки могут быть ограничены или иным образом подвержены периодическим ошибкам.

Поскольку Google меняет свои открытые ключи лишь изредка, вы можете кэшировать их с помощью директив кэширования HTTP-ответа и, в подавляющем большинстве случаев, выполнять локальную проверку гораздо эффективнее, чем с помощью конечной точки tokeninfo . Эта проверка требует извлечения и анализа сертификатов, а также выполнения соответствующих криптографических вызовов для проверки подписи. К счастью, существуют хорошо отлаженные библиотеки, доступные на самых разных языках, для выполнения этого (см. jwt.io ).

Получение информации о профиле пользователя

Чтобы получить дополнительную информацию о профиле пользователя, вы можете использовать токен доступа (который ваше приложение получает во время процесса аутентификации ) и стандарт OpenID Connect :

  1. Для обеспечения совместимости с OpenID необходимо включить значения области openid profile в запрос на аутентификацию .

    Если вы хотите, чтобы адрес электронной почты пользователя был включен, вы можете указать дополнительное значение области email . Чтобы указать и profile , и email , вы можете включить следующий параметр в URI запроса аутентификации:

    scope=openid%20profile%20email
  2. Добавьте свой токен доступа в заголовок авторизации и выполните HTTPS GET запрос к конечной точке userinfo, которую следует извлечь из документа Discovery с помощью значения метаданных userinfo_endpoint . Ответ userinfo включает информацию о пользователе, как описано в OpenID Connect Standard Claims и значении метаданных claims_supported документа Discovery. Пользователи или и�� организации могут выбрать предоставление или удержание определенных полей, поэтому вы можете не получить информацию для каждого поля для ваших авторизованных областей доступа.

Документ Discovery

Протокол OpenID Connect требует использования нескольких конечных точек для аутентификации пользователей и запроса ресурсов, включая токены, информацию о пользователях и открытые ключи.

Для упрощения реализации и повышения гибкости OpenID Connect позволяет использовать «Документ обнаружения», документ JSON, находящийся в известном месте и содержащий пары ключ-значение, которые предоставляют сведения о конфигурации поставщика OpenID Connect, включая URI авторизации, токена, отзыва, информации о пользователе и конечных точек открытых ключей. Документ обнаружения для сервиса OpenID Connect от Google можно получить из:

https://accounts.google.com/.well-known/openid-configuration

Чтобы использовать службы OpenID Connect от Google, вам следует жестко закодировать URI Discovery-document ( https://accounts.google.com/.well-known/openid-configuration ) в вашем приложении. Ваше приложение извлекает документ, применяет правила кэширования в ответе, а затем извлекает из него URI конечных точек по мере необходимости. Например, для аутентификации пользователя ваш код извлечет значение метаданных authorization_endpoint ( https://accounts.google.com/o/oauth2/v2/auth в примере ниже) в качестве базового URI для запросов аутентификации, отправляемых в Google.

Вот пример такого документа; имена полей указаны в OpenID Connect Discovery 1.0 (см. этот документ для их значений). Значения приведены исключительно в иллюстративных целях и могут измениться, хотя они скопированы из последней версии фактического документа Google Discovery:

{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code token",
    "code id_token",
    "token id_token",
    "code token id_token",
    "none"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ],
  "claims_supported": [
    "aud",
    "email",
    "email_verified",
    "exp",
    "family_name",
    "given_name",
    "iat",
    "iss",
    "locale",
    "name",
    "picture",
    "sub"
  ],
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ]
}

Вы можете избежать HTTP-обхода, кэшируя значения из документа Discovery. Используются стандартные заголовки кэширования HTTP, и их следует соблюдать.

Клиентские библиотеки

Следующие клиентские библиотеки упрощают реализацию OAuth 2.0 за счет интеграции с популярными фреймворками:

Соответствие OpenID Connect

Система аутентификации OAuth от Google 2.0 поддерживает необходимые функции спецификации ядра Connect Connect . Любой клиент, который предназначен для работы с OpenID Connect, должен взаимодействовать с этой службой (за исключением объекта OpenID запроса ).