OpenID Connect

Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Google'ın OAuth 2.0 API'leri hem kimlik doğrulama hem de yetkilendirme için kullanılabilir. Bu dokümanda, OpenID Connect spesifikasyonuyla uyumlu olan ve OpenID Sertifikalı 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 bölümünde bulunan 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" ile etiketleyin.

OAuth 2.0'ı ayarlama

Uygulamanızın, kullanıcı girişi için Google'ın OAuth 2.0 kimlik doğrulama sistemini kullanabilmesi için Google API Console uygulamasında OAuth 2.0 kimlik bilgilerini almak, yönlendirme URI'si ayarlamak ve (isteğe bağlı olarak) kullanıcı izni ekranında gösterilen marka bilgilerini özelleştirmeniz gerekir. Hizmet hesabı oluşturmak, faturalandırmayı etkinleştirmek, filtreleme ayarlamak ve başka işlemler yapmak için de API Console hizmetini 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'ın 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 ayarlayın

Google'ın, kimlik doğrulama isteklerinize yanıt gönderdiği API Console yerlerde belirlediğiniz yönlendirme URI'si belirlenir.

To create, view, or edit the redirect URIs for a given OAuth 2.0 credential, do the following:

  1. Go to the Credentials page.
  2. In the OAuth 2.0 client IDs section of the page, click a credential.
  3. View or edit the redirect URIs.

If there is no OAuth 2.0 client IDs section on the Credentials page, then your project has no OAuth credentials. To create one, click Create credentials.

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 serbest bıraktığı bilgileri ve geçerli şartları açıklayan bir izin ekranı içerir. Ö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 dahil ettiği scope parametresini kullanarak bu bilgilere ulaşmak isteyebilirsiniz. Kapsamları, diğer Google API'lerine erişim isteğinde bulunmak 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 bilinci oluşturma bilgilerini, API Consoleiçinde kontrol edersiniz.

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, istekte OAuth 2.0 ve Google Drive kapsamlarının kombinasyonu bulunduğunda kullanıcının ne göreceği gösterilir. (Bu genel iletişim kutusu, Google OAuth 2.0 Playground kullanılarak oluşturulmuştur. Bu yüzden, API Consoleiçinde ayarlanacak marka bilgilerini içermez.)

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

Hizmete erişme

Google ve üçüncü taraflar, kullanıcıların kimliğini doğrulama ve Google API'lerine erişim elde etmeyle ilgili birçok uygulama ayrıntısını yerine getirmek için kullanabileceğiniz kitaplıklar sağlar. Google Kimlik Hizmetleri ve çeşitli platformlarda kullanılabilen Google istemci kitaplıkları örnek olarak verilebilir.

Kitaplık kullanmamayı tercih ederseniz bu kitaplığın geri kalanında yer alan ve mevcut kitaplıkların altında yatan HTTP istek akışlarını açıklayan talimatları uygulayın.

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

Kullanıcının kimliğini doğrulamak için kimlik jetonu alma ve doğrulama gerekir. Kimlik jetonları, internet üzerinden 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 kimlik jetonu almak için en sık kullanılan yaklaşımlara "sunucu" akışı ve "dolaylı" akış denir. 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 API'lere 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. İ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ışı

Bu protokolleri kullanmak ve kullanıcılarınızın kimliklerini doğrulamak için uygulamanızı API Consoleiçinde ayarladığınızdan emin olun. Bir kullanıcı Google ile giriş yapmayı denediğinde:

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

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

Sahtekarlık isteklerine yönelik saldırıları önleyerek kullanıcılarınızın güvenliğini sağlamalı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, istekte bulunduğunu doğrulamak için Google OAuth Giriş hizmeti tarafından döndürülen kimlik doğrulama yanıtıyla eşleştirirsiniz. Bu jetonlar genellikle siteler arası istek sahtekarlığı (CSRF) jetonları olarak adlandırılır.

Eyalet jetonu için iyi bir seçim, yüksek kaliteli bir rastgele sayı jeneratörü kullanılarak oluşturulan 30 karakterli dizedir. Bir diğeri de oturum durumu değişkenlerinizden bazılarının arka ucunda gizli tutulan 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 isterseniz 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önderme

