OpenID Connect

Google'ın OAuth 2.0 API'leri hem kimlik doğrulama hem de yetkilendirme için kullanılabilir. Bu dokümanda, kimlik doğrulama için OpenID Connect spesifikasyonuna uygun ve OpenID Sertifikalı olan OAuth 2.0 uygulamamız açıklanmaktadır. Google API'lerine Erişmek için OAuth 2.0'ı Kullanma bölümünde yer alan dokümanlar bu hizmet için de geçerlidir. Bu protokolü etkileşimli bir şekilde keşfetmek istiyorsanız Google OAuth 2.0 Playground'u öneririz. Stack Overflow hakkında yardım almak için sorularınızı "google-oauth" ile etiketleyin.

OAuth 2.0 kurulumu

Uygulamanızın, kullanıcı girişi için Google'ın OAuth 2.0 kimlik doğrulama sistemini kullanabilmesi için Google API Console içinde bir proje oluşturarak OAuth 2.0 kimlik bilgilerini almalı, yönlendirme URI'si ayarlamalı ve (isteğe bağlı olarak) kullanıcılarınızın kullanıcı izin ekranında gördüğü marka bilgilerini özelleştirmelisiniz. Hizmet hesabı oluşturmak, faturalandırmayı etkinleştirmek, filtrelemeyi ayarlamak ve diğer görevleri yapmak için de API Console aracını kullanabilirsiniz. Daha fazla bilgi için Google API Console Yardım sayfasına göz atın.

OAuth 2.0 kimlik bilgilerini alma

Kullanıcıların kimliğini doğrulamak ve Google API'lerine erişim elde etmek için istemci kimliği ve istemci gizli anahtarı dahil OAuth 2.0 kimlik bilgilerine ihtiyacınız vardır.

Belirli bir OAuth 2.0 kimlik bilgisinin istemci kimliğini ve istemci sırrını görüntülemek için aşağıdaki metni tıklatın: Kimlik bilgilerini seçin . Açılan pencerede projenizi ve istediğiniz kimlik bilgilerini seçin, ardından Görüntüle'yi tıklayın.

Veya müşteri kimliğinizi ve müşteri sırrınızı API Console Kimlik Bilgileri sayfasından API Console :

  1. Go to the Credentials page.
  2. Kimlik bilgilerinizin adını veya kurşun kalem ( ) simgesini tıklayın. Müşteri kimliğiniz ve sırrınız sayfanın en üstünde.

Yönlendirme URI'si ayarlayın

API Console öğesinde ayarladığınız yönlendirme URI'si, Google'ın kimlik doğrulama isteklerinize yanıtları nereye göndereceğini belirler.

Belirli bir OAuth 2.0 kimlik bilgileri için yönlendirme URI'leri oluşturmak, görüntülemek veya düzenlemek için aşağıdakileri yapın:

  1. Go to the Credentials page.
  2. Sayfanın OAuth 2.0 istemci kimlikleri bölümünde bir kimlik bilgilerini tıklatın.
  3. Yönlendirme URI'lerini görüntüleyin veya düzenleyin.

Kimlik Bilgileri sayfasında OAuth 2.0 istemci kimlikleri bölümü yoksa, projenizde OAuth kimlik bilgileri yoktur. Bir tane oluşturmak için Kimlik bilgileri oluştur'u tıklayın.

Kullanıcı rızası ekranını özelleştirme

Kullanıcılarınız için OAuth 2.0 kimlik doğrulama deneyiminde, kullanıcının yayınladığı bilgileri ve geçerli şartları açıklayan bir izin ekranı bulunur. Örneğin, kullanıcı giriş yaptığında, uygulamanızın e-posta adresine ve temel hesap bilgilerine erişmesine izin vermesi istenebilir. Uygulamanızın kimlik doğrulama isteğine eklediği scope parametresini kullanarak bu bilgilere erişim talep edersiniz. Kapsamları, diğer Google API'lerine erişim istemek için de kullanabilirsiniz.

Kullanıcı izni ekranında ürün adınız, logonuz ve ana sayfanızın URL'si gibi marka bilgileri de sunulur. Marka bilgilerini API Consolebölümünden kontrol edebilirsiniz.

Projenizin onay ekranını etkinleştirmek için:

  1. Consent Screen page yılında Google API Console .
  2. If prompted, select a project, or create a new one.
  3. Formu doldurun ve Kaydet'i tıklayın .

Aşağıdaki izin iletişim kutusunda, OAuth 2.0 ve Google Drive kapsamlarının kombinasyonu mevcut olduğunda kullanıcıların ne göreceği gösterilmektedir. (Bu genel iletişim kutusu Google OAuth 2.0 Playground kullanılarak oluşturulduğu için API Consoleiçinde ayarlanacak marka bilgilerini içermez.)

İzin sayfasının ekran görüntüsü

Hizmete erişme

Google ve üçüncü taraflar, kullanıcıların kimliklerini doğrulama ve Google API'lerine erişmeyle ilgili uygulama ayrıntılarının birçoğuyla ilgilenmek için kullanabileceğiniz kitaplıklar sağlar. Örnekler arasında Google Kimlik Hizmetleri ve çeşitli platformlarda kullanılabilen Google istemci kitaplıkları sayılabilir.

Kitaplığı kullanmamayı tercih ederseniz bu belgenin geri kalanında bulunan, kullanılabilir kitaplıkların temelindeki HTTP isteği akışlarını açıklayan talimatları uygulayın.

