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 Sertifikalı olan kimlik doğrulama için OAuth 2.0 uygulama açıklanmaktadır. Google API'lerine Erişmek için OAuth 2.0'ı Kullanma sayfasında 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'ı kurma

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şturmanız, OAuth 2.0 kimlik bilgilerini almanız, bir yönlendirme URI'si ayarlamanız ve (isteğe bağlı olarak) kullanıcılarınızın kullanıcı izni ekranında gördüğü marka bilgilerini özelleştirmeniz gerekir. 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'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 bir istemci kimliği ve istemci gizli anahtarı da dahil OAuth 2.0 kimlik bilgilerine sahip olmanız gerekir.

To view the client ID and client secret for a given OAuth 2.0 credential, click the following text: Select credential. In the window that opens, choose your project and the credential you want, then click View.

Or, view your client ID and client secret from the Credentials page in API Console:

  1. Go to the Credentials page.
  2. Click the name of your credential or the pencil () icon. Your client ID and secret are at the top of the page.

Yönlendirme URI'si ayarlama

API Console alanında ayarladığınız yönlendirme URI'si, Google'ın yanıtları kimlik doğrulama isteklerinize göndereceği yeri belirler.

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 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 adresi ve temel hesap bilgilerine erişim izni vermesi istenebilir. Uygulamanızın kimlik doğrulama isteğinde yer aldığı scope parametresini kullanarak bu bilgilere erişim isteğinde bulunursunuz. Kapsamları diğer Google API'lerine erişim istemek için de kullanabilirsiniz.

Kullanıcı izin ekranı; ürün adı, logo ve ana sayfa URL'si gibi marka bilinci oluşturma bilgilerini de sunar. Marka bilgilerini API Console üzerinde 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 bir kombinasyonu bulunuyorsa kullanıcıların ne göreceği gösterilir. (Bu genel iletişim kutusu Google OAuth 2.0 Playground kullanılarak oluşturulmuştur, dolayısıyla API Consoleiçinde ayarlanacak marka bilgileri 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ı, bunlara örnek olarak gösterilebilir.

Kitaplık kullanmamayı tercih ederseniz bu dokümanın geri kalanında yer alan, mevcut kitaplıkların altında HTTP isteği 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 bir kimlik jetonu edinme ve doğrulama. Kimlik jetonları, internetdeki kimlik iddialarını paylaşmak için tasarlanmış standart bir OpenID Connect özelliğidir.

Bir kullanıcının kimliğini doğrulamak ve 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 bir tarayıcı veya mobil cihaz kullanan kişinin kimliğini doğrulamasına olanak sağlar. Doğrudan 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ımında güvenlik riskleri olduğu için dolaylı akış ç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 kimliklerini doğrulaması için uygulamanızı API Consoleuygulamasında ayarladığınızdan emin olun. Bir kullanıcı Google ile giriş yapmayı denediğinde:

  1. Sahtekarlıkla mücadele durumu jetonu oluşturma
  2. Google'a kimlik doğrulama isteği gönderme
  3. Sahtekarlıkla mücadele durumu 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ıkla mücadele durumu jetonu oluşturma

Sahtekarlık saldırılarına karşı önlem alarak kullanıcılarınızın güvenliğini korumanız gerekir. İlk adım, uygulamanız ile kullanıcının istemcisi arasında durumu koruyan benzersiz bir oturum jetonu oluşturmaktır. Daha sonra bu benzersiz oturum jetonunu, kötü amaçlı bir saldırganla değil kullanıcının 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.

Durum jetonu için iyi bir seçenek, yüksek kaliteli rastgele bir sayı oluşturma aracı kullanılarak oluşturulan 30 karakterlik bir dizedir. Bir diğeri ise oturum durumu değişkenlerinizden bazılarının arka ucunda gizli tutulan bir anahtarla imzalanmasıdır.

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

2.999

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 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 istemci kitaplığı 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 olması gerekir. (Daha fazla bilgi için response_type adresini ziyaret edin.)
  • scope. Bu, temel istekte openid email olmalıdır. (Daha fazla bilgi için scope adresini ziyaret edin.)
  • redirect_uri, sunucunuzdaki Google'dan yanıt alacak HTTP uç noktası olmalıdır. Değerin, OAuth 2.0 istemcisi için yapılandırdığınız yetkili yönlendirme URI'lerinden biriyle tam olarak eşleşmesi gerekir. API Console Credentials pageBu değer yetkili bir URI ile eşleşmezse istek redirect_uri_mismatch hatasıyla başarısız olur.
  • state, sahtecilikten korunma 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ı oturum açmış durumdaysa izin ekranında kullanıcının e-posta adresinin uygulamanızda yayınlanması için bir onay isteği bulunur. (Daha fazla bilgi için login_hint adresine bakın.)
  • OpenID Connect akışını bir Google Cloud kuruluşuyla ilişkili belirli bir alanın kullanıcıları için optimize etmek üzere hd parametresini kullanın. (Daha fazla bilgi için hd adresini ziyaret edin.)