Sonraki adım, uygun URI parametreleriyle 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. Bu, temel yetkilendirme kodu akışı isteğinde code olmalıdır. (Daha fazla bilgi için response_type adresini ziyaret edin.)
  • scope. Bu istek temel istekte openid email olmalıdır. (Daha fazla bilgi için scope adresini ziyaret edin.)
  • redirect_uri, sunucunuzda Google'dan yanıt alacak HTTP uç noktası olmalıdır. Değer, API Console Credentials page içinde yapılandırdığınız OAuth 2.0 istemcisinin yetkili 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, sahte olmayan kullanıma yönelik 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 rastgele bir değerdir ve mevcut olduğunda tekrarlama korumasını etkinleştirir.
  • 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 bilgilerini sağlamazsanız ve kullanıcı şu an oturum açmış durumdaysa izin ekranında kullanıcının e-posta adresinin uygulamanızda yayınlanması 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 adresini ziyaret edin.)

Okunabilirlik için satır sonu ve boşluk içeren eksiksiz bir OpenID Connect kimlik doğrulama URI'sini aşağıda görebilirsiniz:

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 kullanıcıların yeni bilgiler talep etmesi veya daha önce onaylamadıkları hesap erişimi istemesi durumunda kullanıcıların izin vermesi gerekir.

3. Sahtekarlıktan korunma 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ğrulaması, isteği kötü amaçlı bir komut dosyasının değil, kullanıcının yapmasını sağlamaya yardımcı olur.

Aşağıdaki kod, 1. Adım'da oluşturduğunuz oturum jetonlarının onaylandığını göstermektedir:

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 isterseniz 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 code değişimi

Yanıtta code parametresi vardır. Bu, sunucunuzun bir erişim jetonu ve kimlik jetonuyla değiştirebileceği tek seferlik bir yetkilendirme kodudur. Sunucunuz, bu alışverişi bir HTTPS POST isteği göndererek yapar. POST İstek, jeton uç noktasına gönderilir ve bu değeri Discovery dokümanından token_endpoint meta veri değerini kullanarak 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 edinme bölümünde açıklandığı şekilde API Console Credentials pagearacılığıyla edindiğiniz istemci kimliği.
client_secret OAuth 2.0 kimlik bilgilerini edinme bölümünde açıklandığı şekilde, API Console Credentials pagearacılığıyla edindiğiniz istemci sırrı.
redirect_uri Yönlendirme URI'si ayarlama bölümünde açıklandığı üzere, API ConsoleCredentials pageiçinde belirtilen, client_id için yetkili bir yönlendirme URI'sı.
grant_type Bu alan, OAuth 2.0 spesifikasyonunda tanımlandığı şekilde authorization_code değerini içermelidir.

Asıl 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'sine gönderilebilen bir jeton.
expires_in Erişim jetonunun saniye cinsinden kalan ömrü.
id_token Google tarafından dijital olarak imzalanan, kullanıcı hakkında kimlik bilgileri içeren bir JWT.
scope access_token tarafından verilen erişim kapsamları, boşlukla ayrı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 alan her zaman Bearer değerine sahiptir.
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 Jetonları yenileme başlıklı makaleyi inceleyin.

5. Kimlik jetonundan kullanıcı bilgilerini edinme

Kimlik Jetonu, JWT (JSON Web Jetonu) yani kriptografik olarak imzalanmış bir Base64 kodlu JSON nesnesidir. Normalde bir kimlik jetonunu kullanmadan önce kimlik jetonunu doğrulamanız kritik öneme sahiptir, ancak aracısız 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 iletirse diğer bileşenlerin, 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 ayrıştırma işlemlerini birleştirerek gerçekleştirdiğinden, muhtemelen jeton jetondaki hak taleplerine erişirken jetonu doğrulayabilirsiniz.

Kimlik jetonunun yükü

Kimlik jetonu, bir ad/değer çifti kümesi içeren bir JSON nesnesidir. Aşağıda, okunabilirlik için biçimlendirilmiş bir örnek verilmiştir:

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

