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:
- Go to the Credentials page.
- Click the name of your credential or the pencil (create) 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:
- Go to the Credentials page.
- In the OAuth 2.0 client IDs section of the page, click a credential.
- 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:
- Aç Consent Screen page yılında Google API Console .
- If prompted, select a project, or create a new one.
- 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.)

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:
- Sahtekarlıkla mücadele durumu jetonu oluşturma
- Google'a kimlik doğrulama isteği gönderme
- Sahtekarlıkla mücadele durumu jetonunu onaylama
- Erişim jetonu ve kimlik jetonu için
code
değişimi - Kimlik jetonundan kullanıcı bilgilerini alma
- 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 pageresponse_type
. Temel yetkilendirme kodu akış isteğindecode
olması gerekir. (Daha fazla bilgi içinresponse_type
adresini ziyaret edin.)scope
. Bu, temel istekteopenid email
olmalıdır. (Daha fazla bilgi içinscope
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 istekredirect_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çinstate
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 olansub
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çinlogin_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çinhd
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 |
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:
Mevcut |
|
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:
Mevcut |
|
profile |
Kullanıcının profil sayfasının URL'si. Aşağıdaki durumlarda sağlanabilir:
Mevcut |
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.
Yeniden izin isteniyor
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'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 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
|
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 ( İ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 |
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:
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:
- 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. - Kimlik jetonundaki
iss
hak talebinin değerininhttps://accounts.google.com
veyaaccounts.google.com
değerine eşit olduğunu doğrulayın. - Kimlik jetonundaki
aud
hak talebinin değerinin, uygulamanızın istemci kimliğiyle aynı olduğunu doğrulayın. - Kimlik jetonunun son kullanım tarihinin (
exp
hak talebi) geçmediğini doğrulayın. - İ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:
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. Hemprofile
hem deemail
belirtmek için kimlik doğrulama isteği URI'nize aşağıdaki parametreyi ekleyebilirsiniz:scope=openid%20profile%20email
- 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ınclaims_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:
- Java için Google API'leri İstemci Kitaplığı
- Python için Google API'leri İstemci Kitaplığı
- .NET için Google API'leri İstemci Kitaplığı
- Ruby için Google API'leri İstemci Kitaplığı
- PHP için Google API'leri İstemci Kitaplığı
- Google Web Araç Seti için OAuth 2.0 Kitaplığı
- Mac OAuth 2.0 Kumandalar için Google Araç Kutusu
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ç).