Google'ın OAuth 2.0 API'leri hem kimlik doğrulama hem de yetkilendirme için kullanılabilir. Bu dokümanda, kimlik doğrulama için OpenID Connect spesifikasyonuna uygun ve OpenID Sertifikalı olan OAuth 2.0 uygulamamız açıklanmaktadır. Google API'lerine Erişmek için OAuth 2.0'ı Kullanma bölümünde yer alan dokümanlar bu hizmet için de geçerlidir. Bu protokolü etkileşimli bir şekilde keşfetmek istiyorsanız Google OAuth 2.0 Playground'u öneririz. Stack Overflow hakkında yardım almak için sorularınızı "google-oauth" ile etiketleyin.
OAuth 2.0 kurulumu
Uygulamanızın, kullanıcı girişi için Google'ın OAuth 2.0 kimlik doğrulama sistemini kullanabilmesi için Google API Console içinde bir proje oluşturarak OAuth 2.0 kimlik bilgilerini almalı, yönlendirme URI'si ayarlamalı ve (isteğe bağlı olarak) kullanıcılarınızın kullanıcı izin ekranında gördüğü marka bilgilerini özelleştirmelisiniz. Hizmet hesabı oluşturmak, faturalandırmayı etkinleştirmek, filtrelemeyi ayarlamak ve diğer görevleri yapmak için de API Console aracını kullanabilirsiniz. Daha fazla bilgi için Google API Console Yardım sayfasına göz atın.
OAuth 2.0 kimlik bilgilerini alma
Kullanıcıların kimliğini doğrulamak ve Google API'lerine erişim elde etmek için istemci kimliği ve istemci gizli anahtarı dahil OAuth 2.0 kimlik bilgilerine ihtiyacınız vardır.
Belirli bir OAuth 2.0 kimlik bilgisinin istemci kimliğini ve istemci sırrını görüntülemek için aşağıdaki metni tıklatın: Kimlik bilgilerini seçin . Açılan pencerede projenizi ve istediğiniz kimlik bilgilerini seçin, ardından Görüntüle'yi tıklayın.
Veya müşteri kimliğinizi ve müşteri sırrınızı API Console Kimlik Bilgileri sayfasından API Console :
- Go to the Credentials page.
- Kimlik bilgilerinizin adını veya kurşun kalem ( create ) simgesini tıklayın. Müşteri kimliğiniz ve sırrınız sayfanın en üstünde.
Yönlendirme URI'si ayarlayın
API Console öğesinde ayarladığınız yönlendirme URI'si, Google'ın kimlik doğrulama isteklerinize yanıtları nereye göndereceğini belirler.
Belirli bir OAuth 2.0 kimlik bilgileri için yönlendirme URI'leri oluşturmak, görüntülemek veya düzenlemek için aşağıdakileri yapın:
- Go to the Credentials page.
- Sayfanın OAuth 2.0 istemci kimlikleri bölümünde bir kimlik bilgilerini tıklatın.
- Yönlendirme URI'lerini görüntüleyin veya düzenleyin.
Kimlik Bilgileri sayfasında OAuth 2.0 istemci kimlikleri bölümü yoksa, projenizde OAuth kimlik bilgileri yoktur. Bir tane oluşturmak için Kimlik bilgileri oluştur'u tıklayın.
Kullanıcı rızası ekranını özelleştirme
Kullanıcılarınız için OAuth 2.0 kimlik doğrulama deneyiminde, kullanıcının yayınladığı bilgileri ve geçerli şartları açıklayan bir izin ekranı bulunur. Örneğin, kullanıcı giriş yaptığında, uygulamanızın e-posta adresine ve temel hesap bilgilerine erişmesine izin vermesi istenebilir. Uygulamanızın kimlik doğrulama isteğine eklediği scope
parametresini kullanarak bu bilgilere erişim talep edersiniz. Kapsamları, diğer Google API'lerine erişim istemek için de kullanabilirsiniz.
Kullanıcı izni ekranında ürün adınız, logonuz ve ana sayfanızın URL'si gibi marka bilgileri de sunulur. Marka bilgilerini API Consolebölümünden kontrol edebilirsiniz.
Projenizin onay ekranını etkinleştirmek için:
- 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, OAuth 2.0 ve Google Drive kapsamlarının kombinasyonu mevcut olduğunda kullanıcıların ne göreceği gösterilmektedir. (Bu genel iletişim kutusu Google OAuth 2.0 Playground kullanılarak oluşturulduğu için API Consoleiçinde ayarlanacak marka bilgilerini içermez.)
![İzin sayfasının ekran görüntüsü](https://developers-dot-devsite-v2-prod.appspot.com/static/identity/protocols/oauth2/images/examples/scope-authorization.png?authuser=9&hl=tr)
Hizmete erişme
Google ve üçüncü taraflar, kullanıcıların kimliklerini doğrulama ve Google API'lerine erişmeyle ilgili uygulama ayrıntılarının birçoğuyla ilgilenmek için kullanabileceğiniz kitaplıklar sağlar. Örnekler arasında Google Kimlik Hizmetleri ve çeşitli platformlarda kullanılabilen Google istemci kitaplıkları sayılabilir.
Kitaplığı kullanmamayı tercih ederseniz bu belgenin geri kalanında bulunan, kullanılabilir kitaplıkların temelindeki HTTP isteği akışlarını açıklayan talimatları uygulayın.
Kullanıcının kimliğini doğrulama
Kullanıcının kimliğinin doğrulanması, kimlik jetonu alıp doğrulamayı içerir. Kimlik jetonları, OpenID Connect'in internette kimlik onaylarını paylaşmak için tasarlanmış standart bir özelliğidir.
Kullanıcının kimliğini doğrulamak ve kimlik jetonu almak için en yaygın olarak kullanılan yaklaşımlar "sunucu" akışı ve "örtülü" akış olarak adlandırılır. Sunucu akışı, uygulamanın arka uç sunucusunun bir tarayıcı veya mobil cihaz kullanarak kişinin kimliğini doğrulamasını sağlar. Dolaylı akış, bir istemci tarafı uygulamanın (genellikle tarayıcıda çalışan bir JavaScript uygulaması) API'lere arka uç sunucusu yerine doğrudan erişmesi gerektiğinde kullanılır.
Bu dokümanda, kullanıcının kimliğini doğrulamak için sunucu akışının nasıl gerçekleştirileceği açıklanmaktadır. Örtülü akış, istemci tarafında jetonların işlenmesi ve kullanılmasıyla ilgili güvenlik riskleri nedeniyle çok daha karmaşıktır. Dolaylı bir akış uygulamanız gerekiyorsa Google Kimlik Hizmetleri'ni kullanmanızı önemle tavsiye ederiz.
Sunucu akışı
Bu protokolleri kullanması ve kullanıcılarınızın kimliğini doğrulaması için uygulamanızı API Consoleiçinde ayarladığınızdan emin olun. Bir kullanıcı Google ile giriş yapmaya çalıştığında şunları yapmanız gerekir:
- Sahtekarlığa karşı durum jetonu oluşturma
- Google'a kimlik doğrulama isteği gönderme
- Sahtekarlığa karşı koruma durum jetonunu onaylama
- Erişim jetonu ve kimlik jetonu için Exchange
code
- Kimlik jetonundan kullanıcı bilgilerini alma
- Kullanıcının kimliğini doğrulama
1. Sahtekarlığa karşı durum jetonu oluşturma
Sahte istek saldırılarını önleyerek kullanıcılarınızın güvenliğini korumanız gerekir. İlk adım, uygulamanız ile kullanıcının istemcisi arasındaki durumu koruyan benzersiz bir oturum jetonu oluşturmaktır. Daha sonra bu benzersiz oturum jetonunu, Google OAuth Giriş hizmeti tarafından döndürülen kimlik doğrulama yanıtıyla eşleştirerek istekte kullanıcının kötü amaçlı bir saldırgandan değil, kullanıcının istekte bulunduğunu doğrularsınız. Bu jetonlar genellikle siteler arası istek sahtekarlığı (CSRF) jetonları olarak adlandırılır.
Durum jetonu için iyi bir tercih, yüksek kaliteli bir rastgele sayı oluşturma aracı kullanılarak oluşturulan 30 veya daha fazla karakterden oluşan bir dizedir. Bir diğeri, oturum durumu değişkenlerinizden bazılarının arka ucunuzda gizli tutulan bir anahtarla imzalanmasıyla oluşturulan bir karmadır.
Aşağıdaki kod, benzersiz oturum jetonları oluşturmayı göstermektedir.
PHP
Bu örneği kullanmak istiyorsanız PHP için Google API'leri istemci kitaplığını indirmeniz gerekir.
// Create a state token to prevent request forgery. // Store it in the session for later validation. $state = bin2hex(random_bytes(128/8)); $app['session']->set('state', $state); // Set the client ID, token state, and application name in the HTML while // serving it. return $app['twig']->render('index.html', array( 'CLIENT_ID' => CLIENT_ID, 'STATE' => $state, 'APPLICATION_NAME' => APPLICATION_NAME ));
Java
Bu örneği kullanmak istiyorsanız Java için Google API'leri istemci kitaplığını indirmeniz gerekir.
// Create a state token to prevent request forgery. // Store it in the session for later validation. String state = new BigInteger(130, new SecureRandom()).toString(32); request.session().attribute("state", state); // Read index.html into memory, and set the client ID, // token state, and application name in the HTML before serving it. return new Scanner(new File("index.html"), "UTF-8") .useDelimiter("\\A").next() .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID) .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state) .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}", APPLICATION_NAME);
Python
Bu örneği kullanmak istiyorsanız Python için Google API'leri istemci kitaplığını indirmeniz gerekir.
# Create a state token to prevent request forgery. # Store it in the session for later validation. state = hashlib.sha256(os.urandom(1024)).hexdigest() session['state'] = state # Set the client ID, token state, and application name in the HTML while # serving it. response = make_response( render_template('index.html', CLIENT_ID=CLIENT_ID, STATE=state, APPLICATION_NAME=APPLICATION_NAME))
2. Google'a kimlik doğrulama isteği gönderin
Sonraki adım, uygun URI parametreleriyle bir HTTPS GET
isteği oluşturmaktır.
Bu sürecin tüm adımlarında HTTP yerine HTTPS kullanımına dikkat edin; HTTP bağlantıları reddedilir. Temel URI'yı, authorization_endpoint
meta veri değerini kullanarak Keşif belgesinden almanız gerekir. Aşağıdaki açıklamada temel URI'nın https://accounts.google.com/o/oauth2/v2/auth
olduğu varsayılır.
Temel bir istek için aşağıdaki parametreleri belirtin:
client_id
. Bu bilgiyi şu adresten edinebilirsiniz: API Console Credentials page .response_type
; temel yetkilendirme kodu akış isteğindecode
olmalıdır. (response_type
adresinde daha fazla bilgi edinebilirsiniz.)scope
; bu, temel bir istekteopenid email
olmalıdır. (scope
adresinde daha fazla bilgi bulabilirsiniz.)redirect_uri
, sunucunuzda Google'dan yanıt alacak HTTP uç noktası olmalıdır. Değer, OAuth 2.0 istemcisi için API Console Credentials pageiçinde yapılandırdığınız yetkilendirilmiş yönlendirme URI'lerinden biriyle tam olarak eşleşmelidir. Bu değer, yetkili bir URI ile eşleşmezse istekredirect_uri_mismatch
hatasıyla başarısız olur.state
, sahtekârlığa karşı benzersiz oturum jetonunun yanı sıra kullanıcı uygulamanıza döndüğünde bağlamı kurtarmak için gereken diğer bilgileri (ör. başlangıç URL'si) içermelidir. (state
adresinde daha fazla bilgi bulabilirsiniz.)nonce
, uygulamanız tarafından oluşturulan ve mevcut olduğunda tekrar oynatma koruması sağlayan rastgele bir değerdir.login_hint
, kullanıcının e-posta adresi veya kullanıcının Google kimliğine denk gelensub
dizesi olabilir.login_hint
sağlamazsanız ve kullanıcı şu anda giriş yapmışsa izin ekranında kullanıcının e-posta adresinin uygulamanızda yayınlanması için onay isteği görüntülenir. (Daha fazla bilgi içinlogin_hint
adresini ziyaret edin.)- Bir Google Workspace veya Cloud kuruluşuyla ilişkili belirli bir alanın kullanıcıları için OpenID Connect akışını optimize etmek üzere
hd
parametresini kullanın (daha fazla bilgi içinhd
sayfasına bakın).
Aşağıda, okunabilirlik için satır sonları ve boşluklar içeren eksiksiz bir OpenID Connect kimlik doğrulama URI'sı örneği verilmiştir:
https://accounts.google.com/o/oauth2/v2/auth? response_type=code& client_id=424911365001.apps.googleusercontent.com& scope=openid%20email& redirect_uri=https%3A//oauth2.example.com/code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome& login_hint=jsmith@example.com& nonce=0394852-3190485-2490358& hd=example.com
Uygulamanız kendileri hakkında yeni bilgiler isterse veya uygulamanız daha önce onaylamadıkları hesap erişimi istiyorsa kullanıcıların izin vermesi gerekir.
3. Sahtekarlığa karşı durum jetonunu onaylayın
Yanıt, istekte belirttiğiniz redirect_uri
öğesine gönderilir. Tüm yanıtlar, aşağıda gösterildiği gibi sorgu dizesinde döndürülür:
https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email
Sunucuda, Google'dan alınan state
değerinin 1. adımda oluşturduğunuz oturum jetonuyla eşleştiğini onaylamanız gerekir. Bu gidiş dönüş doğrulama, isteği kötü amaçlı bir komut dosyasının değil, kullanıcının yaptığından emin olunmasına yardımcı olur.
Aşağıdaki kod, 1. adımda oluşturduğunuz oturum jetonlarını onaylama işlemini gösterir:
PHP
Bu örneği kullanmak istiyorsanız PHP için Google API'leri istemci kitaplığını indirmeniz gerekir.
// Ensure that there is no request forgery going on, and that the user // sending us this connect request is the user that was supposed to. if ($request->get('state') != ($app['session']->get('state'))) { return new Response('Invalid state parameter', 401); }
Java
Bu örneği kullanmak istiyorsanız Java için Google API'leri istemci kitaplığını indirmeniz gerekir.
// Ensure that there is no request forgery going on, and that the user // sending us this connect request is the user that was supposed to. if (!request.queryParams("state").equals( request.session().attribute("state"))) { response.status(401); return GSON.toJson("Invalid state parameter."); }
Python
Bu örneği kullanmak istiyorsanız Python için Google API'leri istemci kitaplığını indirmeniz gerekir.
# Ensure that the request is not a forgery and that the user sending # this connect request is the expected user. if request.args.get('state', '') != session['state']: response = make_response(json.dumps('Invalid state parameter.'), 401) response.headers['Content-Type'] = 'application/json' return response
4. Erişim jetonu ve kimlik jetonu için Exchange code
Yanıt, sunucunuzun bir erişim jetonu ve kimlik jetonuyla değiştirebileceği tek seferlik bir yetkilendirme kodu olan code
parametresini içerir. Sunucunuz bu değişimi bir HTTPS POST
isteği göndererek gerçekleştirir. POST
isteği jeton uç noktasına gönderilir. Bunu, token_endpoint
meta veri değerini kullanarak Discovery belgesinden almanız gerekir. Aşağıdaki açıklamada, uç noktanın https://oauth2.googleapis.com/token
olduğu varsayılmaktadır. İsteğin POST
gövdesinde aşağıdaki parametreleri içermesi gerekir:
Alanlar | |
---|---|
code |
İlk istekten döndürülen yetkilendirme kodu. |
client_id |
OAuth 2.0 kimlik bilgilerini alma bölümünde açıklandığı gibi, Credentials page API Consolehizmetinden edindiğiniz istemci kimliği. |
client_secret |
OAuth 2.0 kimlik bilgilerini alma bölümünde açıklandığı gibi, API Console Credentials pagehizmetinden aldığınız istemci gizli anahtarı. |
redirect_uri |
Yönlendirme URI'si ayarlama bölümünde açıklanan şekilde API Console
Credentials pageiçinde belirtilen belirtilen client_id için yetkili yönlendirme URI'si. |
grant_type |
Bu alan,
OAuth 2.0 spesifikasyonunda tanımlandığı gibi authorization_code değerini içermelidir. |
Asıl istek aşağıdaki örnek gibi görünebilir:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your-client-id& client_secret=your-client-secret& redirect_uri=https%3A//oauth2.example.com/code& grant_type=authorization_code
Bu isteğe verilen başarılı bir yanıt, bir JSON dizisinde aşağıdaki alanları içerir:
Alanlar | |
---|---|
access_token |
Google API'lerine gönderilebilen bir jeton. |
expires_in |
Erişim jetonunun kalan ömrü (saniye cinsinden). |
id_token |
Kullanıcıyla ilgili kimlik bilgilerini içeren ve Google tarafından dijital olarak imzalanmış bir JWT. |
scope |
access_token tarafından verilen erişim kapsamları, boşlukla sınırlandırılmış, büyük/küçük harfe duyarlı dizelerden oluşan bir liste olarak ifade edilir. |
token_type |
Döndürülen jetonun türünü tanımlar. Şu anda bu alan her zaman Bearer değerini alır.
|
refresh_token |
(isteğe bağlı)
Bu alan yalnızca kimlik doğrulama isteğinde |
5. Kimlik jetonundan kullanıcı bilgilerini alma
Kimlik Jetonu bir JWT (JSON Web Jetonu) yani kriptografik olarak imzalanmış Base64 kodlu bir JSON nesnesidir. Normalde, bir kimlik jetonunu kullanmadan önce doğrulamanız çok önemlidir, ancak aracı gerektirmeyen bir HTTPS kanalı üzerinden doğrudan Google ile iletişim kurduğunuzdan ve Google'da kimliğinizi doğrulamak için istemci sırrınızı kullandığınızdan, aldığınız jetonun gerçekten Google'dan geldiğinden ve geçerli olduğundan emin olabilirsiniz. Sunucunuz kimlik jetonunu uygulamanızın diğer bileşenlerine iletiyorsa diğer bileşenlerin jetonu kullanmadan önce jetonu doğrulaması son derece önemlidir.
Çoğu API kitaplığı, doğrulamayı base64url kodlu değerlerin kodunu çözme ve içindeki JSON'u ayrıştırma işlemiyle birleştirdiğinden kimlik jetonundaki hak taleplerine erişirken muhtemelen jetonu yine de doğrularsınız.
Kimlik jetonunun yükü
Kimlik jetonu, bir dizi ad/değer çifti içeren bir JSON nesnesidir. Okunabilirlik için biçimlendirilmiş bir örneği aşağıda bulabilirsiniz:
{ "iss": "https://accounts.google.com", "azp": "1234987819200.apps.googleusercontent.com", "aud": "1234987819200.apps.googleusercontent.com", "sub": "10769150350006150715113082367", "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q", "hd": "example.com", "email": "jsmith@example.com", "email_verified": "true", "iat": 1353601026, "exp": 1353604926, "nonce": "0394852-3190485-2490358" }
Google Kimlik Jetonları aşağıdaki alanları içerebilir (hak talepleri olarak bilinir):
İddia | Sağlandı | Açıklama |
---|---|---|
aud |
always | Bu kimlik jetonunun hedeflendiği kitle. Uygulamanızın OAuth 2.0 istemci kimliklerinden biri olmalıdır. |
exp |
always | Son kullanma tarihi veya geçtikten sonra kimlik jetonunun kabul edilmemesi gerekir. Unix zamanıyla (saniye cinsinden) temsil edilir. |
iat |
always | Kimlik jetonunun verildiği zaman. Unix zamanıyla (tam sayı saniye) gösterilir. |
iss |
always | Yanıtı Veren için Düzenleyen Kuruluş Tanımlayıcısı. Google kimlik jetonları için her zaman https://accounts.google.com veya accounts.google.com . |
sub |
always | Kullanıcı tanımlayıcısıdır, tüm Google hesaplarında benzersizdir ve hiçbir zaman tekrar kullanılmaz. Bir Google Hesabı, farklı zamanlarda birden fazla e-posta adresine sahip olabilir ancak sub değeri hiçbir zaman değişmez. Uygulamanızda kullanıcının benzersiz tanımlayıcı anahtarı olarak sub kullanın. Büyük/küçük harfe duyarlı maksimum 255 ASCII karakter uzunluğu. |
at_hash |
Erişim jetonu karması. Erişim jetonunun kimlik jetonuna bağlı olduğunun doğrulanmasını sağlar. Kimlik jetonu, sunucu akışında access_token değeriyle verilirse bu hak talebi her zaman dahil edilir. Bu hak talebi, siteler arası istek sahtekarlığı saldırılarına karşı koruma sağlamak için alternatif bir mekanizma olarak kullanılabilir ancak 1. adımı ve 3. adımı uygularsanız erişim jetonunu doğrulamanız gerekmez. |
|
azp |
Yetkili sunucunun client_id . Bu hak talebi, yalnızca kimlik jetonunu isteyen taraf, kimlik jetonunun kitlesiyle aynı olmadığında gerekir. Bu durum, Google'da web uygulaması ile Android uygulamasının farklı bir OAuth 2.0 client_id değerine sahip olduğu ancak aynı Google API'leri projesini paylaştığı karma uygulamalar için geçerli olabilir. |
|
email |
Kullanıcının e-posta adresi. Yalnızca isteğinize email kapsamını dahil ettiyseniz sağlanır. Bu hak talebinin değeri, bu hesaba özel olmayabilir ve zaman içinde değişebilir. Bu nedenle, bu değeri kullanıcı kaydınıza bağlantı oluşturmak için birincil tanımlayıcı olarak kullanmamalısınız. Ayrıca, Google Workspace veya Cloud kuruluşlarının kullanıcılarını belirlemek için email hak talebinin alanından yararlanamazsınız. Bunun yerine hd hak talebini kullanın. |
|
email_verified |
Kullanıcının e-posta adresi doğrulandıysa doğru değerini alır, aksi takdirde yanlış değerini alır. | |
family_name |
Kullanıcının soyadı. name hak talebi mevcut olduğunda sağlanabilir. |
|
given_name |
Kullanıcının adı veya adları. name hak talebi mevcut olduğunda sağlanabilir. |
|
hd |
Kullanıcının Google Workspace veya Cloud kuruluşuyla ilişkili alan adı. Yalnızca kullanıcı bir Google Cloud kuruluşunda yer alıyorsa sağlanır. Bir kaynağa erişimi yalnızca belirli alanların üyeleriyle kısıtlarken bu hak talebini kontrol etmeniz gerekir. Bu iddianın olmaması, hesabın Google tarafından barındırılan bir alana ait olmadığını gösterir. | |
locale |
Kullanıcının BCP 47 dil etiketiyle gösterilen yerel ayarı.
name hak talebi mevcut olduğunda sağlanabilir. |
|
name |
Kullanıcının görüntülenebilir bir biçimde tam adı. Aşağıdaki durumlarda sağlanabilir:
|
|
nonce |
Uygulamanızın kimlik doğrulama isteğinde sağladığı nonce değeri.
Tekrar oynatma saldırılarına karşı yalnızca bir kez sunulduğundan emin olarak koruma sağlamalısınız. |
|
picture |
Kullanıcının profil resminin URL'si. Aşağıdaki durumlarda sağlanabilir:
|
|
profile |
Kullanıcının profil sayfasının URL'si. Aşağıdaki durumlarda sağlanabilir:
|
6. Kullanıcının kimliğini doğrulayın
Kimlik jetonundan kullanıcı bilgilerini aldıktan sonra, uygulamanızın kullanıcı veritabanını sorgulamanız gerekir. Kullanıcı zaten veritabanınızda mevcutsa Google API yanıtı tüm giriş gereksinimlerinin karşılanması durumunda bu kullanıcı için bir uygulama oturumu başlatmanız gerekir.
Kullanıcı kullanıcı veritabanınızda yoksa kullanıcıyı yeni kullanıcı kaydı akışınıza yönlendirmeniz gerekir. Google'dan aldığınız bilgilere göre kullanıcıyı otomatik olarak kaydedebilir veya en azından kayıt formunuzda ihtiyacınız olan alanların birçoğunu önceden doldurabilirsiniz. Kimlik jetonundaki bilgilere ek olarak, kullanıcı profili uç noktalarımızda ek kullanıcı profili bilgileri alabilirsiniz.
İleri düzey konular
Aşağıdaki bölümlerde Google OAuth 2.0 API daha ayrıntılı olarak açıklanmaktadır. Bu bilgi, kimlik doğrulama ve yetkilendirme konusunda ileri düzey gereksinimleri olan geliştiriciler için hazırlanmıştır.
Diğer Google API'lerine erişim
Kimlik doğrulama için OAuth 2.0 kullanmanın avantajlarından biri, kullanıcının kimliğini doğrularken uygulamanızın kullanıcı adına diğer Google API'lerini (YouTube, Google Drive, Takvim veya Kişiler gibi) kullanma izni alabilmesidir. Bunu yapmak için Google'a gönderdiğiniz kimlik doğrulama isteğine ihtiyaç duyduğunuz diğer kapsamları ekleyin. Örneğin, kimlik doğrulama isteğinize kullanıcının yaş grubunu eklemek için openid email https://www.googleapis.com/auth/profile.agerange.read
kapsam parametresini iletin. İzin ekranında kullanıcıya uygun bir şekilde istem gösterilir. Google'dan aldığınız erişim jetonu, istediğiniz ve izin verilen erişim kapsamlarıyla ilgili tüm API'lere erişmenizi sağlar.
Jetonları yenile
API erişimi isteğinizde code
değişimi sırasında döndürülmesi için bir yenileme jetonu isteyebilirsiniz. Yenileme jetonu, kullanıcı uygulamanızda yokken uygulamanızın Google API'lerine sürekli erişimini sağlar. Yenileme jetonu istemek için kimlik doğrulama isteğinizde access_type
parametresini offline
olarak ayarlayın.
Dikkat etmeniz gereken noktalar:
- Yenileme jetonunu yalnızca kod değişimi akışını ilk kez gerçekleştirdiğinizde alabileceğiniz için yenileme jetonunu güvenli ve kalıcı bir şekilde sakladığınızdan emin olun.
- Yayınlanan yenileme jetonlarının sayısına yönelik sınırlar vardır: istemci/kullanıcı kombinasyonu başına bir sınır ve tüm istemcilerde kullanıcı başına bir sınır. Uygulamanız çok fazla yenileme jetonu isterse bu sınırlarla karşılaşabilir ve bu durumda eski yenileme jetonları çalışmayı durdurur.
Daha fazla bilgi için Erişim jetonunu yenileme (çevrimdışı erişim) bölümüne göz atın.
Yeniden izin verilmesi isteniyor
Kimlik doğrulama isteğinizde prompt
parametresini consent
olarak ayarlayarak kullanıcıdan uygulamanızı yeniden yetkilendirmesini isteyebilirsiniz. prompt=consent
dahil edildiğinde, tüm kapsamlar daha önce Google API'leri projenize verilmiş olsa bile uygulamanız erişim kapsamları için her yetkilendirme istediğinde izin ekranı görüntülenir. Bu nedenle, prompt=consent
öğesini yalnızca gerektiğinde ekleyin.
prompt
parametresi hakkında daha fazla bilgi için Kimlik doğrulama URI'si parametreleri tablosundaki prompt
bölümüne bakın.
Kimlik doğrulama URI'si parametreleri
Aşağıdaki tabloda, Google'ın OAuth 2.0 kimlik doğrulama API'si tarafından kabul edilen parametrelerle ilgili daha kapsamlı açıklamalar verilmiştir.
Parametre | Gerekli | Açıklama |
---|---|---|
client_id |
(Zorunlu) | OAuth 2.0 kimlik bilgilerini alma bölümünde açıklandığı gibi, API Console Credentials pagekaynağından aldığınız istemci kimliği dizesi. |
nonce |
(Zorunlu) | Uygulamanız tarafından oluşturulan ve tekrar oynatma korumasını etkinleştiren rastgele bir değer. |
response_type |
(Zorunlu) | Değer code ise Temel yetkilendirme kodu akışını başlatır ve jetonları almak için jeton uç noktasına POST gönderilmesini gerektirir. Değer token id_token veya id_token token ise Dolaylı akış başlatır. Bu da URI #fragment tanımlayıcısından jeton almak için yönlendirme URI'sında JavaScript'in kullanılmasını gerektirir. |
redirect_uri |
(Zorunlu) | Yanıtın nereye gönderileceğini belirler. Bu parametrenin değeri, API Console Credentials page içinde ayarladığınız yetkili yönlendirme değerlerinden biriyle tam olarak eşleşmelidir(HTTP veya HTTPS şeması, büyük/küçük harf ve varsa sondaki "/" dahil). |
scope |
(Zorunlu) | Kapsam parametresi,
Kapsam bağımsız değişkeniniz, OpenID'ye özgü bu kapsamlara ek olarak başka kapsam değerleri de içerebilir. Tüm kapsam değerleri boşlukla ayrılmalıdır. Örneğin, bir kullanıcının Google Drive'ına dosya başına erişim istiyorsanız kapsam parametreniz Kullanılabilir kapsamlar hakkında bilgi edinmek için Google API'leri için OAuth 2.0 Kapsamları bölümüne veya kullanmak istediğiniz Google API'si ile ilgili dokümanlara bakın. |
state |
(İsteğe bağlıdır, ancak kesinlikle önerilir) | Protokolde döngüye alınan opak bir dize. Diğer bir deyişle, Temel akışta URI parametresi olarak ve Örtük akışta URI
|
access_type |
(İsteğe bağlı) | offline ve online değerlerine izin verilir. Etki Çevrimdışı Erişim bölümünde açıklanmıştır. Bir erişim jetonu isteniyorsa istemci, offline değeri belirtilmediği sürece yenileme jetonu almaz. |
display |
(İsteğe bağlı) | Yetkilendirme sunucusunun kimlik doğrulama ve izin kullanıcı arayüzü sayfalarını nasıl görüntülediğini belirten bir ASCII dize değeri. Aşağıdaki değerler, Google sunucuları tarafından belirtilir ve kabul edilir ancak bu değerlerin davranışı üzerinde herhangi bir etkisi yoktur: page , popup , touch ve wap . |
hd |
(İsteğe bağlı) | Google Cloud kuruluşlarına ait hesapların giriş işlemini kolaylaştırın. Google Cloud kuruluş alanını (örneğin, mycollege.edu) dahil ederek hesap seçimi kullanıcı arayüzünün bu alandaki hesaplar için optimize edilmesi gerektiğini belirtebilirsiniz. Tek bir Google Cloud kuruluş alanı yerine genellikle Google Cloud kurumsal hesapları için optimizasyon yapmak istiyorsanız yıldız işareti ( İstemci tarafı istekleri değiştirilebilir. Bu nedenle, uygulamanıza kimlerin erişebileceğini kontrol etmek için bu kullanıcı arayüzü optimizasyonuna güvenmeyin. Döndürülen kimlik jetonunun beklediğinizle (ör.mycolledge.edu) eşleşen bir |
include_granted_scopes |
(İsteğe bağlı) | Bu parametre true değeriyle sağlanırsa ve yetkilendirme isteği verilirse yetkilendirme, diğer kapsamlar için bu kullanıcı/uygulama kombinasyonuna verilen önceki yetkilendirmeleri içerir. Artımlı yetkilendirme bölümüne bakın.
Yüklü Uygulama akışıyla artımlı yetkilendirme yapamayacağınızı unutmayın. |
login_hint |
(İsteğe bağlı) | Uygulamanız hangi kullanıcının kimliğini doğrulamaya çalıştığını bilirse bu parametreyi kimlik doğrulama sunucusuna ipucu olarak sağlayabilir. Bu ipucu iletildiğinde hesap seçici devre dışı bırakılır ve oturum açma formundaki e-posta kutusu önceden doldurulur ya da uygun oturum seçilir (kullanıcı çoklu oturum açma özelliğini kullanıyorsa) ve böylece uygulamanız yanlış kullanıcı hesabıyla giriş yaptığında ortaya çıkabilecek sorunlardan kaçınabilirsiniz.
Değer, bir e-posta adresi veya kullanıcının Google kimliğine denk olan sub dizesi olabilir. |
prompt |
(İsteğe bağlı) | Yetkilendirme sunucusunun kullanıcıdan yeniden kimlik doğrulama ve izin isteyip istemeyeceğini belirten, boşlukla sınırlandırılmış bir dize değerleri listesidir. Olası değerler şunlardır:
Değer belirtilmemişse ve kullanıcı daha önce erişim yetkisi vermediyse kullanıcıya bir izin ekranı gösterilir. |
Kimlik jetonunu doğrulama
Doğrudan Google'dan geldiklerini bilmiyorsanız sunucunuzdaki tüm kimlik jetonlarını doğrulamanız gerekir. Örneğin, sunucunuz istemci uygulamalarınızdan aldığı tüm kimlik jetonlarının orijinal olduğunu doğrulamalıdır.
Sunucunuza kimlik jetonları gönderebileceğiniz yaygın durumlar şunlardır:
- Kimliği doğrulanması gereken isteklerle birlikte kimlik jetonları gönderme. Kimlik jetonları, istekte bulunan kullanıcıyı ve bu kimlik jetonunun hangi istemci için verildiğini belirtir.
Kimlik jetonları hassastır ve müdahale edilmesi durumunda kötüye kullanılabilir. Bu jetonları yalnızca HTTPS üzerinden ve yalnızca POST verileri aracılığıyla veya istek başlıkları içinde ileterek güvenli bir şekilde işlendiğinden emin olmanız gerekir. Sunucunuzda kimlik jetonları depoluyorsanız bunları da güvenli bir şekilde saklamanız gerekir.
Kimlik jetonlarını kullanışlı hale getiren şeylerden biri de bunları uygulamanızın farklı bileşenleri arasında iletebilmenizdir. Bu bileşenler, kimlik jetonunu, uygulamanın ve kullanıcının kimliğini doğrulayan hafif bir kimlik doğrulama mekanizması olarak kullanabilir. Ancak kimlik jetonundaki bilgileri kullanabilmeniz veya kullanıcının kimliğini doğruladığına dair bir onay olarak bu bilgileri kullanabilmeniz için önce bunu doğrulamanız gerekir.
Kimlik jetonunun doğrulanması birkaç adım gerektirir:
- Kimlik jetonunun, kartı veren kuruluş tarafından düzgün şekilde imzalandığını doğrulayın. Google tarafından verilen jetonlar, Discovery dokümanının
jwks_uri
meta veri değerinde belirtilen URI'de bulunan sertifikalardan biri kullanılarak imzalanır. - Kimlik jetonundaki
iss
talebi 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ğine eşit olduğunu doğrulayın. - Kimlik jetonunun geçerlilik süresinin (
exp
hak talebi) sona ermediğini doğrulayın. - İstekte bir hd parametresi değeri belirttiyseniz kimlik jetonunun, Google Cloud kuruluşuyla ilişkili kabul edilen bir alan adıyla eşleşen bir
hd
hak talebine sahip olduğunu doğrulayın.
2. ila 5. adımlar yalnızca oldukça basit olan dize ve tarih karşılaştırmalarını içerir. Bu nedenle, burada ayrıntılarına girmeyeceğiz.
İlk adım daha karmaşıktır ve kriptografik imza denetimini içerir. Hata ayıklama amacıyla, sunucunuzda veya cihazınızda uygulanan yerel işlemlerle karşılaştırmak için Google'ın tokeninfo
uç noktasını kullanabilirsiniz. Kimlik jetonunuzun değerinin XYZ123
olduğunu varsayalım. Daha sonra, https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123
URI'sının referansını kaldırırsınız. Jeton imzası geçerliyse yanıt, kodu çözülmüş JSON nesnesi formundaki JWT yükü olur.
tokeninfo
uç noktası, hata ayıklama için kullanışlıdır ancak üretim amacıyla Google'ın ortak anahtarlarını anahtar uç noktasından alın ve doğrulamayı yerel olarak gerçekleştirin. Anahtar URI'sını jwks_uri
meta veri değerini kullanarak Keşif belgesinden almanız gerekir. Hata ayıklama uç noktasına yapılan istekler kısıtlanabilir veya başka şekilde aralıklı hatalara maruz kalabilir.
Google, genel anahtarlarını çok nadir değiştirdiğinden, bunları HTTP yanıtının önbellek yönergelerini kullanarak önbelleğe alabilirsiniz ve çoğu durumda yerel doğrulama işlemini, tokeninfo
uç noktasını kullanmaya kıyasla çok daha verimli bir şekilde yapabilirsiniz. Bu doğrulama, sertifikaların alınmasını ve ayrıştırılmasını ve imzayı kontrol etmek için uygun şifreleme çağrılarının yapılmasını gerektirir. Neyse ki bunu yapabilmek için çok çeşitli dillerde, hataları ayıklanmış kitaplıklar mevcuttur (jwt.io'ya bakın).
Kullanıcı profili bilgilerini alma
Kullanıcı hakkında ek profil bilgileri edinmek için, erişim jetonunu (uygulamanızın kimlik doğrulama akışı sırasında alır) ve OpenID Connect standardını kullanabilirsiniz:
OpenID ile uyumlu olmak için kimlik doğrulama isteğinize
openid profile
kapsam değerlerini eklemeniz gerekir.Kullanıcının e-posta adresinin dahil edilmesini istiyorsanız
email
değerinde ek bir kapsam değeri belirtebilirsiniz. Hemprofile
hem deemail
belirtmek için kimlik doğrulama isteği URI'nıza aşağıdaki parametreyi ekleyebilirsiniz:scope=openid%20profile%20email
- Erişim jetonunuzu yetkilendirme başlığına ekleyin ve kullanıcı bilgileri uç noktasına HTTPS
GET
isteği gönderin. Bu isteği,userinfo_endpoint
meta veri değerini kullanarak Discovery belgesinden almanız gerekir. Kullanıcı bilgileri yanıtı,OpenID Connect Standard Claims
bölümünde açıklandığı gibi kullanıcı hakkında bilgiler ve Keşif dokümanınınclaims_supported
meta veri değerini içerir. Kullanıcılar veya kuruluşları belirli alanları sağlamayı ya da alıkoymayı tercih edebilir. Bu nedenle, yetkilendirdiğiniz erişim kapsamlarıyla ilgili her alanla ilgili bilgileri alamayabilirsiniz.
Keşif belgesi
OpenID Connect protokolü, kullanıcıların kimliğini doğrulamak ve jetonlar, kullanıcı bilgileri ve ortak anahtarlar dahil olmak üzere kaynak istemek için birden fazla uç noktanın kullanılmasını gerektirir.
OpenID Connect, uygulamaları basitleştirmek ve esnekliği artırmak için "Discovery dokümanı"nın kullanılmasına izin verir. Bu belge, iyi bilinen bir konumda bulunan ve OpenID Connect sağlayıcısının yapılandırması hakkında yetkilendirme, jeton, iptal, kullanıcı bilgileri ve ortak anahtar uç noktalarının URI'leri dahil olmak üzere ayrıntılar sağlayan anahtar/değer çiftlerini içeren bir JSON belgesidir. Google'ın OpenID Connect hizmetinin Keşif dokümanı şuradan alınabilir:
https://accounts.google.com/.well-known/openid-configuration
Google'ın OpenID Connect hizmetlerini kullanmak için Keşif belgesi URI'sını (https://accounts.google.com/.well-known/openid-configuration
) uygulamanıza sabit olarak kodlamanız gerekir.
Uygulamanız belgeyi getirir, yanıta önbelleğe alma kurallarını uygular, ardından gerektiğinde uç nokta URI'larını buradan alır. Örneğin, bir kullanıcının kimliğini doğrulamak için kodunuz, Google'a gönderilen kimlik doğrulama istekleri için temel URI olarak authorization_endpoint
meta veri değerini (aşağıdaki örnekte https://accounts.google.com/o/oauth2/v2/auth
) alır.
Böyle bir dokümanın örneğini burada bulabilirsiniz. Alan adları, OpenID Connect Discovery 1.0'da belirtilenlerdir (anlamları için bu dokümana bakın). Değerler yalnızca örnek olarak verilmiştir ve gerçek Google Keşif dokümanının yakın tarihli bir sürümünden kopyalanmalarına rağmen değişebilir:
{ "issuer": "https://accounts.google.com", "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth", "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code", "token_endpoint": "https://oauth2.googleapis.com/token", "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo", "revocation_endpoint": "https://oauth2.googleapis.com/revoke", "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs", "response_types_supported": [ "code", "token", "id_token", "code token", "code id_token", "token id_token", "code token id_token", "none" ], "subject_types_supported": [ "public" ], "id_token_signing_alg_values_supported": [ "RS256" ], "scopes_supported": [ "openid", "email", "profile" ], "token_endpoint_auth_methods_supported": [ "client_secret_post", "client_secret_basic" ], "claims_supported": [ "aud", "email", "email_verified", "exp", "family_name", "given_name", "iat", "iss", "locale", "name", "picture", "sub" ], "code_challenge_methods_supported": [ "plain", "S256" ] }
Keşif belgesindeki değerleri önbelleğe alarak bir HTTP gidiş dönüşünü önleyebilirsiniz. Standart HTTP önbelleğe alma üst bilgileri kullanılır ve buna uyulmalıdır.
İstemci kitaplıkları
Aşağıdaki istemci kitaplıkları, popüler çerçevelerle entegrasyon sağlayarak OAuth 2.0'ın uygulanmasını kolaylaştırır:
- 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 Denetleyicileri 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ç).