Kullanıcının kimliğini doğrulama

Kullanıcının kimliğinin doğrulanması, kimlik jetonu alıp doğrulamayı içerir. Kimlik jetonları, OpenID Connect'in internette kimlik onaylarını paylaşmak için tasarlanmış standart bir özelliğidir.

Kullanıcının kimliğini doğrulamak ve kimlik jetonu almak için en yaygın olarak kullanılan yaklaşımlar "sunucu" akışı ve "örtülü" akış olarak adlandırılır. Sunucu akışı, uygulamanın arka uç sunucusunun bir tarayıcı veya mobil cihaz kullanarak kişinin kimliğini doğrulamasını sağlar. Dolaylı akış, bir istemci tarafı uygulamanın (genellikle tarayıcıda çalışan bir JavaScript uygulaması) API'lere arka uç sunucusu yerine doğrudan erişmesi gerektiğinde kullanılır.

Bu dokümanda, kullanıcının kimliğini doğrulamak için sunucu akışının nasıl gerçekleştirileceği açıklanmaktadır. Örtülü akış, istemci tarafında jetonların işlenmesi ve kullanılmasıyla ilgili güvenlik riskleri nedeniyle çok daha karmaşıktır. Dolaylı bir akış uygulamanız gerekiyorsa Google Kimlik Hizmetleri'ni kullanmanızı önemle tavsiye ederiz.

Sunucu akışı

Bu protokolleri kullanması ve kullanıcılarınızın kimliğini doğrulaması için uygulamanızı API Consoleiçinde ayarladığınızdan emin olun. Bir kullanıcı Google ile giriş yapmaya çalıştığında şunları yapmanız gerekir:

  1. Sahtekarlığa karşı durum jetonu oluşturma
  2. Google'a kimlik doğrulama isteği gönderme
  3. Sahtekarlığa karşı koruma durum jetonunu onaylama
  4. Erişim jetonu ve kimlik jetonu için Exchange code
  5. Kimlik jetonundan kullanıcı bilgilerini alma
  6. Kullanıcının kimliğini doğrulama

1. Sahtekarlığa karşı durum jetonu oluşturma

Sahte istek saldırılarını önleyerek kullanıcılarınızın güvenliğini korumanız gerekir. İlk adım, uygulamanız ile kullanıcının istemcisi arasındaki durumu koruyan benzersiz bir oturum jetonu oluşturmaktır. Daha sonra bu benzersiz oturum jetonunu, Google OAuth Giriş hizmeti tarafından döndürülen kimlik doğrulama yanıtıyla eşleştirerek istekte kullanıcının kötü amaçlı bir saldırgandan değil, kullanıcının istekte bulunduğunu doğrularsınız. Bu jetonlar genellikle siteler arası istek sahtekarlığı (CSRF) jetonları olarak adlandırılır.

Durum jetonu için iyi bir tercih, yüksek kaliteli bir rastgele sayı oluşturma aracı kullanılarak oluşturulan 30 veya daha fazla karakterden oluşan bir dizedir. Bir diğeri, oturum durumu değişkenlerinizden bazılarının arka ucunuzda gizli tutulan bir anahtarla imzalanmasıyla oluşturulan bir karmadır.

Aşağıdaki kod, benzersiz oturum jetonları oluşturmayı göstermektedir.

PHP

Bu örneği kullanmak istiyorsanız PHP için Google API'leri istemci kitaplığını indirmeniz gerekir.

// 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
));

Java

Bu örneği kullanmak istiyorsanız Java için Google API'leri istemci kitaplığını indirmeniz gerekir.

// 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

Bu örneği kullanmak istiyorsanız Python için Google API'leri istemci kitaplığını indirmeniz gerekir.

# 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'a kimlik doğrulama isteği gönderin

Sonraki adım, uygun URI parametreleriyle bir HTTPS GET isteği oluşturmaktır. Bu sürecin tüm adımlarında HTTP yerine HTTPS kullanımına dikkat edin; HTTP bağlantıları reddedilir. Temel URI'yı, authorization_endpoint meta veri değerini kullanarak Keşif belgesinden almanız gerekir. Aşağıdaki açıklamada temel URI'nın https://accounts.google.com/o/oauth2/v2/auth olduğu varsayılır.

