OpenID Connect

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

OAuth 2.0 ayarlanıyor

Uygulamanızın, kullanıcı girişinde Google'ın OAuth 2.0 kimlik doğrulama sistemini kullanabilmesi için Google API Console OAuth 2.0 kimlik bilgilerini almak, bir yönlendirme URI'si ayarlamak ve (isteğe bağlı olarak) kullanıcılarınızın izin ekranında gördüğü marka bilinci oluşturma bilgilerini özelleştirmek için bir proje oluşturmanız gerekir. Hizmet hesabı oluşturmak, faturalandırmayı etkinleştirmek, filtrelemeyi ayarlamak ve diğer görevleri gerçekleştirmek için API Console hizmetini de kullanabilirsiniz. Daha fazla bilgi için Google API Console Yardım'a bakın.

OAuth 2.0 kimlik bilgilerini alma

Kullanıcıların kimliğini doğrulamak ve Google API'lerine erişmek 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 ayarla

API Console alanında ayarladığınız yönlendirme URI'si, Google'ın yanıtları kimlik doğrulama isteklerinize 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 deneyimi, kullanıcının yayınladığı bilgileri ve geçerli şartları açıklayan bir izin ekranı içerir. Örneğin, kullanıcı giriş yaptığında, uygulamanıza e-posta adresine ve temel hesap bilgilerine erişim izni vermesi istenebilir. Uygulamanızın kimlik doğrulama isteğine dahil ettiği scope parametresini kullanarak bu bilgilere erişim isteğinde bulunabilirsiniz. Diğer Google API'lerine erişim istemek için kapsamları da kullanabilirsiniz.

Kullanıcı rızası ekranı, ürün adı, logo ve ana sayfa URL'si gibi marka bilgilerini de gösterir. Marka bilgilerini API Consoleüzerinde 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 bir kombinasyonu istekte bulunduğunda kullanıcının ne göreceğini belirtir. (Bu genel iletişim kutusu Google OAuth 2.0 Playground kullanılarak oluşturuldu. Bu yüzden, API Consoleöğesinde ayarlanacak marka bilgilerini içermez.)

İzin ekranı 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 çoğunu yapmak için kullanabileceğiniz kitaplıklar sağlar. Örnekler, çeşitli platformlarda kullanılabilen Google Kimlik Hizmetleri ve Google istemci kitaplıklarını kapsar.

Kitaplık kullanmamayı tercih ederseniz bu dokümanın geri kalan kısmında yer alan, mevcut kitaplıkların temelindeki HTTP isteği akışlarını açıklayan talimatları uygulayın.

Kullanıcı kimliğini doğrulama

Kullanıcının kimliğini doğrulamak için bir kimlik jetonu almanız ve bunu doğrulamanız gerekir. Kimlik jetonları, internet üzerinde kimlik doğrulama işlemlerinde kullanılmak üzere tasarlanmış OpenID Connect'in standartlaştırılmış bir özelliğidir.

Bir kullanıcının kimliğini doğrulamak ve bir kimlik jetonu almak için kullanılan en yaygın yaklaşımlar, "sunucu" akışı ve "dolaylı akış" olarak adlandırılır. Sunucu akışı, bir uygulamanın arka uç sunucusunun tarayıcı veya mobil cihaz kullanan kişinin kimliğini doğrulamasına olanak tanır. Dolaylı akış, istemci taraflı bir uygulamanın (genellikle tarayıcıda çalışan bir JavaScript uygulaması) arka uç sunucusu yerine doğrudan API'lere 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. İstemci tarafında jetonların işlenmesi ve kullanılmasıyla ilgili güvenlik riskleri nedeniyle, dolaylı akış önemli ölçüde daha karmaşıktır. Dolaylı bir akış uygulamanız gerekiyorsa Google Kimlik Hizmetleri'ni kullanmanızı önemle tavsiye ederiz.

Sunucu akışı