Aşağıda, satır sonları ve okunabilirlik boşlukları içeren eksiksiz 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 kullanıcılar hakkında yeni bilgiler isterse veya daha önce onaylamadıkları hesap erişimi isterse kullanıcıların izin vermesi gerekir.

3. Sahtekarlıkla mücadele durumu jetonunu onaylama

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 URL'sinin 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ı değil kullanıcının yapmasını sağlar.

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

2.999

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 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 istemci kitaplığı 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 ile değiştirebileceği tek seferlik bir yetkilendirme kodu olan code parametresi vardır. Sunucunuz bu exchange'i bir HTTPS POST isteği göndererek gerçekleştirir. POST isteği, jeton uç noktasına gönderilir. token_endpoint uç noktası değerini kullanarak Discovery 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 pageüzerinden aldığınız istemci kimliği.
client_secret OAuth 2.0 kimlik bilgilerini alma bölümünde açıklandığı gibi API Console Credentials pageüzerinden aldığınız istemci gizli anahtarı.
redirect_uri Yönlendirme URI'si oluşturma bölümünde açıklandığı gibi, API Console Credentials pageöğesinde belirtilen client_id öğesi 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 ö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 başarılı bir yanıt, JSON dizisinde aşağıdaki alanları içerir:

Alanlar
access_token Bir Google API'sine gönderilebilecek 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 izin verilen, boşlukla sınırlandırılmış ve büyük/küçük harfe duyarlı dizelerin listesi olarak verilen erişim kapsamları.
token_type Döndürülen jetonun türünü tanımlar. Şu an için 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 bulunur. Ayrıntılı bilgi için Jetonları yenileme başlıklı makaleyi inceleyin.

5. Kimlik jetonundan kullanıcı bilgilerini edinme

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

Çoğu API kitaplığı, Base64url olarak kodlanmış değerlerin kodunu çözme ve içindeki JSON kodunu ayrıştırma işiyle doğrulamayı birleştirdiğinden, muhtemelen kimlik jetonundaki hak taleplerine eriştikçe jetonu doğrulayabilirsiniz.

Kimlik jetonunun yükü

Kimlik jetonu, bir ad/değer çifti grubu 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 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 Kimlik jetonunun kabul edilmesi gereken son kullanma tarihi. Unix zamanında temsil edilir (tam sayı saniye).
iat always Kimlik jetonunun verildiği zaman. Unix saatiyle gösterilir (tam sayı olarak).
iss always Sertifikayı Veren için Kuruluşu Tanımlayıcı. Google kimliği jetonları için her zaman https://accounts.google.com veya accounts.google.com.
sub always Kullanıcıya ait, tüm Google hesaplarında benzersiz ve hiçbir zaman kullanılmamış bir tanımlayıcı. 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ı için benzersiz tanımlayıcı anahtarı olarak sub kullanın. Maksimum 255 ASCII karakter uzunluğunda.
at_hash Erişim jetonu karması. Erişim jetonunun kimlik jetonuna bağlı olduğuna dair bir doğrulama sağlar. Kimlik jetonu, sunucu akışında bir access_token değeriyle veriliyorsa 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ı takip ederseniz erişim jetonunu doğrulamanız gerekmez.
azp Yetkili sunucudan client_id. Bu hak talebi, yalnızca kimlik jetonunu isteyen tarafın kimlik jetonunun kitlesiyle aynı olmadığı durumlarda gereklidir. Bir web uygulaması ve 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 böyle bir durum söz konusu 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 olduğunda sağlanabilir.
given_name Kullanıcıya verilen adlar veya adlar. name hak talebi olduğunda sağlanabilir.
hd Kullanıcının Google Cloud kuruluşuyla ilişkilendirilen alan. 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 olduğunda sağlanabilir.
name Kullanıcının görüntülenebilir biçimdeki tam adı. Aşağıdaki durumlarda sağlanabilir:
  • İstek kapsamı "profil" dizesini içeriyor
  • Kimlik jetonu, bir jeton yenilemesinden döndürülür.

Mevcut name hak talepleri varsa bunları uygulamanızın kullanıcı kayıtlarını güncellemek için kullanabilirsiniz. Bu hak talebinin mutlaka yer alacağını unutmayın.

nonce Uygulamanızın kimlik doğrulama isteğinde sağladığı nonce değeridir. Videonun 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ı "profil" dizesini içeriyor
  • Kimlik jetonu, bir jeton yenilemesinden döndürülür.