Temel bir istek için aşağıdaki parametreleri belirtin:

  • client_id. Bu bilgiyi şu adresten edinebilirsiniz: API Console Credentials page .
  • response_type; temel yetkilendirme kodu akış isteğinde code olmalıdır. (response_type adresinde daha fazla bilgi edinebilirsiniz.)
  • scope; bu, temel bir istekte openid email olmalıdır. (scope adresinde daha fazla bilgi bulabilirsiniz.)
  • redirect_uri, sunucunuzda Google'dan yanıt alacak HTTP uç noktası olmalıdır. Değer, OAuth 2.0 istemcisi için API Console Credentials pageiçinde yapılandırdığınız yetkilendirilmiş yönlendirme URI'lerinden biriyle tam olarak eşleşmelidir. Bu değer, yetkili bir URI ile eşleşmezse istek redirect_uri_mismatch hatasıyla başarısız olur.
  • state, sahtekârlığa karşı benzersiz oturum jetonunun yanı sıra kullanıcı uygulamanıza döndüğünde bağlamı kurtarmak için gereken diğer bilgileri (ör. başlangıç URL'si) içermelidir. (state adresinde daha fazla bilgi bulabilirsiniz.)
  • nonce, uygulamanız tarafından oluşturulan ve mevcut olduğunda tekrar oynatma koruması sağlayan rastgele bir değerdir.
  • login_hint, kullanıcının e-posta adresi veya kullanıcının Google kimliğine denk gelen sub dizesi olabilir. login_hint sağlamazsanız ve kullanıcı şu anda giriş yapmışsa izin ekranında kullanıcının e-posta adresinin uygulamanızda yayınlanması için onay isteği görüntülenir. (Daha fazla bilgi için login_hint adresini ziyaret edin.)
  • Bir Google Workspace veya Cloud kuruluşuyla ilişkili belirli bir alanın kullanıcıları için OpenID Connect akışını optimize etmek üzere hd parametresini kullanın (daha fazla bilgi için hd sayfasına bakın).

Aşağıda, okunabilirlik için satır sonları ve boşluklar içeren eksiksiz bir OpenID Connect kimlik doğrulama URI'sı örneği verilmiştir:

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

Uygulamanız kendileri hakkında yeni bilgiler isterse veya uygulamanız daha önce onaylamadıkları hesap erişimi istiyorsa kullanıcıların izin vermesi gerekir.

3. Sahtekarlığa karşı durum jetonunu onaylayın

Yanıt, istekte belirttiğiniz redirect_uri öğesine gönderilir. Tüm yanıtlar, aşağıda gösterildiği gibi sorgu dizesinde döndürülür:

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

Sunucuda, Google'dan alınan state değerinin 1. adımda oluşturduğunuz oturum jetonuyla eşleştiğini onaylamanız gerekir. Bu gidiş dönüş doğrulama, isteği kötü amaçlı bir komut dosyasının değil, kullanıcının yaptığından emin olunmasına yardımcı olur.

Aşağıdaki kod, 1. adımda oluşturduğunuz oturum jetonlarını onaylama işlemini gösterir:

PHP

Bu örneği kullanmak istiyorsanız PHP için Google API'leri istemci kitaplığını indirmeniz gerekir.

// 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);
}

Java

Bu örneği kullanmak istiyorsanız Java için Google API'leri istemci kitaplığını indirmeniz gerekir.

// 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

Bu örneği kullanmak istiyorsanız Python için Google API'leri istemci kitaplığını indirmeniz gerekir.

# 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. Erişim jetonu ve kimlik jetonu için Exchange code

Yanıt, sunucunuzun bir erişim jetonu ve kimlik jetonuyla değiştirebileceği tek seferlik bir yetkilendirme kodu olan code parametresini içerir. Sunucunuz bu değişimi bir HTTPS POST isteği göndererek gerçekleştirir. POST isteği jeton uç noktasına gönderilir. Bunu, token_endpoint meta veri değerini kullanarak Discovery belgesinden almanız gerekir. Aşağıdaki açıklamada, uç noktanın https://oauth2.googleapis.com/token olduğu varsayılmaktadır. İsteğin POST gövdesinde aşağıdaki parametreleri içermesi gerekir:

Alanlar
code İlk istekten döndürülen yetkilendirme kodu.
client_id OAuth 2.0 kimlik bilgilerini alma bölümünde açıklandığı gibi, Credentials page API Consolehizmetinden edindiğiniz istemci kimliği.
client_secret OAuth 2.0 kimlik bilgilerini alma bölümünde açıklandığı gibi, API Console Credentials pagehizmetinden aldığınız istemci gizli anahtarı.
redirect_uri Yönlendirme URI'si ayarlama bölümünde açıklanan şekilde API Console Credentials pageiçinde belirtilen belirtilen client_id için yetkili yönlendirme URI'si.
grant_type Bu alan, OAuth 2.0 spesifikasyonunda tanımlandığı gibi authorization_code değerini içermelidir.

Asıl istek aşağıdaki örnek gibi görünebilir:

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

Bu isteğe verilen başarılı bir yanıt, bir JSON dizisinde aşağıdaki alanları içerir:

Alanlar
access_token Google API'lerine gönderilebilen bir jeton.
expires_in Erişim jetonunun kalan ömrü (saniye cinsinden).
id_token Kullanıcıyla ilgili kimlik bilgilerini içeren ve Google tarafından dijital olarak imzalanmış bir JWT.
scope access_token tarafından verilen erişim kapsamları, boşlukla sınırlandırılmış, büyük/küçük harfe duyarlı dizelerden oluşan bir liste olarak ifade edilir.
token_type Döndürülen jetonun türünü tanımlar. Şu anda bu alan her zaman Bearer değerini alır.
refresh_token (isteğe bağlı)

Bu alan yalnızca kimlik doğrulama isteğinde access_type parametresi offline olarak ayarlanmışsa mevcuttur. Ayrıntılı bilgi için Yenileme jetonları bölümünü inceleyin.

5. Kimlik jetonundan kullanıcı bilgilerini alma

