API-интерфейсы Google OAuth 2.0 можно использовать как для аутентификации, так и для авторизации. В этом документе описывается наша реализация 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 для входа в систему, вам необходимо настроить проект в Google API Console чтобы получить учетные данные OAuth 2.0, установите URI перенаправления и (необязательно) настройте информацию о брендинге, которую ваши пользователи видят на экране согласия пользователя. Вы также можете использовать API Console для создания сервисной учетной записи, включения биллинга, настройки фильтрации и выполнения других задач. Более подробную информацию см. Google API ConsoleПомощь .
Получите учетные данные OAuth 2.0.
Вам нужны учетные данные OAuth 2.0, включая идентификатор клиента и секрет клиента, для аутентификации пользователей и получения доступа к API Google.
要查看给定OAuth 2.0凭据的客户端ID和客户端密钥，请单击以下文本： 选择凭据 。在打开的窗口中，选择您的项目和所需的凭证，然后单击“ 查看” 。
或者，从API Console的“ 凭据”页面中查看您的客户端ID和客户端密钥：
- Go to the Credentials page.
- 单击您的凭证名称或铅笔（ create ）图标。您的客户ID和密码位于页面顶部。
Установите URI перенаправления
URI перенаправления, который вы установили в API Console определяет, куда Google отправляет ответы на ваши запросы аутентификации .
要创建，查看或编辑给定OAuth 2.0凭据的重定向URI，请执行以下操作：
- Go to the Credentials page.
- 在页面的OAuth 2.0客户端ID部分中，点击一个凭据。
- 查看或编辑重定向URI。
如果“凭据”页面上没有OAuth 2.0客户端ID部分，则您的项目没有OAuth凭据。要创建一个，点击创建凭证 。
Настройте экран согласия пользователя
Для ваших пользователей процесс аутентификации OAuth 2.0 включает экран согласия, на котором описывается информация, которую пользователь раскрывает, и применимые условия. Например, когда пользователь входит в систему, его могут попросить предоставить вашему приложению доступ к его адресу электронной почты и основной информации об учетной записи. Вы запрашиваете доступ к этой информации, используя параметр scope , который ваше приложение включает в свой запрос аутентификации . Вы также можете использовать области для запроса доступа к другим API Google.
На экране согласия пользователя также отображается информация о бренде, такая как название вашего продукта, логотип и URL-адрес домашней страницы. Вы контролируете информацию о брендинге в API Console.
要启用项目的同意屏幕：
- 在Consent Screen page中打开Google API Console 。
- If prompted, select a project, or create a new one.
- 填写表格，然后点击保存 。
В следующем диалоговом окне согласия показано, что увидит пользователь, если в запросе присутствует комбинация областей OAuth 2.0 и Google Drive. (Это общее диалоговое окно было создано с использованием Google OAuth 2.0 Playground , поэтому оно не включает информацию о брендинге, которая была бы установлена в API Console.)
Доступ к услуге
Google и третьи лица предоставляют библиотеки, которые вы можете использовать для решения многих деталей реализации аутентификации пользователей и получения доступа к API Google. Примеры включают Google Identity Services и клиентские библиотеки Google , которые доступны для различных платформ.
Если вы решите не использовать библиотеку, следуйте инструкциям в оставшейся части этого документа, где описаны потоки HTTP-запросов, лежащие в основе доступных библиотек.
Аутентификация пользователя
Аутентификация пользователя включает получение идентификационного токена и его проверку. Токены идентификатора — это стандартизированная функция OpenID Connect, предназначенная для использования при обмене утверждениями личности в Интернете.
Наиболее часто используемые подходы для аутентификации пользователя и получения идентификационного токена называются «серверным» потоком и «неявным» потоком. Серверный поток позволяет внутреннему серверу приложения проверять личность человека с помощью браузера или мобильного устройства. Неявный поток используется, когда клиентскому приложению (обычно приложению JavaScript, работающему в браузере) требуется доступ к API напрямую, а не через внутренний сервер.
В этом документе описывается, как выполнить серверный поток для аутентификации пользователя. Неявный поток значительно сложнее из-за рисков безопасности при обработке и использовании токенов на стороне клиента. Если вам необходимо реализовать неявный поток, мы настоятельно рекомендуем использовать Google Identity Services .
Процесс сервера
Убедитесь, что вы настроили свое приложение в API Console чтобы позволить ему использовать эти протоколы и аутентифицировать ваших пользователей. Когда пользователь пытается войти в систему через Google, вам необходимо:
- Создайте токен состояния защиты от подделки
- Отправьте запрос на аутентификацию в Google
- Подтвердите токен состояния защиты от подделки
-
codeобмена для токена доступа и токена идентификатора - Получить информацию о пользователе из токена идентификатора
- Аутентификация пользователя
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);
Питон
Чтобы использовать этот пример, вам необходимо загрузить клиентскую библиотеку API Google для 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, который вы получаете из API ConsoleCredentials page. -
response_type, который в базовом запросе потока кода авторизации должен бытьcode. (Подробнее читайте наresponse_type.) -
scope, которая в базовом запросе должна бытьopenid email. (Подробнее читайте вscope».) -
redirect_uriдолжен быть конечной точкой HTTP на вашем сервере, которая получит ответ от Google. Значение должно точно совпадать с одним из авторизованных URI перенаправления для клиента OAuth 2.0, который вы настроили в разделе API ConsoleCredentials page. Если это значение не соответствует авторизованному URI, запрос завершится с ошибкойredirect_uri_mismatch. -
stateдолжно включать значение уникального токена сеанса защиты от подделки, а также любую другую информацию, необходимую для восстановления контекста, когда пользователь возвращается в ваше приложение, например, начальный URL-адрес. (Подробнее читайте наstate.) -
nonce— это случайное значение, генерируемое вашим приложением, которое включает защиту от повтора, если она присутствует. -
login_hintможет быть адресом электронной почты пользователя илиsub, эквивалентной идентификатору Google ID пользователя. Если вы не предоставляете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."); }
Питон
Чтобы использовать этот пример, вам необходимо загрузить клиентскую библиотеку API Google для 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 | Идентификатор клиента, который вы получаете от API ConsoleCredentials page, как описано в разделе Получение учетных данных OAuth 2.0 . |
client_secret | Секрет клиента, который вы получаете от API ConsoleCredentials page, как описано в разделе Получение учетных данных OAuth 2.0 . |
redirect_uri | Авторизованный URI перенаправления для данного client_id , указанного в API ConsoleCredentials page, как описано в разделе Установка 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 | Токен, который можно отправить в Google API. |
expires_in | Оставшийся срок действия токена доступа в секундах. |
id_token | JWT , содержащий идентификационную информацию о пользователе, имеющую цифровую подпись Google. |
scope | Области доступа, предоставляемые access_token выражаются в виде списка строк, разделенных пробелами и чувствительных к регистру. |
token_type | Определяет тип возвращаемого токена. В настоящее время это поле всегда имеет значение Bearer . |
refresh_token | (необязательный) Это поле присутствует только в том случае, если в запросе аутентификации для параметра |
5. Получите информацию о пользователе из идентификационного токена.
Токен идентификатора — это JWT (веб-токен JSON), то есть объект JSON с криптографической подписью в кодировке Base64. Обычно очень важно проверить идентификационный токен перед его использованием, но поскольку вы общаетесь напрямую с Google по каналу HTTPS без посредников и используете свой клиентский секрет для аутентификации в Google, вы можете быть уверены, что токен, который вы используете, Получение действительно исходит от Google и является действительным. Если ваш сервер передает токен идентификатора другим компонентам вашего приложения, чрезвычайно важно, чтобы другие компоненты проверили токен перед его использованием.
Поскольку большинство библиотек API сочетают проверку с работой по декодированию значений в кодировке base64url и анализу JSON внутри, вы, вероятно, в любом случае в конечном итоге будете проверять токен при доступе к утверждениям в токене идентификатора.
Полезная нагрузка токена идентификатора
Токен идентификатора — это объект 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 могут содержать следующие поля (известные как претензии ):
| Требовать | Предоставил | Описание |
|---|---|---|
aud | всегда | Аудитория, для которой предназначен этот идентификационный токен. Это должен быть один из идентификаторов клиента OAuth 2.0 вашего приложения. |
exp | всегда | Срок действия, по истечении которого идентификационный токен не может быть принят. Представлено во времени Unix (целое число секунд). |
iat | всегда | Время выдачи идентификационного токена. Представлено во времени Unix (целое число секунд). |
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 авторизованного докладчика. Это утверждение необходимо только в том случае, если сторона, запрашивающая токен идентификатора, не совпадает с аудиторией токена идентификатора. Это может иметь место в Google для гибридных приложений, где веб-приложение и приложение Android имеют разные OAuth 2.0 client_id , но используют один и тот же проект Google API. | |
email | Адрес электронной почты пользователя. Предоставляется только в том случае, если вы включили в запрос область email . Значение этого утверждения может не быть уникальным для этой учетной записи и может меняться со временем, поэтому вам не следует использовать это значение в качестве основного идентификатора для связи с вашей записью пользователя. Вы также не можете полагаться на домен заявления email для идентификации пользователей организаций Google Workspace или Cloud; вместо этого используйте утверждение hd . | |
email_verified | True, если адрес электронной почты пользователя подтвержден; в противном случае ложь. | |
family_name | Фамилия(и) или фамилия(я) пользователя. Может быть предоставлено при наличии заявки name . | |
given_name | Имя пользователя или имя пользователя. Может быть предоставлено при наличии заявки name . | |
hd | Домен, связанный с организацией Google Workspace или Cloud пользователя. Предоставляется только в том случае, если пользователь принадлежит к организации Google Cloud. Вы должны проверить это утверждение, если доступ к ресурсу разрешен только членам определенных доменов. Отсутствие этого утверждения указывает на то, что учетная запись не принадлежит домену, размещенному в Google. | |
locale | Языковой стандарт пользователя, представленный языковым тегом BCP 47 . Может быть предоставлено при наличии заявки name . | |
name | Полное имя пользователя в отображаемой форме. Может быть предоставлено, когда:
При наличии претензий | |
nonce | Значение nonce предоставленное вашим приложением в запросе аутентификации. Вам следует обеспечить защиту от атак повторного воспроизведения, гарантируя, что оно представлено только один раз. | |
picture | URL-адрес изображения профиля пользователя. Может быть предоставлено, когда:
При наличии претензий | |
profile | URL-адрес страницы профиля пользователя. Может быть предоставлено, когда:
Если имеются утверждения |
6. Аутентификация пользователя
После получения информации о пользователе из токена идентификатора вам следует запросить базу данных пользователей вашего приложения. Если пользователь уже существует в вашей базе данных, вам следует запустить сеанс приложения для этого пользователя, если ответ Google API соответствует всем требованиям для входа в систему.
Если пользователь не существует в вашей базе данных пользователей, вам следует перенаправить его в процесс регистрации нового пользователя. Вы можете иметь возможность автоматически зарегистрировать пользователя на основе информации, которую вы получаете от Google, или, по крайней мере, вы можете предварительно заполнить многие поля, которые вам необходимы в вашей регистрационной форме. Помимо информации в идентификационном токене, вы можете получить дополнительную информацию о профиле пользователя на наших конечных точках профиля пользователя.
Расширенные темы
В следующих разделах API Google OAuth 2.0 описывается более подробно. Эта информация предназначена для разработчиков с расширенными требованиями к аутентификации и авторизации.
Доступ к другим API Google
Одним из преимуществ использования OAuth 2.0 для аутентификации является то, что ваше приложение может получить разрешение на использование других API Google от имени пользователя (например, YouTube, Google Диск, Календарь или Контакты) одновременно с аутентификацией пользователя. Для этого включите другие необходимые области в запрос аутентификации , который вы отправляете в Google. Например, чтобы добавить возрастную группу пользователя в запрос на аутентификацию, передайте параметр области openid email https://www.googleapis.com/auth/profile.agerange.read . Пользователю будет предложено соответствующее сообщение на экране согласия . Токен доступа, который вы получаете обратно от Google, позволяет вам получить доступ ко всем API, связанным с теми объемами доступа, которые вы запросили и получили.
Обновить токены
В своем запросе на доступ к API вы можете запросить токен обновления, который будет возвращен во время обмена code . Токен обновления обеспечивает вашему приложению постоянный доступ к API Google, пока пользователь отсутствует в вашем приложении. Чтобы запросить токен обновления, добавьте в запросе аутентификации значение offline для параметра access_type .
Соображения:
- Обязательно сохраните токен обновления безопасно и навсегда, поскольку вы можете получить токен обновления только при первом выполнении потока обмена кодом.
- Существуют ограничения на количество выдаваемых токенов обновления: одно ограничение на комбинацию клиент/пользователь и другое на пользователя для всех клиентов. Если ваше приложение запрашивает слишком много токенов обновления, оно может столкнуться с этими ограничениями, и в этом случае старые токены обновления перестанут работать.
Дополнительные сведения см. в разделе Обновление токена доступа (автономный доступ) .
Запрос на повторное согласие
Вы можете предложить пользователю повторно авторизовать ваше приложение, установив параметр prompt для consent в вашем запросе аутентификации . Если включен prompt=consent , экран согласия отображается каждый раз, когда ваше приложение запрашивает авторизацию областей доступа, даже если все области ранее были предоставлены вашему проекту API Google. По этой причине включайте prompt=consent только при необходимости.
Дополнительные сведения о параметре prompt см. в разделе prompt в таблице параметров URI аутентификации .
Параметры URI аутентификации
В следующей таблице приведены более полные описания параметров, принимаемых API аутентификации Google OAuth 2.0.
| Параметр | Необходимый | Описание |
|---|---|---|
client_id | (Необходимый) | Строка идентификатора клиента, полученная из API ConsoleCredentials page, как описано в разделе Получение учетных данных OAuth 2.0 . |
nonce | (Необходимый) | Случайное значение, сгенерированное вашим приложением, которое включает защиту от повторного воспроизведения. |
response_type | (Необходимый) | Если значение равно code , запускает поток кода базовой авторизации , требуя POST к конечной точке токена для получения токенов. Если значением является token id_token или id_token token , запускает неявный поток , требующий использования JavaScript в URI перенаправления для получения токенов из идентификатора URI #fragment . |
redirect_uri | (Необходимый) | Определяет, куда отправляется ответ. Значение этого параметра должно точно совпадать с одним из разрешенных значений перенаправления, которые вы установили в API ConsoleCredentials page (включая схему HTTP или HTTPS, регистр и завершающий символ «/», если таковой имеется). |
scope | (Необходимый) | Параметр области должен начинаться со значения Если значение области Если значение области В дополнение к этим специфичным для OpenID областям ваш аргумент области может также включать другие значения области. Все значения области должны быть разделены пробелами. Например, если вам нужен пофайловый доступ к Google Диску пользователя, параметром области действия может быть Информацию о доступных областях см. в разделе «Области действия OAuth 2.0 для API Google» или в документации API Google, который вы хотите использовать. |
state | (Необязательно, но настоятельно рекомендуется) | Непрозрачная строка, которая передается в протоколе; то есть он возвращается как параметр URI в базовом потоке и как идентификатор URI |
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, установите значение звездочки ( Не полагайтесь на эту оптимизацию пользовательского интерфейса для контроля доступа к вашему приложению, поскольку запросы на стороне клиента могут быть изменены. Обязательно убедитесь , что возвращаемый токен идентификатора имеет значение утверждения |
include_granted_scopes | (Необязательный) | Если этому параметру присвоено значение true и запрос на авторизацию предоставлен, авторизация будет включать в себя все предыдущие авторизации, предоставленные этой комбинации пользователя и приложения для других областей; см. Дополнительная авторизация .Обратите внимание, что вы не можете выполнить дополнительную авторизацию с помощью потока установленного приложения. |
login_hint | (Необязательный) | Когда ваше приложение знает, какого пользователя оно пытается аутентифицировать, оно может предоставить этот параметр в качестве подсказки серверу аутентификации. Передача этой подсказки подавляет выбор учетной записи и либо предварительно заполняет поле электронной почты в форме входа, либо выбирает правильный сеанс (если пользователь использует множественный вход ), что может помочь вам избежать проблем, которые могут возникнуть, если ваше приложение входит в неправильную учетную запись пользователя. Значением может быть адрес электронной почты или sub , эквивалентная идентификатору Google ID пользователя. |
prompt | (Необязательный) | Список строковых значений, разделенных пробелами, который указывает, запрашивает ли сервер авторизации пользователя повторную аутентификацию и согласие. Возможные значения:
Если значение не указано и пользователь ранее не авторизовал доступ, пользователю отображается экран согласия. |
Проверка идентификационного токена
Вам необходимо проверить все токены идентификатора на вашем сервере, если вы не уверены, что они получены непосредственно от Google. Например, ваш сервер должен проверять подлинность всех токенов идентификатора, которые он получает от ваших клиентских приложений.
Ниже приведены распространенные ситуации, когда вы можете отправить токены идентификатора на свой сервер:
- Отправка токенов идентификатора с запросами, которые необходимо аутентифицировать. Токены идентификатора сообщают вам, какой именно пользователь сделал запрос, и для какого клиента был предоставлен этот токен идентификатора.
Идентификаторы конфиденциальны и могут быть использованы не по назначению в случае перехвата. Вы должны обеспечить безопасную обработку этих токенов, передавая их только через HTTPS и только через данные POST или в заголовках запросов. Если вы храните токены идентификатора на своем сервере, вы также должны хранить их безопасно.
Одна вещь, которая делает токены идентификаторов полезными, заключается в том, что вы можете передавать их различным компонентам вашего приложения. Эти компоненты могут использовать идентификационный токен в качестве упрощенного механизма аутентификации, проверяющего приложение и пользователя. Но прежде чем вы сможете использовать информацию в токене идентификатора или полагаться на нее как на подтверждение того, что пользователь прошел аутентификацию, вы должны проверить ее.
Проверка идентификационного токена требует нескольких шагов:
- Убедитесь, что токен идентификатора правильно подписан эмитентом. Токены, выпущенные Google, подписываются с использованием одного из сертификатов, найденных по URI, указанному в значении метаданных
jwks_uriдокумента Discovery . - Убедитесь, что значение утверждения
issв токене идентификатора равноhttps://accounts.google.comилиaccounts.google.com. - Убедитесь, что значение утверждения
audв токене идентификатора равно идентификатору клиента вашего приложения. - Убедитесь, что срок действия (утверждение
exp) токена идентификатора не истек. - Если вы указали значение параметра hd в запросе, убедитесь, что токен идентификатора имеет утверждение
hd, соответствующее обслуживаемому домену, связанному с организацией Google Cloud.
Шаги со 2 по 5 включают только сравнения строк и дат, которые довольно просты, поэтому мы не будем их здесь подробно описывать.
Первый шаг более сложен и включает в себя проверку криптографической подписи. В целях отладки вы можете использовать конечную точку tokeninfo Google для сравнения с локальной обработкой, реализованной на вашем сервере или устройстве. Предположим, что значение вашего идентификатора токена — 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 :
Чтобы обеспечить совместимость с OpenID, вы должны включить значения области
openid profileв свой запрос на аутентификацию .Если вы хотите, чтобы адрес электронной почты пользователя был включен, вы можете указать дополнительное значение области
email. Чтобы указать иprofile, иemail, вы можете включить следующий параметр в URI запроса аутентификации:scope=openid%20profile%20email
- Добавьте свой токен доступа в заголовок авторизации и выполните запрос HTTPS
GETк конечной точке userinfo, который вы должны получить из документа Discovery, используя значение метаданныхuserinfo_endpoint. Ответ userinfo включает информацию о пользователе, как описано вOpenID Connect Standard Claimsи значенииclaims_supportedдокумента Discovery. Пользователи или их организации могут решить предоставить или скрыть определенные поля, поэтому вы можете не получить информацию по каждому полю для разрешенных вами областей доступа.
Документ «Дискавери»
Протокол OpenID Connect требует использования нескольких конечных точек для аутентификации пользователей и для запроса ресурсов, включая токены, информацию о пользователе и открытые ключи.
Чтобы упростить реализацию и повысить гибкость, OpenID Connect позволяет использовать «документ Discovery», документ JSON, найденный в известном месте и содержащий пары ключ-значение, которые предоставляют подробную информацию о конфигурации провайдера OpenID Connect, включая URI авторизации. , токен, отзыв, информация о пользователе и конечные точки открытых ключей. Документ Discovery для службы Google OpenID Connect можно получить по адресу:
https://accounts.google.com/.well-known/openid-configuration
Чтобы использовать службы Google OpenID Connect, вам необходимо жестко закодировать URI документа Discovery ( 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 за счет интеграции с популярными платформами:
- Клиентская библиотека API Google для Java
- Клиентская библиотека API Google для Python
- Клиентская библиотека API Google для .NET
- Клиентская библиотека Google API для Ruby
- Клиентская библиотека API Google для PHP
- Библиотека OAuth 2.0 для Google Web Toolkit
- Google Toolbox для контроллеров Mac OAuth 2.0
Соответствие OpenID Connect
Система аутентификации Google OAuth 2.0 поддерживает необходимые функции спецификации OpenID Connect Core . Любой клиент, предназначенный для работы с OpenID Connect, должен взаимодействовать с этой службой (за исключением объекта запроса OpenID ).