Mevcut picture hak talepleri varsa bunları uygulamanızın kullanıcı kayıtlarını güncellemek için kullanabilirsiniz. Bu hak talebinin mutlaka yer alacağını unutmayın.

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

Mevcut profile hak talepleri varsa bunları uygulamanızın kullanıcı kayıtlarını güncellemek için kullanabilirsiniz. Bu hak talebinin mutlaka yer alacağını 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. Kullanıcı, veritabanınızda zaten mevcutsa tüm giriş koşulları 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ında yoksa kullanıcıyı yeni kullanıcı kayıt akışınıza yönlendirmeniz gerekir. Google'dan aldığınız bilgilere dayanarak kullanıcıyı otomatik olarak kaydedebilirsiniz veya 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 alabilirsiniz.

İ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 bilgiler, kimlik doğrulama ve yetkilendirmeyle ilgili gelişmiş şartları 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 kullanıcı kimlik doğrulamasıyla 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 Google'a gönderdiğiniz kimlik doğrulama isteğine ihtiyacınız olan diğer kapsamları 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ıdan uygun şekilde izin ekranında izin 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ı yenile

API erişimi isteğinizde, code değişimi 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ş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ğinizden yenileme jetonunu güvenli ve kalıcı bir şekilde sakladığınızdan emin olun.
  • Yapılan yenileme jetonlarının sayısı sınırlıdır: istemci/kullanıcı kombinasyonu başına bir sınır ve tüm istemciler için kullanıcı başına başka bir sınır. Uygulamanız çok fazla yenileme jetonu isterse bu sınırlara tabi olabilir. Bu durumda eski yenileme jetonları kullanılamaz.

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, uygulamanız daha önce tüm Google API'leri projenize verilmiş olsa bile izin kapsamları her yetkilendirme isteğinde bulunduğunda izin ekranı gösterilir. Bu nedenle, prompt=consent seçeneğini yalnızca gerektiğinde ekleyin.

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

Authentication URI parametreleri

Aşağıdaki tabloda, Google'ın OAuth 2.0 kimlik doğrulama API'si tarafından kabul edilen parametreler hakkında daha kapsamlı açıklamalar sunulmaktadır.

Parametre Zorunlu Açıklama
client_id (Gerekli) OAuth 2.0 kimlik bilgilerini alma bölümünde açıklandığı gibi, API Console Credentials pageüzerinden aldığınız istemci kimliği dizesi.
nonce (Gerekli) Uygulamanızın oluşturduğu ve tekrar koruma korumasını sağlayan rastgele bir değer.
response_type (Gerekli) Değer code ise jetonları almak için jeton uç noktasına bir POST gerektiren Temel yetkilendirme kodu akışı başlatılı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'in kullanılmasını gerektiren bir Dolaylı akış başlatır.
redirect_uri (Gerekli) Yanıtın nereye gönderildiğini belirler. Bu parametrenin değeri, API Console Credentials page içinde ayarladığınız yetkili yönlendirme değerlerinden biriyle(HTTP veya HTTPS şeması, büyük/küçük harf ve varsa sondaki "/" dahil) 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 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.

OpenID'ye özgü bu 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 belgelere bakın.

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

Protokolde gidiş-dönüşlü, yani 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 tahmini yapabildiğinden bir 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ğundan emin olmanızı sağlayabilir. Bu state değişkeninde rastgele bir dize oluşturur veya bazı istemci durumlarının (ör. çerez) karmasını kodlarsanız hem isteğin hem de yanıtın aynı tarayıcıda oluştuğ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 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üleyeceğini belirtmek için bir ASCII dize değeri. Şu değerler Google sunucuları tarafından belirlenir ve kabul edilir, ancak davranışı üzerinde herhangi bir etkisi yoktur: page, popup, touch ve wap.
hd (İsteğe bağlı)

Bir Google Cloud kuruluşuna ait hesaplar için giriş sürecini 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 üzere yıldız işaretinin (*) değerini 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 parametresinden farklı olarak, kimlik jetonu hd hak talebi, Google'ın sağladığı bir 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 verildiyse yetkilendirme, diğer kapsamlar için bu kullanıcı/uygulama kombinasyonuna daha önce verilen tüm yetkilendirmeleri 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 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). Bu durumda, uygulamanız yanlış kullanıcı hesabına giriş yaparsa meydana gelebilecek sorunları önleyebilirsiniz. Değer, bir kullanıcının e-posta adresi veya kullanıcının Google kimliğine eşdeğer 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 doğrulanmamışsa ve istenen kapsamlar için izni önceden yapılandırmamışsa bir hata döndürür. Mevcut kimlik doğrulama ve/veya izin kontrolü 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 kullanıcı hesabı seçmesini ister. Bu sayede, yetkilendirme sunucusunda birden fazla hesabı olan kullanıcılar, mevcut oturumları olabilecek 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