Kimlik Jetonu bir JWT (JSON Web Jetonu) yani kriptografik olarak imzalanmış Base64 kodlu bir JSON nesnesidir. Normalde, bir kimlik jetonunu kullanmadan önce doğrulamanız çok önemlidir, ancak aracı gerektirmeyen bir HTTPS kanalı üzerinden doğrudan Google ile iletişim kurduğunuzdan ve Google'da kimliğinizi doğrulamak için istemci sırrınızı kullandığınızdan, aldığınız jetonun gerçekten Google'dan geldiğinden ve geçerli olduğundan emin olabilirsiniz. Sunucunuz kimlik jetonunu uygulamanızın diğer bileşenlerine iletiyorsa diğer bileşenlerin jetonu kullanmadan önce jetonu doğrulaması son derece önemlidir.

Çoğu API kitaplığı, doğrulamayı base64url kodlu değerlerin kodunu çözme ve içindeki JSON'u ayrıştırma işlemiyle birleştirdiğinden kimlik jetonundaki hak taleplerine erişirken muhtemelen jetonu yine de doğrularsınız.

Kimlik jetonunun yükü

Kimlik jetonu, bir dizi ad/değer çifti içeren bir JSON nesnesidir. Okunabilirlik için biçimlendirilmiş bir örneği aşağıda bulabilirsiniz:

