Google'ın OAuth 2.0 API'leri hem kimlik doğrulama hem de yetkilendirme için kullanılabilir. Bu belgede, 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 İçin OAuth 2.0'ı Kullanma bölümündeki belgeler bu hizmet için de geçerlidir. Bu protokolü etkileşimli olarak keşfetmek istiyorsanız Google OAuth 2.0 Playground'u kullanmanızı öneririz. Stack Overflow'da yardım almak için sorularınızı "google-oauth" etiketiyle işaretleyin.
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 Cloud Console'da 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üğü markalama bilgilerini özelleştirmeniz gerekir. Ayrıca Cloud Console'u kullanarak hizmet hesabı oluşturabilir, faturalandırmayı etkinleştirebilir, filtreleme ayarlayabilir ve başka görevler de yapabilirsiniz. Daha fazla bilgi için Google Cloud Console Yardım Merkezi'ne bakın.
OAuth 2.0 kimlik bilgilerini edinme
Kullanıcıların kimliğini doğrulamak ve Google'ın API'lerine erişmek için istemci kimliği ve istemci gizli anahtarı gibi OAuth 2.0 kimlik bilgilerine ihtiyacınız vardır.
Belirli bir OAuth 2.0 kimlik bilgisinin istemci kimliğini ve istemci gizli anahtarını görüntülemek için şu metni tıklayın: Kimlik bilgisi seçin. Açılan pencerede projenizi ve istediğiniz kimlik bilgisini seçip Görüntüle'yi tıklayın.
Alternatif olarak, Cloud Console'daki İstemciler sayfasından istemci kimliğinizi ve istemci gizli anahtarınızı görüntüleyin:
- Müşteriler sayfasına gidin.
- Müşterinizin adını veya düzenle (create) simgesini tıklayın. İstemci kimliğiniz ve gizli anahtarınız sayfanın üst kısmında yer alır.
Yönlendirme URI'si ayarlama
Cloud Console'da 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 bilgisi için yönlendirme URI'lerini oluşturmak, görüntülemek veya düzenlemek üzere aşağıdakileri yapın:
- Müşteriler sayfasına gidin.
- Müşteriyi tıklayın.
- Yönlendirme URI'lerini görüntüleyin veya düzenleyin.
İstemciler sayfasında listelenmiş bir istemci yoksa projenizde OAuth kimlik bilgileri yoktur. Kimlik bilgisi oluşturmak için İstemci oluştur'u tıklayın.
Kullanıcı rızası ekranını özelleştirme
Kullanıcılarınız için OAuth 2.0 kimlik doğrulama deneyimi, kullanıcının yayınladığı bilgileri ve geçerli şartları açıklayan bir kullanıcı rızası ekranı içerir. Örneğin, kullanıcı giriş yaptığında uygulamanızın e-posta adresine ve temel hesap bilgilerine erişmesine izin vermesi istenebilir. Bu bilgilere erişim isteğinde bulunmak için uygulamanızın kimlik doğrulama isteğine dahil ettiği scope parametresini kullanırsınız. Kapsamları, diğer Google API'lerine erişim isteğinde bulunmak için de kullanabilirsiniz.
Kullanıcı rızası ekranında ürün adınız, logonuz ve ana sayfa URL'si gibi marka bilgileri de gösterilir. Markalama bilgilerini Cloud Console'da kontrol edersiniz.
Projenizin kullanıcı rızası ekranını etkinleştirmek için:
- Google Cloud Console'da Markalama sayfası'nı açın.
- İstenirse bir proje seçin veya yeni bir proje oluşturun.
- 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 bulunduğunda kullanıcının göreceği bilgiler gösterilmektedir. (Bu genel iletişim kutusu, Google OAuth 2.0 Playground kullanılarak oluşturulduğundan Cloud Console'da 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şme ile ilgili birçok uygulama ayrıntısını halletmek için kullanabileceğiniz kitaplıklar sağlar. Örnek olarak, çeşitli platformlarda kullanılabilen Google Kimlik Hizmetleri ve Google istemci kitaplıkları verilebilir.
Kitaplık kullanmamayı tercih ederseniz bu belgenin geri kalanında yer alan talimatları uygulayın. Bu talimatlarda, mevcut kitaplıkların temelini oluşturan HTTP isteği akışları açıklanmaktadır.
Kullanıcının kimliğini doğrulama
Kullanıcının kimliğini doğrulamak için kimlik jetonu alınır ve doğrulanır. Kimlik jetonları, internette kimlik onaylarını paylaşmak için tasarlanmış OpenID Connect'in standart bir özelliğidir.
Kullanıcının kimliğini doğrulamak ve kimlik jetonu almak için en çok tercih edilen yaklaşımlara "sunucu" akışı ve "dolaylı" akış adı verilir. Sunucu akışı, bir uygulamanın arka uç sunucusunun tarayıcı veya mobil cihaz kullanan kişinin kimliğini doğrulamasını sağlar. Dolaylı akış, istemci taraflı bir uygulamanın (genellikle tarayıcıda çalışan bir JavaScript uygulaması) arka uç sunucusunu kullanmak yerine doğrudan API'lere erişmesi gerektiğinde kullanılır.
Bu belgede, kullanıcının kimliğini doğrulamak için sunucu akışının nasıl gerçekleştirileceği açıklanmaktadır. Dolaylı akış, istemci tarafında jetonların işlenmesi ve kullanılmasındaki güvenlik riskleri nedeniyle çok daha karmaşıktır. Dolaylı akış uygulamanız gerekiyorsa Google Kimlik Hizmetleri'ni kullanmanızı önemle tavsiye ederiz.
Sunucu akışı
Bu protokollerin kullanılabilmesi ve kullanıcılarınızın kimliğinin doğrulanabilmesi için uygulamanızı Cloud Console'da ayarladığınızdan emin olun. Bir kullanıcı Google ile oturum açmaya çalıştığında şunları yapmanız gerekir:
- Sahteciliğe karşı durum jetonu oluşturma
- Google'a kimlik doğrulama isteği gönderme
- Sahteciliğe karşı koruma durum jetonunu onaylama
- Erişim jetonu ve kimlik jetonu için
codedeğişimi - Kimlik jetonundan kullanıcı bilgilerini alma
- Kullanıcının kimliğini doğrulama
1. Sahteciliğe karşı durum jetonu oluşturma
İstek sahteciliği 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ında durumu koruyan benzersiz bir oturum jetonu oluşturmaktır. Daha sonra, kullanıcının isteği yaptığını ve kötü niyetli bir saldırgan olmadığını doğrulamak için bu benzersiz oturum jetonunu Google OAuth Login hizmeti tarafından döndürülen kimlik doğrulama yanıtıyla eşleştirirsiniz. Bu jetonlara genellikle siteler arası istek sahteciliği (CSRF) jetonları denir.
Durum jetonu için iyi bir seçenek, yüksek kaliteli bir rastgele sayı üreteci kullanılarak oluşturulmuş yaklaşık 30 karakterlik bir dizedir. Diğeri ise oturum durumu değişkenlerinizin bir kısmının arka uçta gizli tutulan bir anahtarla imzalanmasıyla oluşturulan karma değerdir.
Aşağıdaki kodda benzersiz oturum jetonlarının nasıl oluşturulacağı gösterilmektedir.
PHP
Bu örneği kullanmak için PHP için Google API'leri istemci kitaplığını indirmeniz gerekir.
// Create a state token to prevent request forgery. // Store it in the session for later validation. $state = bin2hex(random_bytes(128/8)); $app['session']->set('state', $state); // Set the client ID, token state, and application name in the HTML while // serving it. return $app['twig']->render('index.html', array( 'CLIENT_ID' => CLIENT_ID, 'STATE' => $state, 'APPLICATION_NAME' => APPLICATION_NAME ));
Java
Bu örneği kullanmak için Java için Google API'leri istemci kitaplığı'nı indirmeniz gerekir.
// Create a state token to prevent request forgery. // Store it in the session for later validation. String state = new BigInteger(130, new SecureRandom()).toString(32); request.session().attribute("state", state); // Read index.html into memory, and set the client ID, // token state, and application name in the HTML before serving it. return new Scanner(new File("index.html"), "UTF-8") .useDelimiter("\\A").next() .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID) .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state) .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}", APPLICATION_NAME);
Python
Bu örneği kullanmak için Python için Google API'leri istemci kitaplığını indirmeniz gerekir.
# Create a state token to prevent request forgery. # Store it in the session for later validation. state = hashlib.sha256(os.urandom(1024)).hexdigest() session['state'] = state # Set the client ID, token state, and application name in the HTML while # serving it. response = make_response( render_template('index.html', CLIENT_ID=CLIENT_ID, STATE=state, APPLICATION_NAME=APPLICATION_NAME))
2. Google'a kimlik doğrulama isteği gönderme
Bir 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 keşif belgesinden temel URI'yi almanız gerekir. Aşağıdaki tartışmada temel URI'nin https://accounts.google.com/o/oauth2/v2/auth olduğu varsayılmaktadır.
Temel bir istek için aşağıdaki parametreleri belirtin:
client_id. Bu kimliği, Cloud Console'daki İstemciler sayfasından edinebilirsiniz.response_type. Temel yetkilendirme kodu akışı isteğinde bu değercodeolmalıdır. (Daha fazla bilgi içinresponse_type.)scope, temel bir istekteopenid emailolmalıdır. (Daha fazla bilgiyiscopeadresinde bulabilirsiniz.)redirect_uri, sunucunuzda Google'dan yanıtı alacak HTTP uç noktası olmalıdır. Değer, Cloud Console'daki Kimlik Bilgileri sayfasında yapılandırdığınız OAuth 2.0 istemcisinin yetkili yönlendirme URI'lerinden biriyle tam olarak eşleşmelidir. Bu değer yetkili bir URI ile eşleşmezse istekredirect_uri_mismatchhatasıyla başarısız olur.state, sahteciliğe karşı koruma için kullanılan benzersiz oturum jetonunun değerini ve kullanıcının uygulamanıza geri döndüğünde bağlamı kurtarmak için gereken diğer bilgileri (ör. başlangıç URL'si) içermelidir. (Daha fazla bilgiyistateadresinde bulabilirsiniz.)nonce, mevcut olduğunda tekrar oynatma korumasını etkinleştiren, uygulamanız tarafından oluşturulan rastgele bir değerdir.login_hint, kullanıcının e-posta adresi veya kullanıcının Google kimliğine eşdeğer olansubdizesi olabilir.login_hintsağlamazsanız ve kullanıcı giriş yapmışsa izin ekranında, kullanıcının e-posta adresinin uygulamanızla paylaşılması için onay isteği yer alır. (Daha fazla bilgiyilogin_hintadresinde bulabilirsiniz.)- Google Workspace veya Cloud kuruluşuyla ilişkili belirli bir alanın kullanıcıları için OpenID Connect akışını optimize etmek üzere
hdparametresini kullanın (hdadresinden daha fazla bilgi edinin).
Aşağıda, okunabilirlik için satır sonları ve 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//developers.google.com/oauthplayground& 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. Sahteciliğe karşı koruma durumu jetonunu onaylayın
Yanıt, istekte belirttiğiniz redirect_uri adresine gönderilir. Tüm yanıtlar sorgu dizesinde döndürülür:
https://developers.google.com/oauthplayground?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
RFC 6749 uyarınca istemciler, tanınmayan yanıt parametrelerini YOK SAYMALIDIR. Sunucuda,
Google'dan alınan state değerinin, 1. adımda oluşturduğunuz oturum jetonuyla eşleştiğini doğrulamanı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ığını doğrulamaya yardımcı olur.
Aşağıdaki kodda, 1. adımda oluşturduğunuz oturum jetonlarının nasıl onaylanacağı gösterilmektedir:
PHP
Bu örneği kullanmak için PHP için Google API'leri istemci kitaplığını indirmeniz gerekir.
// Ensure that there is no request forgery going on, and that the user // sending us this connect request is the user that was supposed to. if ($request->get('state') != ($app['session']->get('state'))) { return new Response('Invalid state parameter', 401); }
Java
Bu örneği kullanmak için Java için Google API'leri istemci kitaplığı'nı indirmeniz gerekir.
// Ensure that there is no request forgery going on, and that the user // sending us this connect request is the user that was supposed to. if (!request.queryParams("state").equals( request.session().attribute("state"))) { response.status(401); return GSON.toJson("Invalid state parameter."); }
Python
Bu örneği kullanmak için Python için Google API'leri istemci kitaplığını indirmeniz gerekir.
# Ensure that the request is not a forgery and that the user sending # this connect request is the expected user. if request.args.get('state', '') != session['state']: response = make_response(json.dumps('Invalid state parameter.'), 401) response.headers['Content-Type'] = 'application/json' return response
4. Erişim jetonu ve kimlik jetonu için code exchange'i
Yanıt, sunucunuzun erişim jetonu ve kimlik jetonu karşılığında kullanabileceği tek seferlik bir yetkilendirme kodu olan code parametresini içerir. Sunucunuz, HTTPS POST isteği göndererek bu değişimi yapar. POST isteği, token_endpoint meta veri değeri kullanılarak keşif belgesinden almanız gereken jeton uç noktasına gönderilir. Aşağıdaki tartışmada, uç noktanın https://oauth2.googleapis.com/token olduğu varsayılmaktadır. İstek, POST gövdesinde aşağıdaki parametreleri içermelidir:
| Alanlar | |
|---|---|
code |
İlk istekten döndürülen yetkilendirme kodu. |
client_id |
OAuth 2.0 kimlik bilgilerini edinme bölümünde açıklandığı gibi, Cloud Console İstemciler sayfasından aldığınız istemci kimliği. |
client_secret |
OAuth 2.0 kimlik bilgilerini edinme başlıklı makalede açıklandığı gibi, Cloud Console İstemciler sayfasından aldığınız istemci gizli anahtarı. |
redirect_uri |
Cloud Console'daki client_id için yetkilendirilmiş bir yönlendirme URI'si.
İstemciler sayfasında, Yönlendirme URI'si ayarlama bölümünde açıklandığı gibi. |
grant_type |
Bu alan, authorization_code değerini içermelidir.
OAuth 2.0 belirtiminde tanımlandığı gibi. |
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//developers.google.com/oauthplayground& grant_type=authorization_code
Bu isteğe verilen başarılı yanıt, bir JSON dizisinde aşağıdaki alanları içerir:
| Alanlar | |
|---|---|
access_token |
Google API'ye gönderilebilen bir jeton. |
expires_in |
Erişim jetonunun kalan kullanım ömrü (saniye cinsinden). |
id_token |
Google tarafından dijital olarak imzalanmış, kullanıcıyla ilgili kimlik bilgilerini içeren bir JWT. |
scope |
access_token tarafından verilen erişim kapsamları, boşlukla ayrılmış ve büyük/küçük harfe duyarlı dizeler listesi olarak ifade edilir. |
token_type |
Döndürülen jetonun türünü tanımlar. Bu alan şu anda her zaman Bearer değerine sahiptir.
|
refresh_token |
(isteğe bağlı)
Bu alan yalnızca kimlik doğrulama isteğinde |
5. Kimlik jetonundan kullanıcı bilgilerini alma
Kimlik jetonu, JWT (JSON Web Token) olarak bilinen, kriptografik olarak imzalanmış bir Base64 kodlu JSON nesnesidir. Normalde, kullanmadan önce kimlik jetonunu doğrulamanız çok önemlidir. Ancak, Google ile doğrudan, aracısız bir HTTPS kanalı üzerinden 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ığı, doğrulamayı base64url ile kodlanmış değerlerin kodunu çözme ve JSON'ı ayrıştırma işlemiyle birleştirdiğinden, kimlik jetonundaki taleplere erişirken jetonu doğrulamanız gerekir.
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 görebilirsiniz:
{ "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ı (talepler olarak bilinir) içerebilir:
| İddia | Sağlandı | Açıklama |
|---|---|---|
aud |
her zaman | Bu kimlik jetonunun hedef kitlesi. Uygulamanızın OAuth 2.0 istemci kimliklerinden biri olmalıdır. |
exp |
her zaman | Kimlik jetonunun kabul edilmemesi gereken son kullanma tarihi. Unix sıfır zamanı (tam saniye) olarak gösterilir. |
iat |
her zaman | Kimlik jetonunun düzenlenme zamanı. Unix epoch zamanı (tam saniye) olarak gösterilir. |
iss |
her zaman | Yanıtın Düzenleyeni'nin Düzenleyen Tanımlayıcısı. Google kimlik jetonları için her zaman https://accounts.google.com veya accounts.google.com olur. |
sub |
her zaman | Kullanıcı için tanımlayıcıdır. Tüm Google Hesapları arasında benzersizdir ve asla yeniden kullanılmaz. Bir Google Hesabı'nın farklı zamanlarda birden fazla e-posta adresi olabilir ancak sub değeri hiçbir zaman değiştirilmez. Uygulamanızda kullanıcı için benzersiz tanımlayıcı anahtar olarak sub kullanın. Maksimum uzunluk 255 büyük/küçük harfe duyarlı ASCII karakteridir. |
amr |
Bir Google Hesabı'nda oturum açmak için kullanılan kimlik doğrulama yöntemlerini tanımlayan bir dize JSON dizisi. Varsa şu olası değerlerden birini veya daha fazlasını içerir:
[IANA.AMR]
değerleri:
amr talebi kimlik doğrulama isteğine dahil edildiğinde ve ayarlarda etkinleştirildiğinde gösterilir.
|
|
auth_time |
Kullanıcı kimlik doğrulamasının gerçekleştiği zaman. Unix sıfır zamanından (1 Ocak 1970, 00:00:00 UTC) bu yana geçen saniye sayısını temsil eden bir JSON sayısıdır. auth_time talebi kimlik doğrulama isteğine dahil edildiğinde ve ayarlarda etkinleştirildiğinde sağlanır.
|
|
at_hash |
Erişim jetonu karması. Erişim jetonunun kimlik jetonuna bağlı olduğunu doğrulama Kimlik jetonu, sunucu akışında access_token değeriyle verildiyse bu talep her zaman dahil edilir. Bu talep, siteler arası istek sahteciliği saldırılarına karşı koruma sağlamak için alternatif bir mekanizma olarak kullanılabilir ancak 1. Adım ve 3. Adım'ı uyguladığınızda erişim jetonunun doğrulanması gerekmez. |
|
azp |
Yetkili sunum yapan kişinin client_id. Bu talep yalnızca kimlik jetonunu isteyen taraf, kimlik jetonunun hedef kitlesiyle aynı olmadığında gereklidir. Bu durum, bir web uygulaması ve Android uygulamasının farklı bir OAuth 2.0 client_id'ye sahip olduğu ancak aynı Google API'leri projesini paylaştığı hibrit uygulamalar için Google'da geçerli olabilir. |
|
email |
Kullanıcının e-posta adresi. Yalnızca isteğinize email kapsamını dahil ettiyseniz sağlanır. Bu talebin değeri bu hesaba özgü olmayabilir ve zaman içinde değişebilir. Bu nedenle, kullanıcı kaydınıza bağlantı vermek için bu değeri birincil tanımlayıcı olarak kullanmamalısınız. Google Workspace veya Cloud kuruluşlarının kullanıcılarını tanımlamak için email talebinin alanına da güvenemezsiniz. Bunun yerine hd talebini kullanın.
|
|
email_verified |
Kullanıcının e-posta adresi doğrulandıysa doğru, aksi halde yanlış değerini alır. | |
family_name |
Kullanıcının soyadı. name talebi olduğunda sağlanabilir. |
|
given_name |
Kullanıcının verilen adı veya adları. name talebi olduğunda sağlanabilir. |
|
hd |
Kullanıcının Google Workspace veya Cloud kuruluşuyla ilişkili alan. Yalnızca kullanıcı bir Google Cloud kuruluşuna aitse sağlanır. Bir kaynağa erişimi yalnızca belirli alan adlarının üyeleriyle kısıtlarken bu hak talebini kontrol etmeniz gerekir. Bu talebin olmaması, hesabın Google tarafından barındırılan bir alana ait olmadığını gösterir. | |
locale |
Kullanıcının yerel ayarı, BCP 47 dil etiketiyle gösterilir.
name talebi olduğunda sağlanabilir. |
|
name |
Kullanıcının tam adı, görüntülenebilir biçimde. Aşağıdaki durumlarda sağlanabilir:
|
|
nonce |
Kimlik doğrulama isteğinde uygulamanız tarafından sağlanan nonce değeri.
Bu değeri yalnızca bir kez sunarak tekrar oynama saldırılarına karşı koruma sağlamanız gerekir. |
|
picture |
Kullanıcının profil resminin URL'si. Şu durumlarda sağlanabilir:
|
|
profile |
Kullanıcının profil sayfasının URL'si. Şu durumlarda sağlanabilir:
|
6. Kullanıcının kimliğini doğrulama
Kimlik jetonundan kullanıcı bilgilerini aldıktan sonra uygulamanızın kullanıcı veritabanını sorgulamanız gerekir. Kullanıcı veritabanınızda zaten varsa Google API yanıtı tüm giriş koşullarını karşılıyorsa bu kullanıcı için bir uygulama oturumu başlatmanız gerekir.
Kullanıcı, kullanıcı veritabanınızda yoksa kullanıcıyı yeni kullanıcı kayıt akışınıza yönlendirmeniz gerekir. Google'dan aldığınız bilgilere göre kullanıcıyı otomatik olarak kaydedebilir veya en azından kayıt formunuzda gerekli olan birçok alanı önceden doldurabilirsiniz. Kimlik jetonundaki bilgilere ek olarak, kullanıcı profili uç noktalarımızda ek kullanıcı profili bilgileri de edinebilirsiniz.
İ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 gelişmiş gereksinimleri olan geliştiriciler için hazırlanmıştır.
Diğer Google API'lerine erişim
Kimlik doğrulama için OAuth 2.0 kullanmanın avantajlarından biri, uygulamanızın kullanıcıyı kimlik doğruladığınız sırada kullanıcının adına diğer Google API'lerini (ör. YouTube, Google Drive, Takvim veya Kişiler) 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ı, kullanıcı rızası ekranında uygun şekilde yönlendirilir. Google'dan geri aldığınız erişim jetonu, uygulamanızın istediğiniz ve verilen erişim kapsamlarıyla ilgili tüm API'lere erişmesine olanak tanır.
Yenileme jetonları
API erişimi isteğinizde, code değişim sırasında yenileme jetonunun döndürülmesini isteyebilirsiniz. Yenileme jetonu, kullanıcı uygulamanızda bulunmadığı sürece uygulamanıza Google API'lerine sürekli erişim imkanı sağlar. Yenileme jetonu istemek için kimlik doğrulama isteğinize access_type parametresini offline olarak ayarlayın.
Dikkat etmeniz gereken noktalar:
- Yenileme jetonunu güvenli ve kalıcı bir şekilde sakladığınızdan emin olun. Çünkü kod değişimi akışını ilk kez gerçekleştirdiğinizde yalnızca bir yenileme jetonu alabilirsiniz.
- Yenileme jetonlarının sayısı sınırlıdır: Bir sınır istemci/kullanıcı kombinasyonu başına, diğeri ise tüm istemcilerde kullanıcı başına uygulanır. Uygulamanız çok fazla yenileme jetonu isterse bu sınırlara takılabilir. Bu durumda eski yenileme jetonları çalışmayı durdurur.
Daha fazla bilgi için Erişim jetonunu yenileme (çevrimdışı erişim) başlıklı makaleyi inceleyin.
Yeniden izin isteme
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 her erişim kapsamı yetkilendirmesi istediğinde kullanıcı rızası ekranı gösterilir. Bu nedenle, prompt=consent yalnızca gerektiğinde ekleyin.
prompt parametresi hakkında daha fazla bilgi için Kimlik doğrulama URI parametreleri tablosundaki prompt bölümüne bakın.
Kimlik doğrulama URI parametreleri
Aşağıdaki tabloda, Google'ın OAuth 2.0 kimlik doğrulama API'si tarafından kabul edilen parametrelerin daha eksiksiz açıklamaları verilmiştir.
| Parametre | Zorunlu | Açıklama | ||||||
|---|---|---|---|---|---|---|---|---|
client_id |
(Gerekli) | OAuth 2.0 kimlik bilgilerini edinme bölümünde açıklandığı gibi, Cloud Console İstemciler sayfasından aldığınız istemci kimliği dizesi. | ||||||
nonce |
(Gerekli) | Uygulamanız tarafından oluşturulan ve yeniden oynatma korumasını etkinleştiren rastgele bir değer. | ||||||
response_type |
(Gerekli) | Değer code ise jetonları almak için jeton uç noktasına POST gönderilmesini gerektiren bir temel yetkilendirme kodu akışı başlatır. Değer token id_token veya id_token token ise jetonları URI #fragment tanımlayıcısından almak için yönlendirme URI'sinde JavaScript kullanılmasını gerektiren bir örtülü akış başlatır. |
||||||
redirect_uri |
(Gerekli) | Yanıtın nereye gönderileceğini belirler. Bu parametrenin değeri, Cloud Console Clients sayfasında 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 |
(Gerekli) | Kapsam parametresi
Kapsam bağımsız değişkeniniz, bu OpenID'ye özgü kapsamların yanı sıra diğer kapsam değerlerini de içerebilir. Tüm kapsam değerleri boşlukla ayrılmalıdır. Örneğin, bir kullanıcının Google Drive'ına dosya bazında erişmek istiyorsanız kapsam parametreniz Kullanılabilir kapsamlar hakkında bilgi için Google API'leri için OAuth 2.0 Kapsamları başlıklı makaleye veya kullanmak istediğiniz Google API'sinin dokümanlarına bakın. |
||||||
state |
(İsteğe bağlıdır ancak kesinlikle önerilir) | Protokolde gidiş-dönüş yapılan opak bir dize. Yani, Temel akışta URI parametresi olarak, dolaylı akışta ise URI
|
||||||
access_type |
(İsteğe bağlı) | İzin verilen değerler offline ve online'dir. Bu durum, Çevrimdışı Erişim bölümünde açıklanmıştır. Erişim jetonu isteniyorsa offline değeri belirtilmediği sürece istemciye yenileme jetonu verilmez. |
||||||
claims |
(İsteğe bağlı) |
claims parametresi, userinfo uç noktasına veya kimlik doğrulama isteği kimlik jetonu yanıt türlerine dahil edilecek bir veya daha fazla isteğe bağlı alanı belirtmek için kullanılır. Değer, yanıt türünü ve istenen talepleri içeren bir JSON nesnesidir. Aşağıdaki hak talebi istekleri Google sunucuları tarafından kabul edilir:
|
||||||
display |
(İsteğe bağlı) | Yetkilendirme sunucusunun kimlik doğrulama ve izin kullanıcı arayüzü sayfalarını nasıl göstereceğini belirtmek için kullanılan bir ASCII dize değeri. Aşağıdaki değerler belirtilir ve Google sunucuları tarafından kabul edilir ancak protokol akışı davranışı üzerinde herhangi bir etkisi yoktur: page, popup, touch ve wap. |
||||||
hd |
(İsteğe bağlı) | Google Cloud kuruluşuna ait hesaplar için giriş sürecini kolaylaştırın. Google Cloud kuruluş alanını (ör. mycollege.edu) ekleyerek hesap seçimi kullanıcı arayüzünün bu alandaki hesaplar için optimize edilmesi gerektiğini belirtebilirsiniz. Yalnızca tek bir Google Cloud kuruluş alanı yerine genellikle Google Cloud kuruluş hesapları için optimizasyon yapmak istiyorsanız yıldız işareti ( İ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. Döndürülen 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 verilirse yetkilendirme, bu kullanıcı/uygulama kombinasyonuna diğer kapsamlar için verilen önceki yetkilendirmeleri de içerir. Artımlı yetkilendirme bölümüne bakın.
Yüklü uygulama akışıyla kademeli yetkilendirme yapamayacağınızı unutmayın. |
||||||
login_hint |
(İsteğe bağlı) | Uygulamanız, kimliği doğrulanmaya çalışılan kullanıcının kim olduğunu biliyorsa bu parametreyi kimlik doğrulama sunucusuna ipucu olarak sağlayabilir. Bu ipucunun iletilmesi, Hesap Seçiciyi devre dışı bırakır ve oturum açma formundaki e-posta kutusunu önceden doldurur ya da doğru oturumu seçer (kullanıcı çoklu oturum açma özelliğini kullanıyorsa). Bu sayede, uygulamanızın yanlış kullanıcı hesabında oturum açması durumunda ortaya çıkabilecek sorunları önleyebilirsiniz.
Değer, e-posta adresi veya kullanıcının Google kimliğine eşdeğer olan sub dizesi olabilir. |
||||||
prompt |
(İsteğe bağlı) | Yetkilendirme sunucusunun kullanıcıdan yeniden kimlik doğrulama ve izin isteyip istemediğini belirten, boşlukla ayrılmış dize değerleri listesi. Olası değerler şunlardır:
Değer belirtilmemişse ve kullanıcı daha önce erişimi yetkilendirmemişse kullanıcıya kullanıcı rızası ekranı gösterilir. |
||||||
hl |
(İsteğe bağlı) | Oturum açma, hesap seçici ve izin ekranlarının görüntüleme dilini belirtmek için kullanılan BCP 47 dil etiketi. Bu parametre sağlanmazsa dil, varsayılan olarak kullanıcının Google Hesabı veya tarayıcı ayarlarına göre belirlenir. Örneğin, kullanıcı arayüzünün İngiliz İngilizcesi olarak istenmesi için parametreyi en-GB olarak ayarlayın.
|
||||||
Kimlik jetonunu doğrulama
Doğrudan Google'dan geldiğini bilmediğiniz sürece sunucunuzdaki tüm kimlik jetonlarını doğrulamanız gerekir. Örneğin, sunucunuz, istemci uygulamalarınızdan aldığı tüm kimlik jetonlarının gerçekliğini doğrulamalıdır.
Aşağıda, kimlik jetonlarını sunucunuza gönderebileceğiniz yaygın durumlar verilmiştir:
- Kimliği doğrulanması gereken isteklerle kimlik jetonları gönderme. Kimlik jetonları, isteği yapan belirli kullanıcıyı ve bu kimlik jetonunun hangi istemci için verildiğini gösterir.
Kimlik jetonları hassastır ve ele geçirilirse kötüye kullanılabilir. Bu jetonların yalnızca HTTPS üzerinden ve yalnızca POST verileri kullanılarak ya da istek başlıkları içinde iletilerek güvenli bir şekilde işlenmesini sağlamalısınız. Kimlik jetonlarını sunucunuzda saklıyorsanız bunları güvenli bir şekilde saklamanız da gerekir.
Kimlik jetonlarını kullanışlı kılan özelliklerden biri, bunları uygulamanızın farklı bileşenlerine iletebilmenizdir. Bu bileşenler, uygulamayı ve kullanıcıyı doğrulayan basit bir kimlik doğrulama mekanizması olarak kimlik jetonunu kullanabilir. Ancak kimlik jetonundaki bilgileri kullanabilmeniz veya kullanıcının kimliğinin doğrulandığını belirten bir onay olarak jetona güvenebilmeniz için jetonu doğrulamanız gerekir.
Kimlik jetonunun doğrulanması için birkaç adım gerekir:
- Kimlik jetonunun, veren tarafından düzgün şekilde imzalandığını doğrulayın. Google tarafından verilen jetonlar, Discovery belgesinin
jwks_urimeta veri değerinde belirtilen URI'de bulunan sertifikalardan biri kullanılarak imzalanır. - Kimlik jetonundaki
isstalebinin değerininhttps://accounts.google.comveyaaccounts.google.com'ye eşit olduğunu doğrulayın. - Kimlik jetonundaki
audtalebinin değerinin uygulamanızın istemci kimliğine eşit olduğunu doğrulayın. - Kimlik jetonunun süre sonunun (
exptalebi) geçmediğini doğrulayın. - İstek içinde bir hd parametresi değeri belirttiyseniz kimlik jetonunun, bir Google Cloud kuruluşuyla ilişkili kabul edilen bir alanla eşleşen bir
hdtalebi içerdiğini doğrulayın.
2-5. adımlar yalnızca oldukça basit olan dize ve tarih karşılaştırmalarını içerdiğinden burada ayrıntılı olarak açıklanmayacaktır.
İlk adım daha karmaşıktır ve kriptografik imza kontrolünü içerir. Hata ayıklama amacıyla, sunucunuzda veya cihazınızda uygulanan yerel işlemeyle karşılaştırmak için Google'ın tokeninfo uç noktasını kullanabilirsiniz. Kimlik jetonunuzun değerinin
XYZ123 olduğunu varsayalım. Ardından URI'nin referansını kaldırırsınız
https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. Jeton imzası geçerliyse yanıt, kod çözülmüş JSON nesnesi biçimindeki JWT yükü olur.
tokeninfo uç noktası hata ayıklama için yararlıdır ancak üretim amacıyla Google'ın ortak anahtarlarını keys uç noktasından alıp doğrulamayı yerel olarak gerçekleştirin. Anahtarların URI'sini jwks_uri meta veri değerini kullanarak keşif belgesinden almanız gerekir. Hata ayıklama uç noktasına yapılan istekler sınırlandırılabilir veya başka bir şekilde aralıklı hatalara tabi olabilir.
Google, ortak anahtarlarını yalnızca nadiren değiştirdiğinden bunları HTTP yanıtının önbellek yönergelerini kullanarak önbelleğe alabilir ve çoğu durumda yerel doğrulamayı tokeninfo uç noktasını kullanmaktan çok daha verimli bir şekilde gerçekleştirebilirsiniz. Bu doğrulama, sertifikaların alınmasını ve ayrıştırılmasını, ayrıca imzayı kontrol etmek için uygun şifreleme çağrılarının yapılmasını gerektirir. Neyse ki bu işlemi gerçekleştirmek için çeşitli dillerde iyi hata ayıklaması yapılmış kitaplıklar mevcuttur (bkz. jwt.io).
Kullanıcı profili bilgilerini edinme
Kullanıcı hakkında ek profil bilgileri edinmek için erişim jetonunu (uygulamanızın kimlik doğrulama akışı sırasında aldığı) ve OpenID Connect standardını kullanabilirsiniz:
OpenID ile uyumlu olmak için
openid profilekapsam değerlerini kimlik doğrulama isteğinize eklemeniz gerekir.Kullanıcının e-posta adresinin dahil edilmesini istiyorsanız
emailek kapsam değerini belirtebilirsiniz. Hemprofilehem deemaildeğerini 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
GETmeta veri değerini kullanarak keşif belgesinden almanız gereken userinfo uç noktasına bir HTTPS isteği gönderin.userinfo_endpointUserinfo yanıtı,OpenID Connect Standard Claimsbölümünde açıklandığı gibi kullanıcıyla ilgili bilgileri ve keşif belgesininclaims_supportedmeta veri değerini içerir. Kullanıcılar veya kuruluşları belirli alanları sağlamayı ya da sağlamamayı tercih edebilir. Bu nedenle, yetkili erişim kapsamlarınızdaki her alan için bilgi alamayabilirsiniz.
Keşif belgesi
OpenID Connect protokolü, kullanıcıların kimliğini doğrulamak ve jetonlar, kullanıcı bilgileri ve genel 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 "Keşif belgesi" kullanımına izin verir. Keşif belgesi, iyi bilinen bir konumda bulunan ve OpenID Connect sağlayıcısının yapılandırmasıyla ilgili ayrıntıları sağlayan anahtar/değer çiftlerini içeren bir JSON belgesidir. Bu ayrıntılar arasında yetkilendirme, jeton, iptal, kullanıcı bilgisi ve genel anahtarlar uç noktalarının URI'leri yer alır. Google'ın OpenID Connect hizmetinin keşif belgesi şu adresten alınabilir:
https://accounts.google.com/.well-known/openid-configuration
Google'ın OpenID Connect hizmetlerini kullanmak için Discovery-document URI'yi (https://accounts.google.com/.well-known/openid-configuration) uygulamanıza sabit kodlamanız gerekir.
Uygulamanız dokümanı getirir, yanıttaki önbelleğe alma kurallarını uygular ve ardından gerektiğinde uç nokta URI'lerini dokümandan alır. Örneğin, bir kullanıcının kimliğini doğrulamak için kodunuz, Google'a gönderilen kimlik doğrulama isteklerinin temel URI'si olarak authorization_endpoint meta veri değerini (aşağıdaki örnekte https://accounts.google.com/o/oauth2/v2/auth) alır.
Bu tür bir belgeye örnek olarak, OpenID Connect Discovery 1.0'da belirtilen alan adları verilmiştir (anlamları için ilgili belgeye bakın). Değerler tamamen açıklayıcıdır ve gerçek Google keşif belgesinin son sürümünden kopyalanmış olsa 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" ] }
Discovery belgesindeki değerleri önbelleğe alarak HTTP gidiş dönüşünü önleyebilirsiniz. Standart HTTP önbelleğe alma üst bilgileri kullanılır ve bunlara 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 istemci kitaplığı
- Python için Google API'leri İstemci Kitaplığı
- .NET için Google API'leri istemci kitaplığı
- Ruby için Google API'leri İstemci Kitaplığı
- PHP için Google API'leri istemci kitaplığı
- Google Web Toolkit için OAuth 2.0 Kitaplığı
- Mac için Google Araç Kutusu OAuth 2.0 Denetleyicileri
OpenID Connect uyumluluğu
Google'ın OAuth 2.0 kimlik doğrulama sistemi, OpenID Connect Core spesifikasyonunun gerekli özelliklerini destekler. OpenID Connect ile çalışmak üzere tasarlanmış tüm istemciler, bu hizmetle birlikte çalışmalıdır (OpenID İstek Nesnesi hariç).