Uygulamanızın bu protokolleri kullanabilmesi ve kullanıcılarınızın kimliğini doğrulaması için uygulamayı API Consoleuygulamasında ayarladığınızdan emin olun. Bir kullanıcı Google'a giriş yapmaya çalıştığında şunları yapmanız gerekir:

  1. Sahtekarlık karşıtı durum jetonu oluşturma
  2. Google'a kimlik doğrulama isteği gönderme
  3. Sahtekarlığı önleme durum jetonunu onaylayın
  4. Erişim jetonu ve kimlik jetonu için code değişimi
  5. Kimlik jetonundan kullanıcı bilgileri edinme
  6. Kullanıcının kimliğini doğrulama

1. Sahtekarlık karşıtı durum jetonu oluşturma

Sahtekarlık saldırılarına karşı önlem alarak kullanıcılarınızın güvenliğini korumalısınız. İlk adım, uygulamanız ile kullanıcının istemcisi arasında durumu tutan benzersiz bir oturum jetonu oluşturmaktır. Daha sonra bu benzersiz oturum jetonunu, kullanıcının kötü amaçlı bir saldırganla değil, istek yaptığını doğrulamak üzere Google OAuth Giriş hizmeti tarafından döndürülen kimlik doğrulama yanıtıyla eşleştirirsiniz. Bu jetonlara genellikle siteler arası istek sahtekarlığı (CSRF) jetonları denir.

Eyalet jetonu için iyi bir seçim, yüksek kaliteli rastgele sayı jeneratörü kullanılarak oluşturulmuş 30'a yakın karakterden oluşan bir dizedir. Bir diğeri de oturum durumu değişkenlerinizden bazılarının arka ucunda gizli tutulacak bir anahtarla imzalanmasıyla elde edilen karmadır.

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

PHP