{
  "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 Kimlik Jetonları aşağıdaki alanları içerebilir (hak talepleri olarak bilinir):

İddia Sağlandı Açıklama
aud always Bu kimlik jetonunun hedeflendiği kitle. Uygulamanızın OAuth 2.0 istemci kimliklerinden biri olmalıdır.
exp always Son kullanma tarihi veya geçtikten sonra kimlik jetonunun kabul edilmemesi gerekir. Unix zamanıyla (saniye cinsinden) temsil edilir.
iat always Kimlik jetonunun verildiği zaman. Unix zamanıyla (tam sayı saniye) gösterilir.
iss always Yanıtı Veren için Düzenleyen Kuruluş Tanımlayıcısı. Google kimlik jetonları için her zaman https://accounts.google.com veya accounts.google.com.
sub always Kullanıcı tanımlayıcısıdır, tüm Google hesaplarında benzersizdir ve hiçbir zaman tekrar kullanılmaz. Bir Google Hesabı, farklı zamanlarda birden fazla e-posta adresine sahip olabilir ancak sub değeri hiçbir zaman değişmez. Uygulamanızda kullanıcının benzersiz tanımlayıcı anahtarı olarak sub kullanın. Büyük/küçük harfe duyarlı maksimum 255 ASCII karakter uzunluğu.
at_hash Erişim jetonu karması. Erişim jetonunun kimlik jetonuna bağlı olduğunun doğrulanmasını sağlar. Kimlik jetonu, sunucu akışında access_token değeriyle verilirse bu hak talebi her zaman dahil edilir. Bu hak talebi, siteler arası istek sahtekarlığı saldırılarına karşı koruma sağlamak için alternatif bir mekanizma olarak kullanılabilir ancak 1. adımı ve 3. adımı uygularsanız erişim jetonunu doğrulamanız gerekmez.
azp Yetkili sunucunun client_id. Bu hak talebi, yalnızca kimlik jetonunu isteyen taraf, kimlik jetonunun kitlesiyle aynı olmadığında gerekir. Bu durum, Google'da web uygulaması ile Android uygulamasının farklı bir OAuth 2.0 client_id değerine sahip olduğu ancak aynı Google API'leri projesini paylaştığı karma uygulamalar için geçerli olabilir.
email Kullanıcının e-posta adresi. Yalnızca isteğinize email kapsamını dahil ettiyseniz sağlanır. Bu hak talebinin değeri, bu hesaba özel olmayabilir ve zaman içinde değişebilir. Bu nedenle, bu değeri kullanıcı kaydınıza bağlantı oluşturmak için birincil tanımlayıcı olarak kullanmamalısınız. Ayrıca, Google Workspace veya Cloud kuruluşlarının kullanıcılarını belirlemek için email hak talebinin alanından yararlanamazsınız. Bunun yerine hd hak talebini kullanın.
email_verified Kullanıcının e-posta adresi doğrulandıysa doğru değerini alır, aksi takdirde yanlış değerini alır.
family_name Kullanıcının soyadı. name hak talebi mevcut olduğunda sağlanabilir.
given_name Kullanıcının adı veya adları. name hak talebi mevcut olduğunda sağlanabilir.
hd Kullanıcının Google Workspace veya Cloud kuruluşuyla ilişkili alan adı. Yalnızca kullanıcı bir Google Cloud kuruluşunda yer alıyorsa sağlanır. Bir kaynağa erişimi yalnızca belirli alanların üyeleriyle kısıtlarken bu hak talebini kontrol etmeniz gerekir. Bu iddianın olmaması, hesabın Google tarafından barındırılan bir alana ait olmadığını gösterir.
locale Kullanıcının BCP 47 dil etiketiyle gösterilen yerel ayarı. name hak talebi mevcut olduğunda sağlanabilir.
name Kullanıcının görüntülenebilir bir biçimde tam adı. Aşağıdaki durumlarda sağlanabilir:
  • İstek kapsamı "profile" dizesini içeriyor
  • Kimlik jetonu, jeton yenilemesinden döndürüldü

name hak talebi varsa uygulamanızın kullanıcı kayıtlarını güncellemek için bunları kullanabilirsiniz. Bu hak talebinin mevcut olacağı garanti edilmez.

nonce Uygulamanızın kimlik doğrulama isteğinde sağladığı nonce değeri. Tekrar oynatma saldırılarına karşı yalnızca bir kez sunulduğundan emin olarak koruma sağlamalısınız.
picture Kullanıcının profil resminin URL'si. Aşağıdaki durumlarda sağlanabilir:
  • İstek kapsamı "profile" dizesini içeriyor
  • Kimlik jetonu, jeton yenilemesinden döndürüldü

picture hak talebi varsa uygulamanızın kullanıcı kayıtlarını güncellemek için bunları kullanabilirsiniz. Bu hak talebinin mevcut olacağı garanti edilmez.

profile Kullanıcının profil sayfasının URL'si. Aşağıdaki durumlarda sağlanabilir:
  • İstek kapsamı "profile" dizesini içeriyor
  • Kimlik jetonu, jeton yenilemesinden döndürüldü

profile hak talebi varsa uygulamanızın kullanıcı kayıtlarını güncellemek için bunları kullanabilirsiniz. Bu hak talebinin mevcut olacağı garanti edilmez.

6. Kullanıcının kimliğini doğrulayın

Kimlik jetonundan kullanıcı bilgilerini aldıktan sonra, uygulamanızın kullanıcı veritabanını sorgulamanız gerekir. Kullanıcı zaten veritabanınızda mevcutsa Google API yanıtı tüm giriş gereksinimlerinin karşılanması durumunda bu kullanıcı için bir uygulama oturumu başlatmanız gerekir.

Kullanıcı kullanıcı veritabanınızda yoksa kullanıcıyı yeni kullanıcı kaydı akışınıza yönlendirmeniz gerekir. Google'dan aldığınız bilgilere göre kullanıcıyı otomatik olarak kaydedebilir veya en azından kayıt formunuzda ihtiyacınız olan alanların birçoğunu önceden doldurabilirsiniz. Kimlik jetonundaki bilgilere ek olarak, kullanıcı profili uç noktalarımızda ek kullanıcı profili bilgileri alabilirsiniz.

İleri düzey konular

Aşağıdaki bölümlerde Google OAuth 2.0 API daha ayrıntılı olarak açıklanmaktadır. Bu bilgi, kimlik doğrulama ve yetkilendirme konusunda ileri düzey gereksinimleri olan geliştiriciler için hazırlanmıştır.

Diğer Google API'lerine erişim

Kimlik doğrulama için OAuth 2.0 kullanmanın avantajlarından biri, kullanıcının kimliğini doğrularken uygulamanızın kullanıcı adına diğer Google API'lerini (YouTube, Google Drive, Takvim veya Kişiler gibi) kullanma izni alabilmesidir. Bunu yapmak için Google'a gönderdiğiniz kimlik doğrulama isteğine ihtiyaç duyduğunuz diğer kapsamları ekleyin. Örneğin, kimlik doğrulama isteğinize kullanıcının yaş grubunu eklemek için openid email https://www.googleapis.com/auth/profile.agerange.read kapsam parametresini iletin. İzin ekranında kullanıcıya uygun bir şekilde istem gösterilir. Google'dan aldığınız erişim jetonu, istediğiniz ve izin verilen erişim kapsamlarıyla ilgili tüm API'lere erişmenizi sağlar.

Jetonları yenile

API erişimi isteğinizde code değişimi sırasında döndürülmesi için bir yenileme jetonu isteyebilirsiniz. Yenileme jetonu, kullanıcı uygulamanızda yokken uygulamanızın Google API'lerine sürekli erişimini sağlar. Yenileme jetonu istemek için kimlik doğrulama isteğinizde access_type parametresini offline olarak ayarlayın.

Dikkat etmeniz gereken noktalar:

  • Yenileme jetonunu yalnızca kod değişimi akışını ilk kez gerçekleştirdiğinizde alabileceğiniz için yenileme jetonunu güvenli ve kalıcı bir şekilde sakladığınızdan emin olun.
  • Yayınlanan yenileme jetonlarının sayısına yönelik sınırlar vardır: istemci/kullanıcı kombinasyonu başına bir sınır ve tüm istemcilerde kullanıcı başına bir sınır. Uygulamanız çok fazla yenileme jetonu isterse bu sınırlarla karşılaşabilir ve bu durumda eski yenileme jetonları çalışmayı durdurur.

Daha fazla bilgi için Erişim jetonunu yenileme (çevrimdışı erişim) bölümüne göz atın.

Kimlik doğrulama isteğinizde prompt parametresini consent olarak ayarlayarak kullanıcıdan uygulamanızı yeniden yetkilendirmesini isteyebilirsiniz. prompt=consent dahil edildiğinde, tüm kapsamlar daha önce Google API'leri projenize verilmiş olsa bile uygulamanız erişim kapsamları için her yetkilendirme istediğinde izin ekranı görüntülenir. Bu nedenle, prompt=consent öğesini yalnızca gerektiğinde ekleyin.

prompt parametresi hakkında daha fazla bilgi için Kimlik doğrulama URI'si parametreleri tablosundaki prompt bölümüne bakın.

Kimlik doğrulama URI'si parametreleri

Aşağıdaki tabloda, Google'ın OAuth 2.0 kimlik doğrulama API'si tarafından kabul edilen parametrelerle ilgili daha kapsamlı açıklamalar verilmiştir.

Parametre Gerekli Açıklama
client_id (Zorunlu) OAuth 2.0 kimlik bilgilerini alma bölümünde açıklandığı gibi, API Console Credentials pagekaynağından aldığınız istemci kimliği dizesi.
nonce (Zorunlu) Uygulamanız tarafından oluşturulan ve tekrar oynatma korumasını etkinleştiren rastgele bir değer.
response_type (Zorunlu) Değer code ise Temel yetkilendirme kodu akışını başlatır ve jetonları almak için jeton uç noktasına POST gönderilmesini gerektirir. Değer token id_token veya id_token token ise Dolaylı akış başlatır. Bu da URI #fragment tanımlayıcısından jeton almak için yönlendirme URI'sında JavaScript'in kullanılmasını gerektirir.
redirect_uri (Zorunlu) Yanıtın nereye gönderileceğini belirler. Bu parametrenin değeri, API Console Credentials page içinde ayarladığınız yetkili yönlendirme değerlerinden biriyle tam olarak eşleşmelidir(HTTP veya HTTPS şeması, büyük/küçük harf ve varsa sondaki "/" dahil).
scope (Zorunlu)

Kapsam parametresi, openid değeriyle başlamalı ve ardından profile değerini, email değerini veya her ikisini de içermelidir.

profile kapsam değeri mevcutsa kimlik jetonu, kullanıcının varsayılan profile hak taleplerini içerebilir (ancak olacağı garanti edilmez).

email kapsam değeri varsa kimlik jetonu email ve email_verified hak taleplerini içerir.

Kapsam bağımsız değişkeniniz, OpenID'ye özgü bu kapsamlara ek olarak başka kapsam değerleri de içerebilir. Tüm kapsam değerleri boşlukla ayrılmalıdır. Örneğin, bir kullanıcının Google Drive'ına dosya başına erişim istiyorsanız kapsam parametreniz openid profile email https://www.googleapis.com/auth/drive.file olabilir.

Kullanılabilir kapsamlar hakkında bilgi edinmek için Google API'leri için OAuth 2.0 Kapsamları bölümüne veya kullanmak istediğiniz Google API'si ile ilgili dokümanlara bakın.

state (İsteğe bağlıdır, ancak kesinlikle önerilir)

Protokolde döngüye alınan opak bir dize. Diğer bir deyişle, Temel akışta URI parametresi olarak ve Örtük akışta URI #fragment tanımlayıcısında döndürülür.

state, isteklerin ve yanıtların ilişkilendirilmesi açısından yararlı olabilir. redirect_uri değerinin tahmin edilebilmesi, state değerinin kullanılması, gelen bağlantının uygulamanız tarafından başlatılan bir kimlik doğrulama isteğinin sonucu olduğuna dair güveninizi artırabilir. Bu state değişkeninde rastgele bir dize oluşturur veya bazı istemci durumlarının karmasını (ör. bir çerez) kodlarsanız yanıtı doğrulayarak ayrıca isteğin ve yanıtın aynı tarayıcıdan kaynaklandığından emin olabilirsiniz. Bu sayede, siteler arası istek sahtekarlığı gibi saldırılara karşı koruma sağlanır.

access_type (İsteğe bağlı) offline ve online değerlerine izin verilir. Etki Çevrimdışı Erişim bölümünde açıklanmıştır. Bir erişim jetonu isteniyorsa istemci, offline değeri belirtilmediği sürece yenileme jetonu almaz.
display (İsteğe bağlı) Yetkilendirme sunucusunun kimlik doğrulama ve izin kullanıcı arayüzü sayfalarını nasıl görüntülediğini belirten bir ASCII dize değeri. Aşağıdaki değerler, Google sunucuları tarafından belirtilir ve kabul edilir ancak bu değerlerin davranışı üzerinde herhangi bir etkisi yoktur: page, popup, touch ve wap.
hd (İsteğe bağlı)

Google Cloud kuruluşlarına ait hesapların giriş işlemini kolaylaştırın. Google Cloud kuruluş alanını (örneğin, mycollege.edu) dahil ederek hesap seçimi kullanıcı arayüzünün bu alandaki hesaplar için optimize edilmesi gerektiğini belirtebilirsiniz. Tek bir Google Cloud kuruluş alanı yerine genellikle Google Cloud kurumsal hesapları için optimizasyon yapmak istiyorsanız yıldız işareti (*) değeri belirleyin: hd=*.

İstemci tarafı istekleri değiştirilebilir. Bu nedenle, uygulamanıza kimlerin erişebileceğini kontrol etmek için bu kullanıcı arayüzü optimizasyonuna güvenmeyin. Döndürülen kimlik jetonunun beklediğinizle (ör.mycolledge.edu) eşleşen bir hd hak talebi değerine (ör. mycolledge.edu) sahip olduğunu validate emin olun. İstek parametresinden farklı olarak, kimlik jetonu hd talebi Google'ın sağladığı bir güvenlik jetonunun içinde yer aldığı için değer güvenilir olabilir.

include_granted_scopes (İsteğe bağlı) Bu parametre true değeriyle sağlanırsa ve yetkilendirme isteği verilirse yetkilendirme, diğer kapsamlar için bu kullanıcı/uygulama kombinasyonuna verilen önceki yetkilendirmeleri içerir. Artımlı yetkilendirme bölümüne bakın.

Yüklü Uygulama akışıyla artımlı yetkilendirme yapamayacağınızı unutmayın.

login_hint (İsteğe bağlı) Uygulamanız hangi kullanıcının kimliğini doğrulamaya çalıştığını bilirse bu parametreyi kimlik doğrulama sunucusuna ipucu olarak sağlayabilir. Bu ipucu iletildiğinde hesap seçici devre dışı bırakılır ve oturum açma formundaki e-posta kutusu önceden doldurulur ya da uygun oturum seçilir (kullanıcı çoklu oturum açma özelliğini kullanıyorsa) ve böylece uygulamanız yanlış kullanıcı hesabıyla giriş yaptığında ortaya çıkabilecek sorunlardan kaçınabilirsiniz. Değer, bir e-posta adresi veya kullanıcının Google kimliğine denk olan sub dizesi olabilir.
prompt (İsteğe bağlı) Yetkilendirme sunucusunun kullanıcıdan yeniden kimlik doğrulama ve izin isteyip istemeyeceğini belirten, boşlukla sınırlandırılmış bir dize değerleri listesidir. Olası değerler şunlardır:
  • none

    Yetkilendirme sunucusu, herhangi bir kimlik doğrulama veya kullanıcı izin ekranı görüntülemez. Kullanıcının kimliği henüz doğrulanmamışsa ve istenen kapsamlar için önceden yapılandırılmamışsa bir hata döndürür. Mevcut kimlik doğrulama ve/veya izni kontrol etmek için none uygulamasını kullanabilirsiniz.

  • consent

    Yetkilendirme sunucusu, bilgileri istemciye döndürmeden önce kullanıcıdan izin ister.

  • select_account

    Yetkilendirme sunucusu, kullanıcıdan bir kullanıcı hesabı seçmesini ister. Böylece, yetkilendirme sunucusunda birden fazla hesap bulunan kullanıcılar, şu anda oturum açmış olabilecekleri birden fazla hesap arasından seçim yapabilir.

Değer belirtilmemişse ve kullanıcı daha önce erişim yetkisi vermediyse kullanıcıya bir izin ekranı gösterilir.

Kimlik jetonunu doğrulama

Doğrudan Google'dan geldiklerini bilmiyorsanız sunucunuzdaki tüm kimlik jetonlarını doğrulamanız gerekir. Örneğin, sunucunuz istemci uygulamalarınızdan aldığı tüm kimlik jetonlarının orijinal olduğunu doğrulamalıdır.

Sunucunuza kimlik jetonları gönderebileceğiniz yaygın durumlar şunlardır:

  • Kimliği doğrulanması gereken isteklerle birlikte kimlik jetonları gönderme. Kimlik jetonları, istekte bulunan kullanıcıyı ve bu kimlik jetonunun hangi istemci için verildiğini belirtir.

Kimlik jetonları hassastır ve müdahale edilmesi durumunda kötüye kullanılabilir. Bu jetonları yalnızca HTTPS üzerinden ve yalnızca POST verileri aracılığıyla veya istek başlıkları içinde ileterek güvenli bir şekilde işlendiğinden emin olmanız gerekir. Sunucunuzda kimlik jetonları depoluyorsanız bunları da güvenli bir şekilde saklamanız gerekir.

Kimlik jetonlarını kullanışlı hale getiren şeylerden biri de bunları uygulamanızın farklı bileşenleri arasında iletebilmenizdir. Bu bileşenler, kimlik jetonunu, uygulamanın ve kullanıcının kimliğini doğrulayan hafif bir kimlik doğrulama mekanizması olarak kullanabilir. Ancak kimlik jetonundaki bilgileri kullanabilmeniz veya kullanıcının kimliğini doğruladığına dair bir onay olarak bu bilgileri kullanabilmeniz için önce bunu doğrulamanız gerekir.

Kimlik jetonunun doğrulanması birkaç adım gerektirir:

  1. Kimlik jetonunun, kartı veren kuruluş tarafından düzgün şekilde imzalandığını doğrulayın. Google tarafından verilen jetonlar, Discovery dokümanının jwks_uri meta veri değerinde belirtilen URI'de bulunan sertifikalardan biri kullanılarak imzalanır.
  2. Kimlik jetonundaki iss talebi değerinin https://accounts.google.com veya accounts.google.com değerine eşit olduğunu doğrulayın.
  3. Kimlik jetonundaki aud hak talebinin değerinin, uygulamanızın istemci kimliğine eşit olduğunu doğrulayın.
  4. Kimlik jetonunun geçerlilik süresinin (exp hak talebi) sona ermediğini doğrulayın.
  5. İstekte bir hd parametresi değeri belirttiyseniz kimlik jetonunun, Google Cloud kuruluşuyla ilişkili kabul edilen bir alan adıyla eşleşen bir hd hak talebine sahip olduğunu doğrulayın.

2. ila 5. adımlar yalnızca oldukça basit olan dize ve tarih karşılaştırmalarını içerir. Bu nedenle, burada ayrıntılarına girmeyeceğiz.

İlk adım daha karmaşıktır ve kriptografik imza denetimini içerir. Hata ayıklama amacıyla, sunucunuzda veya cihazınızda uygulanan yerel işlemlerle karşılaştırmak için Google'ın tokeninfo uç noktasını kullanabilirsiniz. Kimlik jetonunuzun değerinin XYZ123 olduğunu varsayalım. Daha sonra, https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123 URI'sının referansını kaldırırsınız. Jeton imzası geçerliyse yanıt, kodu çözülmüş JSON nesnesi formundaki JWT yükü olur.

tokeninfo uç noktası, hata ayıklama için kullanışlıdır ancak üretim amacıyla Google'ın ortak anahtarlarını anahtar uç noktasından alın ve doğrulamayı yerel olarak gerçekleştirin. Anahtar URI'sını jwks_uri meta veri değerini kullanarak Keşif belgesinden almanız gerekir. Hata ayıklama uç noktasına yapılan istekler kısıtlanabilir veya başka şekilde aralıklı hatalara maruz kalabilir.

Google, genel anahtarlarını çok nadir değiştirdiğinden, bunları HTTP yanıtının önbellek yönergelerini kullanarak önbelleğe alabilirsiniz ve çoğu durumda yerel doğrulama işlemini, tokeninfo uç noktasını kullanmaya kıyasla çok daha verimli bir şekilde yapabilirsiniz. Bu doğrulama, sertifikaların alınmasını ve ayrıştırılmasını ve imzayı kontrol etmek için uygun şifreleme çağrılarının yapılmasını gerektirir. Neyse ki bunu yapabilmek için çok çeşitli dillerde, hataları ayıklanmış kitaplıklar mevcuttur (jwt.io'ya bakın).

Kullanıcı profili bilgilerini alma

Kullanıcı hakkında ek profil bilgileri edinmek için, erişim jetonunu (uygulamanızın kimlik doğrulama akışı sırasında alır) ve OpenID Connect standardını kullanabilirsiniz:

  1. OpenID ile uyumlu olmak için kimlik doğrulama isteğinize openid profile kapsam değerlerini eklemeniz gerekir.

    Kullanıcının e-posta adresinin dahil edilmesini istiyorsanız email değerinde ek bir kapsam değeri belirtebilirsiniz. Hem profile hem de email belirtmek için kimlik doğrulama isteği URI'nıza aşağıdaki parametreyi ekleyebilirsiniz:

    scope=openid%20profile%20email
  2. Erişim jetonunuzu yetkilendirme başlığına ekleyin ve kullanıcı bilgileri uç noktasına HTTPS GET isteği gönderin. Bu isteği, userinfo_endpoint meta veri değerini kullanarak Discovery belgesinden almanız gerekir. Kullanıcı bilgileri yanıtı, OpenID Connect Standard Claims bölümünde açıklandığı gibi kullanıcı hakkında bilgiler ve Keşif dokümanının claims_supported meta veri değerini içerir. Kullanıcılar veya kuruluşları belirli alanları sağlamayı ya da alıkoymayı tercih edebilir. Bu nedenle, yetkilendirdiğiniz erişim kapsamlarıyla ilgili her alanla ilgili bilgileri alamayabilirsiniz.

Keşif belgesi

OpenID Connect protokolü, kullanıcıların kimliğini doğrulamak ve jetonlar, kullanıcı bilgileri ve ortak anahtarlar dahil olmak üzere kaynak istemek için birden fazla uç noktanın kullanılmasını gerektirir.

OpenID Connect, uygulamaları basitleştirmek ve esnekliği artırmak için "Discovery dokümanı"nın kullanılmasına izin verir. Bu belge, iyi bilinen bir konumda bulunan ve OpenID Connect sağlayıcısının yapılandırması hakkında yetkilendirme, jeton, iptal, kullanıcı bilgileri ve ortak anahtar uç noktalarının URI'leri dahil olmak üzere ayrıntılar sağlayan anahtar/değer çiftlerini içeren bir JSON belgesidir. Google'ın OpenID Connect hizmetinin Keşif dokümanı şuradan alınabilir:

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

Google'ın OpenID Connect hizmetlerini kullanmak için Keşif belgesi URI'sını (https://accounts.google.com/.well-known/openid-configuration) uygulamanıza sabit olarak kodlamanız gerekir. Uygulamanız belgeyi getirir, yanıta önbelleğe alma kurallarını uygular, ardından gerektiğinde uç nokta URI'larını buradan alır. Örneğin, bir kullanıcının kimliğini doğrulamak için kodunuz, Google'a gönderilen kimlik doğrulama istekleri için temel URI olarak authorization_endpoint meta veri değerini (aşağıdaki örnekte https://accounts.google.com/o/oauth2/v2/auth) alır.

Böyle bir dokümanın örneğini burada bulabilirsiniz. Alan adları, OpenID Connect Discovery 1.0'da belirtilenlerdir (anlamları için bu dokümana bakın). Değerler yalnızca örnek olarak verilmiştir ve gerçek Google Keşif dokümanının yakın tarihli bir sürümünden kopyalanmalarına rağmen değişebilir:

{
  "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"
  ]
}

Keşif belgesindeki değerleri önbelleğe alarak bir HTTP gidiş dönüşünü önleyebilirsiniz. Standart HTTP önbelleğe alma üst bilgileri kullanılır ve buna uyulmalıdır.

İstemci kitaplıkları

Aşağıdaki istemci kitaplıkları, popüler çerçevelerle entegrasyon sağlayarak OAuth 2.0'ın uygulanmasını kolaylaştırır:

OpenID Connect uygunluğu

Google'ın OAuth 2.0 kimlik doğrulama sistemi, OpenID Connect Core spesifikasyonunun gerekli özelliklerini destekler. OpenID Connect ile çalışacak şekilde tasarlanmış tüm istemciler, bu hizmetle birlikte çalışmalıdır (OpenID İstek Nesnesi hariç).