Hak talebi 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 Kimlik jetonunun kabul edilmemesi gereken son kullanma tarihi. Unix saatiyle (tamsayı saniyesi) gösterilir.
iat always Kimlik jetonunun verildiği zaman. Unix zamanında temsil edilir (tamsayı saniyesi).
iss always Yanıtın Veren Kuruluş Kimliği. Google kimliği jetonları için her zaman https://accounts.google.com veya accounts.google.com.
sub always Kullanıcının tüm Google hesapları için benzersiz ve hiçbir zaman tekrar kullanılmayan tanımlayıcısı. Bir Google hesabı, farklı noktalarda 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. Maksimum 255 büyük/küçük harfe duyarlı 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 bir access_token değeriyle yayınlanırsa 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 jetonunun doğrulanması gerekmez.
azp Yetkili sunucunun client_id. Bu hak talebi yalnızca kimlik jetonunu isteyen taraf, kimlik jetonunun kitlesiyle aynı olmadığında gereklidir. Bir web uygulaması ve Android uygulaması farklı bir OAuth 2.0 client_id sürümüne sahip ancak aynı Google API'leri projesini paylaşan karma uygulamalar için Google'da bu durum geçerli olabilir.
email Kullanıcının e-posta adresi. Bu değer, kullanıcıya özel olmayabilir ve birincil anahtar olarak kullanılamaz. 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 soyadı. name hak talebi mevcut olduğunda sağlanabilir.
given_name Kullanıcıya verilen adlar veya adlar. name hak talebi mevcut olduğunda sağlanabilir.
hd Kullanıcının Google Cloud kuruluşuyla ilişkilendirilmiş 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ı, gösterilen bir biçimde olmalıdır. Aşağıdaki durumlarda sağlanabilir:
  • İstek kapsamı "profile" dizesini içeriyordu
  • Kimlik jetonu, bir jeton yenilemesinden döndürülür

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

nonce Uygulamanızın kimlik doğrulama isteğinde sağladığı nonce değeridir. Videoların yalnızca bir defa sunulduğundan emin olarak tekrarlı saldırılara karşı 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çeriyordu
  • Kimlik jetonu, bir jeton yenilemesinden döndürülür

picture hak talebi varsa bunları uygulamanızın kullanıcı kayıtlarını güncellemek için kullanabilirsiniz. Bu hak talebinin hiçbir zaman 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çeriyordu
  • Kimlik jetonu, bir jeton yenilemesinden döndürülür

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

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. Kullanıcı, veritabanınızda zaten mevcutsa tüm giriş gereksinimleri Google API yanıtı tarafından karşılanıyorsa söz konusu 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. Google'dan aldığınız bilgilere göre kullanıcıyı otomatik olarak kaydettirebilir ya da en azından kayıt formunuzda gerekli olan alanların çoğunu önceden doldurabilirsiniz. Kimlik jetonundaki bilgilere ek olarak, kullanıcı profili uç noktalarımızda ek kullanıcı profili bilgileri edinebilirsiniz.

İleri düzey konular

Aşağıdaki bölümlerde Google OAuth 2.0 API'si daha ayrıntılı olarak açıklanmaktadır. Bu bilgi, kimlik doğrulama ve yetkilendirmeyle ilgili gelişmiş şartları olan geliştiriciler için hazırlanmıştır.

Diğer Google API'lerine erişme

Kimlik doğrulama için OAuth 2.0 kullanmanın avantajlarından biri, uygulamanızın kimlik doğrulaması sırasında aynı anda kullanıcı adına (YouTube, Google Drive, Takvim veya Kişiler gibi) diğer Google API'lerini kullanma izni alabilmesidir. Bunu yapmak için ihtiyacınız olan diğer kapsamları Google'a gönderdiğiniz kimlik doğrulama isteğine 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. Kullanıcıya, izin ekranında uygun şekilde mesaj 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şmenize olanak tanır.

Jetonları yenile

API erişimi isteğinizde, code değişimi sırasında döndürülecek bir jeton isteyebilirsiniz. Yenileme jetonu, uygulamanızda kullanıcı mevcut değilken uygulamanızın Google API'lerine sürekli erişebilmesini 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ği için alabileceğinizden emin olun.
  • Sunulan yenileme jetonlarının sayısı sınırlıdır: İstemci/kullanıcı kombinasyonu başına bir sınır ve tüm istemciler genelinde kullanıcı başına bir sınır. Uygulamanız çok fazla yenileme jetonu istiyorsa bu sınırlarla karşılaşabilirsiniz. Bu durumda, eski yenileme jetonlarının çalışması durur.