Bu örneği kullanmak için 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 için 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 için 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önderme

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ıldığını unutmayın. HTTP bağlantıları reddedilir. authorization_endpoint meta veri değerini kullanarak temel URI'yi Discovery dokümanından almanız gerekir. Aşağıdaki tartışmada temel URI'nin https://accounts.google.com/o/oauth2/v2/auth olduğu varsayılmıştır.

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

  • client_id API Console Credentials page
  • response_type. Temel yetkilendirme kodu akışı isteğinde code olmalıdır. (Daha fazla bilgi için response_type adresine bakın.)
  • scope. Temel istekte openid email olması gerekir. (Daha fazla bilgi için scope adresini ziyaret edin.)
  • redirect_uri, sunucunuzda Google'dan yanıt alacak HTTP uç noktası olmalıdır. Değerin, API Console Credentials pagebölümünde yapılandırdığınız OAuth 2.0 istemcisinin yetkili yönlendirme URI'lerinden biriyle tam olarak eşleşmesi gerekir. Bu değer yetkili bir URI ile eşleşmezse istek redirect_uri_mismatch hatasıyla başarısız olur.
  • state, sahtekarlık karşıtı benzersiz oturum jetonunun değerini ve kullanıcı uygulamanıza döndüğünde bağlamı kurtarmak için gereken diğer bilgileri (ör. başlangıç URL'si) içermelidir. (Daha fazla bilgi için state adresini ziyaret edin.)
  • nonce, uygulamanız tarafından oluşturulan ve mevcut olduğunda tekrar oynatma korumasını sağlayan rastgele bir değerdir.
  • login_hint, kullanıcının e-posta adresi veya kullanıcının Google kimliğiyle eşdeğer olan sub dizesi olabilir. login_hint sağlamazsanız ve kullanıcı halihazırda oturum açmışsa, izin ekranında kullanıcının e-posta adresinin uygulamanıza serbest bırakılması için bir onay isteği yer alır. (login_hint adresinde daha fazla bilgi edinebilirsiniz.)
  • OpenID Connect akışını bir Google Cloud kuruluşuyla ilişkili belirli bir alanın kullanıcıları için optimize etmek amacıyla hd parametresini kullanın. (Daha fazla bilgi için hd adresine bakın.)

Aşağıda, satır sonları ve boşlukları içeren okunabilir bir OpenID Connect kimlik doğrulama URI'si ö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 kendileriyle ilgili yeni bilgiler isterse veya daha önce onaylamadıkları hesap erişimi isterse kullanıcılar izin vermelidir.

3. Sahtekarlık karşıtı durum jetonunu onaylayın

Yanıt, istekte belirttiğiniz redirect_uri adresine 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 aldığınız state değerinin 1. adımda oluşturduğunuz oturum jetonuyla eşleştiğini onaylamanız gerekir. Bu gidiş dönüş doğrulama, kötü amaçlı bir komut dosyası değil kullanıcının isteği yapmasını sağlamaya yardımcı olur.

Aşağıdaki kodda, 1. Adımda oluşturduğunuz oturum jetonlarının onaylandığı gösterilmektedir:

PHP

Bu örneği kullanmak için 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 için 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 için 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 code değişimi

Yanıtta, sunucunuzun erişim jetonu ve kimlik jetonu karşılığında kullanabileceği tek seferlik bir yetkilendirme kodu olan code parametresi bulunmaktadır. Sunucunuz, bu exchange'i HTTPS POST isteği göndererek gerçekleştirir. POST isteği, jeton uç noktasına gönderilir. token_endpoint meta veri değerini kullanarak Keşif dokümanından almanız gerekir. Aşağıdaki tartışmada uç noktanın https://oauth2.googleapis.com/token olduğu varsayılmaktadır. İstek, POST gövdesinde aşağıdaki parametreleri içermelidir:

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, API Console Credentials pagekaynağından edindiğiniz istemci kimliği.
client_secret OAuth 2.0 kimlik bilgilerini alma bölümünde açıklandığı gibi, API Console Credentials pagekaynağından edindiğiniz istemci sırrı.
redirect_uri Credentials pageURI'si ayarlama bölümünde açıklandığı gibi, API ConsoleCredentials pagebölümünde belirtilen client_id için yetkili bir yönlendirme URI'si.
grant_type Bu alan, OAuth 2.0 spesifikasyonunda tanımlandığı gibi authorization_code değerini içermelidir.

Gerçek istek, aşağıdaki örnekteki 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 başarılı bir yanıt, JSON dizisinde aşağıdaki alanları içerir:

Alanlar
access_token Google API'ye gönderilebilen bir jeton.
expires_in Saniye cinsinden erişim jetonunun kalan ömrü.
id_token Google tarafından dijital olarak imzalanan, kullanıcı hakkında kimlik bilgilerini içeren bir JWT.
scope access_token tarafından verilen erişim kapsamları; boşlukla sınırlandırılmış ve büyük/küçük harfe duyarlı dizelerin listesi olarak belirtilir.
token_type Döndürülen jetonun türünü tanımlar. Şu anda bu alanda her zaman Bearer değeri bulunur.
refresh_token (isteğe bağlı)

Bu alan yalnızca kimlik doğrulama isteğinde access_type parametresi offline olarak ayarlanmışsa kullanılır. Ayrıntılı bilgi için Jetonları yenileme başlıklı makaleye göz atın.

5. Kimlik jetonundan kullanıcı bilgileri edinme

Kimlik Jetonu, bir JWT (JSON Web Token) yani kriptografik olarak imzalanmış Base64 kodlu bir JSON nesnesidir. Normalde kimliği bir jetonu kullanmadan önce doğrulamanız çok önemlidir. Ancak Google ile doğrudan aracı olmayan bir HTTPS kanalı üzerinden iletişim kurduğunuzdan ve Google'da kimliğinizi doğrulamak için istemci gizli anahtarı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 bu jetonu kullanmadan önce jetonu doğrulaması çok önemlidir.

Çoğu API kitaplığı, doğrulamayı Base64url olarak kodlanmış değerlerin kodunu çözme ve JSON içindeki verileri ayrıştırma çalışmalarıyla birleştirdiğinden, muhtemelen jetondaki hak taleplerine eriştiğinizde jetonu doğrulayabilirsiniz.

Kimlik jetonu yükü

Kimlik jetonu, bir ad/değer çifti kümesi içeren bir JSON nesnesidir. Okunaklılık için biçimlendirilmiş bir örnek:

{
  "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 Kimliği 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 Geçerlilik bitiş zamanı, kimlik jetonunun kabul edildiği tarihte veya daha sonra kabul edilmemelidir. Unix saatiyle (tam sayı saniye) gösterilir.
iat always Kimlik jetonunun verildiği saat. Unix saatiyle (tam sayı saniye) gösterilir.
iss always Yanıtı veren kuruluşun tanımlayıcısı. Google kimlik jetonları için her zaman https://accounts.google.com veya accounts.google.com kullanılır.
sub always Kullanıcının tanımlayıcısıdır. Tüm Google hesapları arasında benzersizdir ve hiçbir zaman kullanılmamıştır. 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ı için benzersiz tanımlayıcı anahtarı olarak sub kullanın. Büyük/küçük harfe duyarlı 255 ASCII karakteri uzunluğunda.
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 birlikte verilirse bu hak talebi her zaman dahil edilir. Bu hak talebi, siteler arası istek sahtekarlığı saldırılarına karşı korumak 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, bir web uygulaması ile Android uygulamasının farklı bir OAuth 2.0 client_id sürümüne sahip olduğu ancak aynı Google API'leri projesini paylaştığı karma uygulamalar için Google'da geçerli olabilir.
email Kullanıcının e-posta adresi. Bu değer, kullanıcıya özel olmayabilir ve birincil anahtar olarak kullanılmaya uygun değildir. Yalnızca kapsamınız email kapsam değerini içeriyorsa sağlanır.
email_verified Kullanıcının e-posta adresi doğrulandıysa doğru, aksi takdirde yanlış değerini alır.
family_name Kullanıcının soyadı veya soyadları name hak talebi mevcut olduğunda sağlanabilir.
given_name Kullanıcıya verilen adlar. name hak talebi mevcut olduğunda sağlanabilir.
hd Kullanıcının Google Cloud kuruluşuyla ilişkilendirilen alan adı. Yalnızca kullanıcı bir Google Cloud kuruluşuna aitse sağlanır.
locale Kullanıcının yerel ayarı, BCP 47 dil etiketiyle gösterilir. name hak talebi mevcut olduğunda sağlanabilir.
name Kullanıcının tam adı ve görüntülenebilir biçimdedir. Şu durumlarda sağlanabilir:
  • İstek kapsamı, "profile&quot" dizesini içeriyordu
  • Kimlik jetonu, jeton yenilemesinden döndürülür

Mevcut name hak taleplerini, uygulamanızın kullanıcı kayıtlarını güncellemek için kullanabilirsiniz. Bu iddianın hiçbir zaman mevcut olacağının garanti edilmediğini unutmayın.

nonce Uygulamanızın kimlik doğrulama isteğinde sağladığı nonce değeridir. Videonun yalnızca bir kez sunulduğundan emin olarak tekrarlı saldırılara karşı koruma sağlamalısınız.
picture Kullanıcının profil resminin URL'si. Şu durumlarda sağlanabilir:
  • İstek kapsamı, "profile&quot" dizesini içeriyordu
  • Kimlik jetonu, jeton yenilemesinden döndürülür

Mevcut picture hak taleplerini, uygulamanızın kullanıcı kayıtlarını güncellemek için kullanabilirsiniz. Bu iddianın hiçbir zaman mevcut olacağının garanti edilmediğini unutmayın.

profile Kullanıcının profil sayfasının URL'si. Şu durumlarda sağlanabilir:
  • İstek kapsamı, "profile&quot" dizesini içeriyordu
  • Kimlik jetonu, jeton yenilemesinden döndürülür

Mevcut profile hak taleplerini, uygulamanızın kullanıcı kayıtlarını güncellemek için kullanabilirsiniz. Bu iddianın hiçbir zaman mevcut olacağının garanti edilmediğini unutmayın.

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

Kimlik jetonundan kullanıcı bilgilerini aldıktan sonra uygulamanızın kullanıcı veritabanını sorgulamalısınız. Halihazırda veritabanınızda bulunan bir kullanıcı varsa ve tüm giriş şartları Google API yanıtı tarafından karşılanıyorsa 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ı kayıt akışınıza yönlendirmeniz gerekir. Kullanıcıyı Google'dan edindiğiniz bilgilere göre otomatik olarak kaydedebilir veya en azından kayıt formunuzda zorunlu tutulan birçok alanı ö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'si daha ayrıntılı olarak açıklanmıştır. Bu bilgi, kimlik doğrulama ve yetkilendirmeyle ilgili 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, uygulamanızın kimlik doğrulamasının aynı zamanda kullanıcı adına diğer YouTube API'lerini (YouTube, Google Drive, Takvim veya Kişiler gibi) kullanma iznine sahip olmasıdır. Bunu yapmak için ihtiyacınız olan diğer kapsamları Google'a gönderdiğiniz kimlik doğrulama isteğine ekleyin. Örneğin, kullanıcının yaş grubunu kimlik doğrulama isteğinize eklemek için openid email https://www.googleapis.com/auth/profile.agerange.read kapsam parametresini iletin. Kullanıcı, izin ekranında uygun şekilde istenir. Google'dan aldığınız erişim jetonu, istediğiniz ve size verilen erişim kapsamlarıyla ilgili tüm API'lere erişmenizi sağlar.

Jetonları yenileme

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

Dikkat Edilecek Noktalar:

  • Yenileme jetonunu yalnızca kod değişimi akışını ilk kez gerçekleştirdiğinizde alabileceğinizden yenileme jetonunu güvenli ve kalıcı bir şekilde sakladığınızdan emin olun.
  • Her bir istemci/kullanıcı kombinasyonu için bir sınır ve tüm istemcilerde kullanıcı başına bir sınır olmak üzere, yayınlanan yenileme jetonlarının sayısı sınırlıdır. Uygulamanız çok fazla yenileme jetonu isterse bu sınırlara rastlayabilir. 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 eklendiğinde, kapsamlar Google API'leri projenize daha önce verilmiş olsa bile uygulamanız erişim kapsamları için her yetkilendirme istediğinde izin ekranı görüntülenir. Bu nedenle, prompt=consent özelliğini yalnızca gerektiğinde ekleyin.

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

Kimlik doğrulama URI parametreleri

Aşağıdaki tabloda, Google’ın OAuth 2.0 kimlik doğrulama API'si tarafından kabul edilen parametreler hakkında daha ayrıntılı açıklamalar verilmiştir.

Parametre Zorunlu Açıklama
client_id (Gerekli) OAuth 2.0 kimlik bilgilerini alma bölümünde açıklandığı gibi, API ConsoleCredentials pagesayfasından edindiğiniz istemci kimliği dizesi.
nonce (Gerekli) Uygulamanızın oluşturduğu, tekrarlama korumasını sağlayan rastgele bir değer.
response_type (Gerekli) Değer code ise jetonları almak için jeton uç noktasına POST kullanılmasını gerektiren bir Temel yetkilendirme kodu akışı başlatır. Değer token id_token veya id_token token ise URI #fragment tanımlayıcısından jetonlar almak için yönlendirme URI'sinde JavaScript kullanılmasını gerektiren bir Dolaylı akış başlatır.
redirect_uri (Gerekli) Yanıtın gönderileceği yeri belirler. Bu parametrenin değeri, API ConsoleCredentials page özelliğinde ayarladığınız yetkili yönlendirme değerlerinden biriyle (HTTP veya HTTPS şeması, büyük/küçük harf ve varsa '/' varsa) tam olarak eşleşmelidir.
scope (Gerekli)

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

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

email kapsam değeri mevcutsa 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ğerlerini 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ı veya kullanmak istediğiniz Google API dokümanlarını inceleyin.

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

Protokolde çift yönlü opak bir dizedir. Yani, Temel akışta ve Örtük akıştaki URI #fragment tanımlayıcısında bir URI parametresi olarak döndürülür.

state, ilişkili istekler ve yanıtlar için yararlı olabilir. redirect_uri tahmininiz olabileceği için state değeri kullanmak, gelen bağlantının uygulamanız tarafından başlatılan bir kimlik doğrulama isteği sonucunda gerçekleştiğine dair güvencenizi artırabilir. Bu state değişkeninde rastgele bir dize oluşturur veya bazı istemci durumlarının (ör. çerez) karmasını kodlarsanız isteğin ve yanıtın aynı tarayıcıda oluşturulmuş olduğundan emin olmak için yanıtı doğrulayabilirsiniz. Bu, siteler arası istek sahtekarlığı gibi saldırılara karşı koruma sağlar.

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

Bir Google Cloud kuruluşunun sahip olduğu hesaplar için giriş işlemini kolaylaştırın. Google Cloud kuruluş alanını (örneğin, mycollege.edu) ekleyerek, hesap seçimi kullanıcı arayüzünün söz konusu alandaki hesaplar için optimize edilmesi gerektiğini belirtebilirsiniz. Yalnızca bir Google Cloud kuruluş alanı yerine Google Cloud kuruluş hesaplarını optimize etmek için yıldız işareti değeri (*) ayarlayın: hd=*.

İstemci taraflı değişiklikler değiştirilebildiğinden uygulamanıza kimlerin erişebileceğini kontrol etmek için bu kullanıcı arayüzü optimizasyonuna güvenmeyin. İade edilen kimlik jetonunun beklediğinizle eşleşen bir hd talep değeri olduğunu (ör.mycolledge.edu) doğruladığınızdan emin olun. İstek parametresinin aksine hd kimlik jetonu, Google'ın güvenlik jetonunda yer alır. Böylece bu değere güvenilebilir.

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 de içerir. Ek yetkilendirme başlıklı makaleyi inceleyin.

Yüklü Uygulama akışı ile 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 bir ipucu olarak sağlayabilir. Bu ipucunun iletilmesi, hesap seçiciyi gizler ve oturum açma formundaki e-posta kutusunu önceden doldurur ya da doğru oturumu seçer (kullanıcı çoklu oturum açma kullanıyorsa). Uygulamanız yanlış kullanıcı hesabına giriş yaptığında bu sorunlardan kaçınabilirsiniz. Değer, kullanıcının Google kimliğiyle eşdeğer olan bir e-posta adresi veya 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 ayrılmış bir dize değerleri listesi. Olası değerler:
  • none

    Yetkilendirme sunucusu herhangi bir kimlik doğrulama veya kullanıcı rızası ekranı göstermez. Kullanıcının kimliği zaten doğrulanmamışsa ve istenen kapsamlar için önceden yapılandırılmış bir izin yapılandırmamışsa hata döndürecektir. Mevcut kimlik doğrulamasını ve/veya izni kontrol etmek için none etiketini kullanabilirsiniz.

  • consent

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

  • select_account

    Yetkilendirme sunucusu kullanıcıdan bir kullanıcı hesabı seçmesini ister. Bu şekilde, yetkilendirme sunucusunda birden fazla hesabı olan bir kullanıcı, o anda oturum açmış olabileceği birden fazla hesap arasından seçim yapabilir.

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

Kimlik jetonunu doğrulama

Sunucunuzdaki tüm kimlik jetonlarını doğrudan Google'dan geldiğini bilmediğiniz sürece doğrulamanız gerekir. Örneğin, sunucunuzun istemci uygulamalarınızdan aldığı tüm kimlik jetonlarını orijinal olarak doğrulaması gerekir.

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

  • Kimliğinin doğrulanması gereken istekler içeren kimlik jetonları gönderme. Kimlik jetonları, istekte bulunan belirli bir kullanıcıyı ve bu kimlik jetonunun hangi istemci için verildiğini gösterir.

Kimlik jetonları hassastır ve ele geçirilirse kötüye kullanılabilir. Bu jetonların yalnızca HTTPS üzerinden ve yalnızca POST verileri aracılığıyla ya da istek başlıkları altında aktarılmasıyla güvenli bir şekilde işlendiğinden emin olmanız gerekir. Kimlik jetonlarını sunucunuzda depoluyorsanız bunları da güvenli bir şekilde saklamalısınız.

Kimlik jetonlarını faydalı kılan şeylerden biri de jetonları uygulamanızın farklı bileşenlerinin içine aktarmanızdır. Bu bileşenler, kimlik doğrulaması için uygulamanın ve kullanıcının kimliğini doğrulayan basit bir kimlik doğrulama mekanizması olarak kullanılabilir. Ancak kimlik jetonundaki bilgileri kullanabilmek veya bunu kullanıcının kimliğini doğruladığının bir kanıtı olarak kullanmadan önce bunu doğrulamanız gerekir.

Kimlik jetonunun doğrulanması için birkaç adım gerekir:

  1. Kimlik jetonunun, kartı veren kuruluş tarafından doğru ş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 hak 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ğiyle aynı olduğunu doğrulayın.
  4. Kimlik jetonunun süre sonu (exp hak talebi) geçmediğini doğrulayın.
  5. İstekte hd parametresi değeri belirttiyseniz kimlik jetonunun, Google Cloud kuruluşuyla ilişkili kabul edilen bir alan adıyla eşleşen hd hak talebinde bulunduğ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ı ayrıntılı olarak vermeyeceğiz.

İlk adım daha karmaşıktır ve kriptografik imza kontrolü 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. Bu durumda https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123 URI'sinin referansını kaybedersiniz. Jeton imzası geçerliyse yanıt, kodu çözülmüş JSON nesne biçimindeki JWT yükü olur.

tokeninfo uç noktası, hata ayıklama için faydalı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. Anahtarların URI'sini jwks_uri meta veri değerini kullanarak Discovery dokümanından almanız gerekir. Hata ayıklama uç noktasına yapılan istekler kısıtlanabilir veya başka şekillerde aralıklı hatalara neden olabilir.

Google, ortak anahtarlarını yalnızca nadiren değiştirdiğinden, HTTP yanıtının önbellek yönergelerini kullanarak bu anahtarları önbelleğe alabilir ve çoğu durumda yerel doğrulama işlemini tokeninfo uç noktasından çok daha etkili bir şekilde gerçekleştirebilirsiniz. Bu doğrulama, sertifikaların alınıp 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 yapmak için çok çeşitli dillerde kullanılabilen, hata ayıklaması yapılmış kitaplıklar mevcuttur (bkz. jwt.io).

Kullanıcı profili bilgilerini alma

Kullanıcı hakkında ek profil bilgileri almak için erişim jetonunu (uygulamanızın kimlik doğrulama akışı sırasında aldığı adres) 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 eklenmesini istiyorsanız email şeklinde ek bir kapsam değeri belirtebilirsiniz. Hem profile hem de email değerini belirtmek için kimlik doğrulama isteği URI'nize aşağıdaki parametreyi ekleyebilirsiniz:

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

Keşif dokümanı

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

Uygulamaları basitleştirmek ve esnekliği artırmak için OpenID Connect; OpenID Connect sağlayıcısının yapılandırmasıyla ilgili yetkilendirme, jeton, iptal, kullanıcı bilgileri ve ortak anahtar uç noktaları dahil olmak üzere ayrıntılı bilgiler içeren anahtar/değer çiftleri içeren, iyi bilinen bir konumda bulunan JSON dokümanının kullanılmasına imkan tanır. Google'ın OpenID Connect hizmeti için Discovery dokümanı şu kaynaklardan alınabilir:

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

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

Aşağıda bu tür bir belge örneği verilmiştir. Alan adları, OpenID Connect Discovery 1.0'da belirtilen adlardır (anlamları için söz konusu dokümana bakın). Değerler tamamen açıklama amaçlıdır ve gerçek Google Discovery belgesinin son sürümlerinden kopyalanmış olsalar bile değişebilirler:

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

Discovery dokümanındaki değerleri önbelleğe alarak HTTP gidiş dönüşten kaçınabilirsiniz. Standart HTTP önbelleğe alma üst bilgileri kullanılır ve bu kurallara uygun hareket edilmelidir.

İstemci kitaplıkları

Aşağıdaki istemci kitaplıkları, popüler çerçevelerle entegre olarak OAuth 2.0'ı uygulamayı 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ç).