Doğrudan Google'dan geldiğini bilmediğiniz sürece sunucunuzdaki tüm kimlik jetonlarını 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ı yapılması gereken istekler içeren kimlik jetonları gönderme. Kimlik jetonları, istekte bulunan belirli kullanıcıyı ve bu kimlik jetonunun hangi istemci için verildiğini gösterir.

Kimlik jetonları hassastır ve ele geçirilirse hatalı şekilde kullanılabilir. Bu jetonların yalnızca HTTPS üzerinden ve yalnızca POST verileri aracılığıyla veya 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ı yararlı kılan unsurlardan biri de bunları uygulamanızın farklı bileşenlerinin etrafına geçirebilmenizdir. Bu bileşenler, uygulama ve kullanıcının kimliğini doğrulayan basit bir kimlik doğrulama mekanizması olarak kimlik jetonunu kullanabilir. Ancak kimlik jetonundaki bilgileri kullanmadan veya kullanıcının kimlik doğrulamasına dair bir onay olarak kullanmadan önce bu bilgiyi 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'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ğiyle aynı olduğunu doğrulayın.
  4. Kimlik jetonunun son kullanım tarihinin (exp hak talebi) geçmediğini doğrulayın.
  5. İstekte hd parametresi değeri belirlediyseniz kimlik jetonunun, bir Google Cloud kuruluşuyla ilişkili kabul edilen bir alan adıyla eşleşen bir hd hak talebi olduğunu doğrulayın.

2. - 5. adımlar yalnızca oldukça basit olan dize ve tarih karşılaştırmalarını içerir. Bu yüzden, bunları burada detaylandırmıyoruz.

İlk adım daha karmaşıktır ve kriptografik imza kontrolü içerir. Hata ayıklama amacıyla Google'ın tokeninfo uç noktasını kullanarak sunucunuzda veya cihazınızda uygulanan yerel işlemeyi karşılaştırabilirsiniz. Kimlik jetonunuzun değerinin XYZ123 olduğunu varsayalım. Ardından 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 formundaki JWT yükü olur.

tokeninfo uç noktası, hata ayıklama için faydalıdır ancak üretim amacıyla anahtarların uç noktasından Google'ın ortak anahtarlarını alın ve doğrulamayı yerel olarak gerçekleştirin. Anahtarlar 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 zaman zaman hatalara maruz kalabilir.

Google, ortak anahtarlarını çok nadir değiştirdiği için HTTP yanıtının önbellek yönergelerini kullanarak önbellekleri önbelleğe alabilir ve çoğu durumda yerel doğrulamayı tokeninfo uç noktasına göre ç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 kriptografik çağrıların yapılmasını gerektirir. Neyse ki bunu başarmak için çeşitli dillerde hata ayıklama yapılmış kitaplıklar vardır (jwt.io sayfasına bakın).

Kullanıcı profili bilgilerini edinme

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 için ek bir kapsam değeri belirtebilirsiniz. Hem profile hem de email 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 Discovery dokümanından almanız gerekir. Userinfo yanıtı, kullanıcıyla ilgili bilgileri (OpenID Connect Standard Claims bölümünde açıklandığı gibi) ve Discovery dokümanının claims_supported meta veri değerini içerir. Kullanıcılar veya kuruluşları belirli alanları sağlamayı veya saklamayı tercih edebilir. Bu nedenle, yetkili erişim kapsamlarınız için her alanla ilgili bilgi alamayabilirsiniz.

Discovery dokümanı

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

OpenID Connect, uygulamaları basitleştirmek ve esnekliği artırmak için yetkilendirme, jeton, iptal, kullanıcı bilgileri ve ortak anahtar uç noktalarının URI'leri de dahil olmak üzere OpenID Connect sağlayıcısının yapılandırmasıyla ilgili ayrıntılar sağlayan iyi bilinen bir konumda bulunan ve anahtar/değer çiftleri içeren bir JSON dokümanı olan "Discovery dokümanı"nın kullanılmasına izin veriyor. 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 kodlama yapmanız gerekir. Uygulamanız belgeyi getirir, yanıtta önbelleğe alma kuralları uygular, 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, authorization_endpoint meta veri değerini (aşağıdaki örnekte https://accounts.google.com/o/oauth2/v2/auth) Google'a gönderilen kimlik doğrulama istekleri için temel URI olarak 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 örnektir ve gerçek Google Discovery dokümanının en son sürümünden kopyalanmış olsalar da 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"
  ]
}

HTTP dokümanındaki değerleri önbelleğe alarak bir HTTP gidiş dönüşü önlemeniz mümkün olabilir. Standart HTTP önbelleğe alma üstbilgileri kullanılır ve bu kurallara saygı duyulmalıdır.

İstemci kitaplıkları

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