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 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üğü markalama bilgilerini özelleştirmeniz gerekir. Hizmet hesabı oluşturmak, faturalandırmayı etkinleştirmek, filtreleme ayarlamak ve diğer görevleri gerçekleştirmek için Cloud Console de kullanabilirsiniz. Daha fazla bilgi için Google Cloud Console Yardım bölümü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, istemci kimliğinizi ve istemci gizli anahtarınızıCloud Consolebölümündeki Clients page simgesinden görüntüleyebilirsiniz:
- Go to the Clients page.
- 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 bölümünde 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:
- Go to the Clients page.
- Müşteriyi tıklayın.
- Yönlendirme URI'lerini görüntüleyin veya düzenleyin.
İstemciler sayfasında listelenen bir istemci yoksa projenizde OAuth kimlik bilgileri yoktur. Oluşturmak için Müşteri oluştur'u tıklayın.
Kullanıcı izni 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 adresine ve temel hesap bilgilerine erişim izni vermesi istenebilir. Uygulamanızın kimlik doğrulama isteğine dahil ettiği scope parametresini kullanarak bu bilgilere erişim isteğinde bulunursunuz. Kapsamları, diğer Google API'lerine erişim isteğinde bulunmak için de kullanabilirsiniz.
Kullanıcı izni ekranında ürün adınız, logonuz ve ana sayfa URL'si gibi marka bilgileri de gösterilir. Cloud Consolehizmetindeki markalama bilgilerini siz kontrol edersiniz.
Projenizin izin ekranını etkinleştirmek için:
- Google Cloud Consoleuygulamasını Google Cloud Consolecihazında açın. Branding page
- 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 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 Consoleiçinde ayarlanacak marka bilgileri yer almaz.)
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ğrulama ve kimlik jetonu alma için en yaygın kullanılan 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. Örtülü akış, istemci tarafı 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. Örtülü akış, istemci tarafında jetonların işlenmesi ve kullanılmasıyla ilgili güvenlik riskleri nedeniyle çok daha karmaşıktır. Örtülü akış uygulamanız gerekiyorsa Google Kimlik Hizmetleri'ni kullanmanızı önemle tavsiye ederiz.
Sunucu akışı
Bu protokolleri kullanabilmesi ve kullanıcılarınızın kimliğini doğrulayabilmesi için uygulamanızı Cloud Console içinde ayarladığınızdan emin olun. 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
codeiçin erişim jetonu ve kimlik jetonu değ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 gönderen kişi olduğunu ve kötü niyetli bir saldırgan olmadığını doğrulamak için bu benzersiz oturum jetonunu Google OAuth Giriş 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 işlemin 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 Discovery 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, Cloud Console Clients page .response_type, temel yetkilendirme kodu akışı isteğindecodeolmalıdır. (Daha fazla bilgi içinresponse_typeadresini ziyaret edin.)scope. Bu değer, 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 Credentials pagebölümünde 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, uygulamanız tarafından oluşturulan rastgele bir değerdir. Bu değer, mevcut olduğunda yeniden oynatma korumasını etkinleştirir.login_hint, kullanıcının e-posta adresi veyasubdizesi olabilir. Bu dize, kullanıcının Google Kimliği'ne eşdeğerdir.login_hintsağlamazsanız ve kullanıcı oturum açmış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 (daha fazla bilgiyihdadresinde bulabilirsiniz).
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//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. Sahteciliğe karşı durum 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://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 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 değerini değiştirin.
Yanıt, sunucunuzun erişim jetonu ve kimlik jetonu ile değiştirebileceğ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 Discovery 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 |
Cloud Console Clients pageadresinden aldığınız istemci kimliği. Bu kimliği OAuth 2.0 kimlik bilgilerini edinme bölümünde açıklandığı şekilde kullanabilirsiniz. |
client_secret |
Cloud Console Clients pageadresinden aldığınız istemci gizli anahtarı. Bu anahtar, OAuth 2.0 kimlik bilgilerini edinme bölümünde açıklanmıştır. |
redirect_uri |
client_id için yetkilendirilmiş bir yönlendirme URI'si,
Cloud Console
Clients pageiçinde belirtildiği gibi, Yönlendirme URI'si ayarlama bölümünde açıklanmıştır. |
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//oauth2.example.com/code& grant_type=authorization_code
Bu isteğe verilen başarılı yanıtta, bir JSON dizisinde aşağıdaki alanlar bulunur:
| 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 adlandırılan, kriptografik olarak imzalanmış Base64 kodlu bir JSON nesnesidir. Normalde, kullanmadan önce kimlik jetonunu doğrulamanız kritik önem taşır. Ancak, aracı içermeyen bir HTTPS kanalı üzerinden doğrudan Google ile iletişim kurduğunuz ve Google'da kimliğinizi doğrulamak için istemci gizli dizinizi 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 jetonu kullanmadan önce doğrulaması son derece önemlidir.
Çoğu API kitaplığı, doğrulamayı base64url kodlu değerlerin kodunu çözme ve JSON'ı ayrıştırma işlemiyle birleştirdiğinden, kimlik jetonundaki taleplere erişirken jetonu doğrulamanız muhtemeldir.
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ı (talep 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üzenlendiği zaman. Unix epoch zamanı (tam sayı saniye) olarak gösterilir. |
iss |
her zaman | Yanıtı veren tarafın veren tanımlayıcısı. Google kimliği jetonları için her zaman https://accounts.google.com veya accounts.google.com kullanın. |
sub |
her zaman | Kullanıcı için, tüm Google Hesapları arasında benzersiz olan ve asla yeniden kullanılmayan bir tanımlayıcı. 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. |
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 jetonunu doğrulamanız 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, Google'da 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 uygulamalarda 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, bu değeri kullanıcı kaydınıza bağlanmak 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ı tanımlamak için email talebinin alanına 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). Şu 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 ve Google API yanıtı tüm giriş koşullarını karşılıyorsa söz konusu kullanıcı için bir uygulama oturumu başlatmanız gerekir.
Kullanıcı, kullanıcı veritabanınızda yoksa kullanıcıyı yeni kullanıcı kayıt akışınıza yönlendirmeniz gerekir. Google'dan aldığınız bilgilere göre kullanıcıyı otomatik olarak 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.
Gelişmiş konular
Aşağıdaki bölümlerde Google OAuth 2.0 API daha ayrıntılı olarak açıklanmaktadır. Bu bilgiler, 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ı kimliklendirirken aynı zamanda kullanıcı 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, kimlik doğrulama isteğinize kullanıcının yaş grubunu eklemek için openid email https://www.googleapis.com/auth/profile.agerange.read kapsam parametresini iletin. Kullanıcı, izin 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şiminde 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:
- Yalnızca kod değişimi akışını ilk kez gerçekleştirdiğinizde yenileme jetonu alabileceğiniz için yenileme jetonunu güvenli ve kalıcı bir şekilde sakladığınızdan emin olun.
- Verilen 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 isteğinde bulunursa bu sınırlara ulaşabilir. 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 izin ekranı gösterilir. Bu nedenle, prompt=consent öğesini 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 Clients page'dan 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 gerektiren bir temel yetkilendirme kodu akışı başlatır. Değer token id_token veya id_token token ise örtülü akış başlatılır. Bu akışta, URI #fragment tanımlayıcısından jeton almak için yönlendirme URI'sinde JavaScript kullanılması gerekir. |
redirect_uri |
(Gerekli) | Yanıtın nereye gönderileceğini belirler. Bu parametrenin değeri, Cloud Console Clients page (HTTP veya HTTPS şeması, büyük/küçük harf ve varsa sondaki "/" dahil) içinde ayarladığınız yetkili yönlendirme değerlerinden biriyle tam olarak eşleşmelidir. |
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ı'na 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, Örtülü akışta ise URI
|
access_type |
(İsteğe bağlı) | İzin verilen değerler offline ve online'dir. Etkisi Ç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. |
display |
(İsteğe bağlı) | Yetkilendirme sunucusunun kimlik doğrulama ve izin kullanıcı arayüzü sayfalarını nasıl göstereceğini belirten 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şu tarafından sahip olunan hesaplar için oturum açma 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 bu alandaki hesaplar için optimize edilmesi gerektiğini belirtebilirsiniz. Yalnızca bir Google Cloud kuruluş alanı yerine genel olarak 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 artımlı 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ı birden fazla 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 izin 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, kullanıcının Google Hesabı veya tarayıcı ayarlarına göre varsayılan olarak 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:
- Kimlik doğrulama gerektiren 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 bir özellik, 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 kullanmadan veya kullanıcının kimlik doğruladığını belirten bir onay olarak kabul etmeden önce 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 geçerlilik süresinin (
exptalebi) dolmadığını doğrulayın. - İstekle bir hd parametresi değeri belirttiyseniz kimlik jetonunun, 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'yi dereference yaparsı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ın ve doğrulamayı yerel olarak gerçekleştirin. Anahtarların URI'sini, jwks_uri meta veri değerini kullanarak Discovery belgesinden
almanız gerekir. Hata ayıklama uç noktasına yapılan istekler, sıklık sınırlamasına tabi olabilir veya aralıklı hatalara neden 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 kriptografik çağrıların yapılmasını gerektirir. Neyse ki bunu yapmak 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'ye uygun 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 Discovery 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 Discovery belgesininclaims_supportedmeta veri değerini içerir. Kullanıcılar veya kuruluşları belirli alanları sağlamayı ya da sağlamamayı seçebilir. 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 "Discovery document" (Keşif belgesi) kullanımına izin verir. Bu belge, iyi bilinen bir konumda bulunan ve anahtar/değer çiftleri içeren bir JSON belgesidir. Yetkilendirme, jeton, iptal, kullanıcı bilgisi ve genel anahtarlar 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ğlar. Google'ın OpenID Connect hizmetiyle ilgili Discovery 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ı verilebilir (anlamları için ilgili belgeye bakın). Değerler tamamen açıklayıcıdır ve gerçek Google Discovery dokümanının 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 istemci 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ığı
- Google Toolbox for Mac 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ç).