Daha fazla bilgi için Erişim jetonunu yenileme (çevrimdışı erişim) başlıklı makaleye bakın.

Kimlik doğrulama isteğinizde prompt parametresini consent olarak ayarlayarak kullanıcıdan uygulamanızı yeniden yetkilendirmesini isteyebilirsiniz. prompt=consent dahil edildiğinde, uygulamanız daha önce Google API'leri projenize verilmiş olsa bile izin kapsamları her yetkilendirme isteğinde bulunduğunda 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'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 parametrelerle ilgili daha kapsamlı açıklamalar sunulmaktadır.

Parametre Zorunlu Açıklama
client_id (Gerekli) OAuth 2.0 kimlik bilgilerini edinme bölümünde açıklandığı şekilde, API ConsoleCredentials pagearacılığıyla edindiğiniz istemci kimliği dizesi.
nonce (Gerekli) Tekrar oluşturulan korumayı etkinleştiren, uygulamanız tarafından oluşturulan rastgele bir değerdir.
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 Consoleiçinde ayarladığınız yetkili yönlendirme değerlerinden biriyle tam olarak eşleşmelidir. Credentials page (HTTP veya HTTPS şeması, büyük/küçük harf durumu ve varsa '/' dahil).
scope (Gerekli)

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 garanti edilmez).

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

Bu OpenID'ye özel kapsamlara ek olarak, kapsam bağımsız değişkeniniz de diğer kapsam değerlerini 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'si ile ilgili dokümanları inceleyin.

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

Protokolde yuvarlatılmış opak bir dize. Yani dizenin Temel akıştaki URI parametresi ve Örtük akıştaki URI #fragment tanımlayıcısında döndürüldüğünü unutmayın.

state, istekleri ve yanıtları ilişkilendirmek için yararlı olabilir. redirect_uri değeriniz tahmin edilebildiğinden, gelen bir bağlantının uygulamanız tarafından başlatılan bir kimlik doğrulama isteği sonucu olduğundan emin olabilirsiniz. Rastgele bir dize oluşturur veya bu state değişkenindeki bazı istemci durumlarının (ör. çerez) karmasını kodlarsanız hem isteğin hem de yanıtın aynı tarayıcıdan geldiğinden 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 bölümünde belgelenmiştir. 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 kullanıcı rızası arayüzü sayfalarını nasıl görüntüleyeceğini belirtmek için kullanılan bir ASCII dize değeri. Şu değerler belirtilir ve Google sunucuları tarafından kabul edilir, ancak davranışı ü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ı için optimizasyon yapmak istiyorsanız yıldız işaretini (*) ayarlayın: hd=*

İstemci tarafı istekleri değiştirilebileceğ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 hak talebi değerine (ör.mycolledge.edu) sahip olduğunu doğruladığınızdan emin olun. İstek parametresinin aksine, hd kimlik jetonu (hd) 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ıya/uygulama kombinasyonuna verilen önceki yetkilendirmeleri de içerir. Ek 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 ipucunun iletilmesi, hesap seçiciyi gizler ve oturum açma formundaki e-posta kutusunu önceden doldurur ya da uygun oturumu (kullanıcı çoklu oturum açma kullanıyorsa) seçer. Uygulamanız yanlış kullanıcı hesabına giriş yaparsa ortaya çıkabilecek sorunlardan kaçınmanıza yardımcı olabilir. 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 sınırlandırı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ı daha önce kimliği doğrulanmamışsa ve istenen kapsamlar için izni önceden yapılandırmamışsa hata döndürür. Mevcut kimlik doğrulama ve/veya rıza bilgilerini kontrol etmek için none 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ı bulunan 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 jetonu doğrulama

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

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

  • Kimlik doğrulaması gerektiren istekler içeren kimlik jetonları gönderme. Kimlik jetonları, istekte bulunan belirli bir kullanıcıyı ve bu kimlik jetonunun hangi istemciye verildiğini bildirir.

