Google стремится продвигать расовое равенство для чернокожих сообществ. Смотри как.
Эта страница переведена с помощью Cloud Translation API.
Switch to English

OpenID Connect

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

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, щелкните следующий текст: Выберите учетные данные . В открывшемся окне выберите свой проект и необходимые учетные данные, затем нажмите « Просмотр» .

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

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

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

URI перенаправления, который вы установили в API Console, определяет, куда 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 , который ваше приложение включает в свой запрос аутентификации . Вы также можете использовать области для запроса доступа к другим API Google.

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

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

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

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

Снимок экрана страницы согласия

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

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

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

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

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

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

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

Серверный поток

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

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

1. Создайте токен состояния защиты от подделки.

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

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

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

PHP

Чтобы использовать этот пример, необходимо загрузить клиентскую библиотеку API Google для 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
));

Ява

Чтобы использовать этот пример, необходимо загрузить клиентскую библиотеку API Google для 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);

Python

Чтобы использовать этот образец, необходимо загрузить клиентскую библиотеку 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 Console Credentials page.
  • response_type , который в базовом запросе потока кода авторизации должен быть code . (Подробнее см. response_type .)
  • scope , которым в базовом запросе должен быть openid email . (Подробнее см. В scope .)
  • redirect_uri должен быть конечной точкой HTTP на вашем сервере, которая получит ответ от Google. Значение должно точно соответствовать одному из авторизованных URI перенаправления для клиента OAuth 2.0, который вы настроили в API Console Credentials page. Если это значение не соответствует авторизованному URI, запрос завершится ошибкой redirect_uri_mismatch .
  • state должно включать значение уникального токена сеанса защиты от подделки, а также любую другую информацию, необходимую для восстановления контекста, когда пользователь возвращается в ваше приложение, например, начальный URL. (Подробнее в state .)
  • nonce - это случайное значение, генерируемое вашим приложением, которое включает защиту от воспроизведения, если она присутствует.
  • login_hint может быть адрес электронной почты пользователя или sub строка, которая эквивалентна пользователя Google ID. Если вы не предоставили login_hint а пользователь в настоящее время вошел в систему, на экране согласия будет содержаться запрос на утверждение, чтобы login_hint адрес электронной почты пользователя вашему приложению. (Подробнее читайте на login_hint .)
  • Используйте параметр hd чтобы оптимизировать поток OpenID Connect для пользователей определенного домена G Suite. (Подробнее читайте на 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

Чтобы использовать этот пример, необходимо загрузить клиентскую библиотеку API Google для 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);
}

Ява

Чтобы использовать этот пример, необходимо загрузить клиентскую библиотеку API Google для 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.");
}

Python

Чтобы использовать этот образец, необходимо загрузить клиентскую библиотеку 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 метаданных token_endpoint . В следующем обсуждении предполагается, что конечной точкой является https://oauth2.googleapis.com/token . Запрос должен включать в себя следующие параметры в теле POST :

Поля
code Код авторизации, возвращаемый при первоначальном запросе .
client_id Идентификатор клиента, полученный от API Console Credentials page, как описано в разделе Получение учетных данных OAuth 2.0 .
client_secret Секрет клиента, полученный от API Console Credentials page, как описано в разделе Получение учетных данных OAuth 2.0 .
redirect_uri Авторизованный URI перенаправления для данного client_id указанного в API Console Credentials 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 доступа, предоставляемые access_token выражаются в виде списка строк, разделенных пробелами и чувствительных к регистру.
token_type Определяет тип возвращаемого токена. В настоящее время это поле всегда имеет значение Bearer .
refresh_token (по желанию)

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

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

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

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

Полезная нагрузка 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 всегда Аудитория, для которой предназначен этот идентификатор. Это должен быть один из идентификаторов клиента 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 Хеш токена доступа. Обеспечивает проверку того, что токен доступа привязан к токену удостоверения. Если маркер ID выдается со значением access_token в потоке сервера, это утверждение всегда включается. Это утверждение можно использовать как альтернативный механизм для защиты от атак с подделкой межсайтовых запросов, но если вы выполните шаги 1 и 3, нет необходимости проверять токен доступа.
azp client_id авторизованного докладчика. Это утверждение требуется только в том случае, если сторона, запрашивающая токен ID, не совпадает с аудиторией токена ID. Это может иметь место в Google для гибридных приложений, когда веб-приложение и приложение Android имеют разные client_id OAuth 2.0, но используют один и тот же проект API Google.
email Электронный адрес пользователя. Это значение может не быть уникальным для данного пользователя и не подходит для использования в качестве первичного ключа. Предоставляется только в том случае, если ваша область действия включает значение области email .
email_verified Истина, если адрес электронной почты пользователя подтвержден; в противном случае - ложь.
family_name Фамилия (и) или фамилия (и) пользователя. Может быть предоставлен при наличии заявки на name .
given_name Имя (имена) или имя (имена) пользователя. Может быть предоставлен при наличии заявки на name .
hd Размещенный домен G Suite пользователя. Предоставляется только в том случае, если пользователь принадлежит к размещенному домену.
locale Локаль пользователя, представленная тегом языка BCP 47 . Может быть предоставлен при наличии заявки на name .
name Полное имя пользователя в отображаемой форме. Может быть предоставлен, когда:
  • В объем запроса включена строка «профиль».
  • Идентификационный токен возвращается после обновления токена

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

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

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

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

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

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, пока пользователь не присутствует в вашем приложении. Чтобы запросить токен обновления, добавьте access_type параметра access_type значение offline в запросе аутентификации .

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

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

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

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

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

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

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

Параметр Обязательный Описание
client_id (Обязательный) Строка идентификатора клиента, которую вы получаете от API Console Credentials page, как описано в разделе Получение учетных данных OAuth 2.0 .
nonce (Обязательный) Случайное значение, генерируемое вашим приложением, которое включает защиту от воспроизведения.
response_type (Обязательный) Если значением является code , запускает поток кода базовой авторизации , требующий POST для конечной точки токена для получения токенов. Если значение - token id_token или id_token token , запускает неявный поток , требующий использования JavaScript в URI перенаправления для извлечения токенов из идентификатора URI #fragment .
redirect_uri (Обязательный) Определяет, куда отправляется ответ. Значение этого параметра должно точно соответствовать одному из разрешенных значений перенаправления, которые вы установили в API Console Credentials page (включая схему 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 .
display (По желанию) Строковое значение ASCII для указания того, как сервер авторизации отображает страницы пользовательского интерфейса аутентификации и согласия. Следующие значения указаны и принимаются серверами Google, но не влияют на его поведение: page , popup , touch и wap .
hd (По желанию)

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

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

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

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

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

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

  • consent

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

  • select_account

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

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

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

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

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

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

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

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

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

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

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

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

tokeninfo точка tokeninfo полезна для отладки, но для производственных целей tokeninfo открытые ключи Google из конечной точки ключей и выполняйте проверку локально. Вы должны получить URI ключей из документа Discovery, используя jwks_uri метаданных 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_endpoint . Ответ userinfo включает информацию о пользователе, как описано в OpenID Connect Standard Claims и claims_supported метаданных claims_supported документа Discovery. Пользователи или их организации могут по своему усмотрению предоставить или скрыть определенные поля, поэтому вы можете не получить информацию для каждого поля для ваших разрешенных областей доступа.

Документ открытия

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

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

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

Чтобы использовать службы OpenID Connect от Google, необходимо жестко прописать URI документа обнаружения ( 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

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