Kimlik jetonları hassastır ve ele geçirilirse yanlış kullanılabilir. Bu jetonların yalnızca HTTPS üzerinden ve yalnızca POST verileri aracılığıyla ya da istek başlıkları içinde iletilerek güvenli bir şekilde işlendiğinden emin olmanız gerekir. Kimlik jetonlarını sunucunuzda depoluyorsanız bunları da güvenli bir şekilde depolamanız gerekir.

Kimlik jetonlarını kullanışlı yapan bir özellik, bunları uygulamanızın farklı bileşenlerinin etrafına geçirebilmenizdir. Bu bileşenler, uygulamanın ve kullanıcının kimliğini doğrulayan basit bir kimlik doğrulama mekanizması olarak bir kimlik jetonu kullanabilir. Ancak, kimlik jetonundaki bilgileri kullanabilmek veya kullanıcının kimlik doğrulaması yaptığını doğrulamak için bu kodu kullanmadan önce bu kodu doğrulamanız gerekir.

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

  1. Kimlik jetonunun, kartı veren kuruluş tarafından doğru şekilde imzalandığını doğrulayın. Google tarafından verilen jetonlar, Discovery dokümanındaki jwks_uri meta veri değerinde belirtilen URI'da bulunan sertifikalardan biri kullanılarak imzalanır.
  2. Kimlik jetonundaki iss hak talebinin 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) iletilmediğini doğrulayın.
  5. İstekte hd parametresi değeri belirlediyseniz 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ımlarda, yalnızca oldukça basit olan dize ve tarih karşılaştırmaları yer alır. Bu nedenle, bu ayrıntıları burada ayrıntılı olarak açıklamayız.

İ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'sının referansını kaldırırsınız. Jeton imzası geçerliyse yanıt, kodu çözülmüş JSON nesne biçiminde 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 almalısınız. 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 bunları önbelleğe alabilir ve çoğu durumda yerel doğrulamayı tokeninfo uç noktasına kıyasla çok daha verimli 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 kriptografik çağrıların yapılmasını gerektirir. Neyse ki, bunu yapmak için çok çeşitli dillerde kullanılabilen, hata ayıklamaya uygun kitaplıklar mevcut (bkz. jwt.io).

Kullanıcı profili bilgilerini elde etme

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 dahil edilmesini 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ı bilgileri uç noktasına bir HTTPS GET isteği gönderin. Bu isteği, userinfo_endpoint meta veri değerini kullanarak Keşif dokümanından almanız gerekir. Userinfo yanıtı, OpenID Connect Standard Claims bölümünde açıklandığı şekilde ve Discovery dokümanının claims_supported meta veri değeri gibi kullanıcıyla ilgili bilgileri içerir. Kullanıcılar veya kuruluşları, belirli alanları sunmayı veya saklamayı tercih edebilir. 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 jetonlar, kullanıcı bilgileri, ortak anahtarlar gibi kaynaklar için istek göndermek üzere birden fazla uç nokta kullanılmasını gerektirir.

OpenID Connect, uygulamaları basitleştirmek ve esnekliği artırmak için "Keşif dokümanı"nın kullanılmasına izin verir. Bu doküman, bilinen bir konumda bulunan ve anahtar/değer çiftleri içeren bir JSON dokümanıdır. Bu doküman; yetkilendirme, jeton, iptal, kullanıcı bilgileri ve ortak anahtar uç noktalarının URI'leri gibi OpenID Connect sağlayıcısının yapılandırması hakkında ayrıntılı bilgi sağlar. Google'ın OpenID Connect hizmetiyle ilgili Discovery dokümanı şuradan alınabilir:

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

Google'ın OpenID Connect hizmetlerini kullanmak için Discovery doküman URI'sını (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ını uygular ve ardından gerektiğinde uç nokta URI'larını dokümandan 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 doküman örneği verilmiştir. Alan adları, OpenID Connect Discovery 1.0'da belirtilen alanlardı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 dokümanının en yeni sürümünden kopyalanmış olsa bile 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"
  ]
}

Discovery dokümanındaki değerleri önbelleğe alarak bir HTTP gidiş dönüşünü önlemek isteyebilirsiniz. Standart HTTP önbelleğe alma üst bilgileri kullanılır ve bunlara saygı gösterilmelidir.

İ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 hizmet ile çalışmalıdır (OpenID İstek Nesnesi hariç).