Google'ın OAuth 2.0 API'leri hem kimlik doğrulama hem de yetkilendirme için kullanılabilir. Bu dokümanda, OpenID Connect spesifikasyonuyla uyumlu olan ve OpenID Sertifikalı olan kimlik doğrulama için OAuth 2.0 uygulamamız açıklanmaktadır. Google API'lerine Erişmek için OAuth 2.0'ı Kullanma bölümünde bulunan dokümanlar da bu hizmet için geçerlidir. Bu protokolü etkileşimli olarak keşfetmek istiyorsanız Google OAuth 2.0 Playground'u öneririz. Stack Overflow ile ilgili yardım almak için sorularınızı "google-oauth" ile etiketleyin.
OAuth 2.0'ı ayarlama
Uygulamanızın, kullanıcı girişi için Google'ın OAuth 2.0 kimlik doğrulama sistemini kullanabilmesi için Google API Console uygulamasında OAuth 2.0 kimlik bilgilerini almak, yönlendirme URI'si ayarlamak ve (isteğe bağlı olarak) kullanıcı izni ekranında gösterilen marka bilgilerini özelleştirmeniz gerekir. Hizmet hesabı oluşturmak, faturalandırmayı etkinleştirmek, filtreleme ayarlamak ve başka işlemler yapmak için de API Console hizmetini kullanabilirsiniz. Daha fazla bilgi için Google API Console Yardım'a bakın.
OAuth 2.0 kimlik bilgilerini alma
Kullanıcıların kimliğini doğrulamak ve Google'ın API'lerine erişmek için 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
Google'ın, kimlik doğrulama isteklerinize yanıt gönderdiği API Console yerlerde belirlediğiniz yönlendirme URI'si belirlenir.
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 deneyimi, kullanıcının serbest bıraktığı bilgileri ve geçerli şartları açıklayan bir izin 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. Uygulamanızın kimlik doğrulama isteğine dahil ettiği scope
parametresini kullanarak bu bilgilere ulaşmak isteyebilirsiniz. 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 sayfanızın URL'si gibi marka bilgileri de sunulur. Marka bilinci oluşturma bilgilerini, API Consoleiçinde kontrol edersiniz.
Projenizin onay ekranını etkinleştirmek için:
- Aç Consent Screen page yılında Google API Console .
- If prompted, select a project, or create a new one.
- Formu doldurun ve Kaydet'i tıklayın .
Aşağıdaki izin iletişim kutusunda, istekte OAuth 2.0 ve Google Drive kapsamlarının kombinasyonu bulunduğunda kullanıcının ne göreceği gösterilir. (Bu genel iletişim kutusu, Google OAuth 2.0 Playground kullanılarak oluşturulmuştur. Bu yüzden, API Consoleiçinde ayarlanacak marka bilgilerini içermez.)

Hizmete erişme
Google ve üçüncü taraflar, kullanıcıların kimliğini doğrulama ve Google API'lerine erişim elde etmeyle ilgili birçok uygulama ayrıntısını yerine getirmek için kullanabileceğiniz kitaplıklar sağlar. Google Kimlik Hizmetleri ve çeşitli platformlarda kullanılabilen Google istemci kitaplıkları örnek olarak verilebilir.
Kitaplık kullanmamayı tercih ederseniz bu kitaplığın geri kalanında yer alan ve mevcut kitaplıkların altında yatan HTTP istek akışlarını açıklayan talimatları uygulayın.
Kullanıcının kimliğini doğrulama
Kullanıcının kimliğini doğrulamak için kimlik jetonu alma ve doğrulama gerekir. Kimlik jetonları, internet üzerinden kimlik doğrulama işlemlerinde kullanılmak üzere tasarlanmış OpenID Connect'in standartlaştırılmış bir özelliğidir.
Bir kullanıcının kimliğini doğrulamak ve kimlik jetonu almak için en sık kullanılan yaklaşımlara "sunucu" akışı ve "dolaylı" akış denir. Sunucu akışı, bir uygulamanın arka uç sunucusunun tarayıcı veya mobil cihaz kullanan kişinin kimliğini doğrulamasına olanak tanır. Dolaylı akış, istemci taraflı bir uygulamanın (genellikle tarayıcıda çalışan bir JavaScript uygulaması) arka uç sunucusu yerine API'lere 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. İstemci tarafında jetonların işlenmesi ve kullanılmasıyla ilgili güvenlik riskleri nedeniyle, dolaylı akış önemli ölçüde daha karmaşıktır. Dolaylı bir akış uygulamanız gerekiyorsa Google Kimlik Hizmetleri'ni kullanmanızı önemle tavsiye ederiz.
Sunucu akışı
Bu protokolleri kullanmak ve kullanıcılarınızın kimliklerini doğrulamak için uygulamanızı API Consoleiçinde ayarladığınızdan emin olun. Bir kullanıcı Google ile giriş yapmayı denediğinde:
- Sahtekarlık karşıtı durum jetonu oluşturma
- Google'a kimlik doğrulama isteği gönderme
- Sahtekarlık karşıtı durum jetonunu onaylama
- Erişim jetonu ve kimlik jetonu için
code
değişimi - Kimlik jetonundan kullanıcı bilgilerini alma
- Kullanıcının kimliğini doğrulama
1. Sahtekarlık karşıtı durum jetonu oluşturun
Sahtekarlık isteklerine yönelik saldırıları önleyerek kullanıcılarınızın güvenliğini sağlamalısınız. İlk adım, uygulamanız ile kullanıcının istemcisi arasında durumu tutan benzersiz bir oturum jetonu oluşturmaktır. Daha sonra bu benzersiz oturum jetonunu, kullanıcının kötü amaçlı bir saldırganla değil, istekte bulunduğunu doğrulamak için Google OAuth Giriş hizmeti tarafından döndürülen kimlik doğrulama yanıtıyla eşleştirirsiniz. Bu jetonlar genellikle siteler arası istek sahtekarlığı (CSRF) jetonları olarak adlandırılır.
Eyalet jetonu için iyi bir seçim, yüksek kaliteli bir rastgele sayı jeneratörü kullanılarak oluşturulan 30 karakterli dizedir. Bir diğeri de oturum durumu değişkenlerinizden bazılarının arka ucunda gizli tutulan bir anahtarla imzalanmasıyla elde edilen karmadır.
Aşağıdaki kod, benzersiz oturum jetonları oluşturmayı göstermektedir.
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 isterseniz Java için Google API'leri istemci kitaplığı'nı indirmeniz gerekir.
// Create a state token to prevent request forgery. // Store it in the session for later validation. String state = new BigInteger(130, new SecureRandom()).toString(32); request.session().attribute("state", state); // Read index.html into memory, and set the client ID, // token state, and application name in the HTML before serving it. return new Scanner(new File("index.html"), "UTF-8") .useDelimiter("\\A").next() .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID) .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state) .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}", APPLICATION_NAME);
Python
Bu örneği kullanmak istiyorsanız Python için Google API'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
Sonraki adım, uygun URI parametreleriyle HTTPS GET
isteği oluşturmaktır.
Bu sürecin tüm adımlarında HTTP yerine HTTPS kullanıldığını unutmayın. HTTP bağlantıları reddedilir. authorization_endpoint
meta veri değerini kullanarak temel URI'yi Discovery dokümanından almanız gerekir. Aşağıdaki tartışmada temel URI'nin https://accounts.google.com/o/oauth2/v2/auth
olduğu varsayılmıştır.
Temel istek için aşağıdaki parametreleri belirtin:
client_id
API Console Credentials pageresponse_type
. Bu, temel yetkilendirme kodu akışı isteğindecode
olmalıdır. (Daha fazla bilgi içinresponse_type
adresini ziyaret edin.)scope
. Bu istek temel istekteopenid email
olmalıdır. (Daha fazla bilgi içinscope
adresini ziyaret edin.)redirect_uri
, sunucunuzda Google'dan yanıt alacak HTTP uç noktası olmalıdır. Değer, API Console Credentials page içinde 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 istek,redirect_uri_mismatch
hatasıyla başarısız olur.state
, sahte olmayan kullanıma yönelik benzersiz oturum jetonunun değerini ve kullanıcı uygulamanıza döndüğünde bağlamı kurtarmak için gereken diğer bilgileri (ör. başlangıç URL'si) içermelidir. (Daha fazla bilgi içinstate
adresini ziyaret edin.)nonce
, uygulamanız tarafından oluşturulan rastgele bir değerdir ve mevcut olduğunda tekrarlama korumasını etkinleştirir.login_hint
, kullanıcının e-posta adresi veya kullanıcının Google kimliğiyle eşdeğer olansub
dizesi olabilir.login_hint
bilgilerini sağlamazsanız ve kullanıcı şu an oturum açmış durumdaysa izin ekranında kullanıcının e-posta adresinin uygulamanızda yayınlanması için bir onay isteği yer alır. (login_hint
adresinde daha fazla bilgi edinebilirsiniz.)- OpenID Connect akışını bir Google Cloud kuruluşuyla ilişkili belirli bir alanın kullanıcıları için optimize etmek amacıyla
hd
parametresini kullanın. (Daha fazla bilgi içinhd
adresini ziyaret edin.)
Okunabilirlik için satır sonu ve boşluk içeren eksiksiz bir OpenID Connect kimlik doğrulama URI'sini aşağıda görebilirsiniz:
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ın yeni bilgiler talep etmesi veya daha önce onaylamadıkları hesap erişimi istemesi durumunda kullanıcıların izin vermesi gerekir.
3. Sahtekarlıktan korunma 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ğrulaması, isteği kötü amaçlı bir komut dosyasının değil, kullanıcının yapmasını sağlamaya yardımcı olur.
Aşağıdaki kod, 1. Adım'da oluşturduğunuz oturum jetonlarının onaylandığını göstermektedir:
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 isterseniz Java için Google API'leri istemci kitaplığı'nı indirmeniz gerekir.
// Ensure that there is no request forgery going on, and that the user // sending us this connect request is the user that was supposed to. if (!request.queryParams("state").equals( request.session().attribute("state"))) { response.status(401); return GSON.toJson("Invalid state parameter."); }
Python
Bu örneği kullanmak istiyorsanız Python için Google API'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ğişimi
Yanıtta code
parametresi vardır. Bu, sunucunuzun bir erişim jetonu ve kimlik jetonuyla değiştirebileceği tek seferlik bir yetkilendirme kodudur. Sunucunuz, bu alışverişi bir HTTPS POST
isteği göndererek yapar. POST
İstek, jeton uç noktasına gönderilir ve bu değeri Discovery dokümanından token_endpoint
meta veri değerini kullanarak almanız gerekir. Aşağıdaki tartışmada uç noktanın https://oauth2.googleapis.com/token
olduğu varsayılmaktadır. İstek, POST
gövdesinde aşağıdaki parametreleri içermelidir:
Alanlar | |
---|---|
code |
İlk istekten döndürülen yetkilendirme kodu. |
client_id |
OAuth 2.0 kimlik bilgilerini edinme bölümünde açıklandığı şekilde API Console Credentials pagearacılığıyla edindiğiniz istemci kimliği. |
client_secret |
OAuth 2.0 kimlik bilgilerini edinme bölümünde açıklandığı şekilde, API Console Credentials pagearacılığıyla edindiğiniz istemci sırrı. |
redirect_uri |
Yönlendirme URI'si ayarlama bölümünde açıklandığı üzere, API ConsoleCredentials pageiçinde belirtilen, client_id için yetkili bir yönlendirme URI'sı. |
grant_type |
Bu alan, OAuth 2.0 spesifikasyonunda tanımlandığı şekilde authorization_code değerini içermelidir. |
Asıl istek aşağıdaki örnekteki gibi görünebilir:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your-client-id& client_secret=your-client-secret& redirect_uri=https%3A//oauth2.example.com/code& grant_type=authorization_code
Bu isteğe başarılı bir yanıt, JSON dizisinde aşağıdaki alanları içerir:
Alanlar | |
---|---|
access_token |
Google API'sine gönderilebilen bir jeton. |
expires_in |
Erişim jetonunun saniye cinsinden kalan ömrü. |
id_token |
Google tarafından dijital olarak imzalanan, kullanıcı hakkında kimlik bilgileri içeren bir JWT. |
scope |
access_token tarafından verilen erişim kapsamları, boşlukla ayrılmış ve büyük/küçük harfe duyarlı dizelerin listesi olarak belirtilir. |
token_type |
Döndürülen jetonun türünü tanımlar. Şu anda bu alan 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 edinme
Kimlik Jetonu, JWT (JSON Web Jetonu) yani kriptografik olarak imzalanmış bir Base64 kodlu JSON nesnesidir. Normalde bir kimlik jetonunu kullanmadan önce kimlik jetonunu doğrulamanız kritik öneme sahiptir, ancak aracısız 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 iletirse diğer bileşenlerin, jetonu kullanmadan önce Jetonu doğrulaması çok önemlidir.
Çoğu API kitaplığı, doğrulamayı, base64url olarak kodlanmış değerlerin kodunu çözme ve JSON içindeki ayrıştırma işlemlerini birleştirerek gerçekleştirdiğinden, muhtemelen jeton jetondaki hak taleplerine erişirken jetonu doğrulayabilirsiniz.
Kimlik jetonunun yükü
Kimlik jetonu, bir ad/değer çifti kümesi içeren bir JSON nesnesidir. Aşağıda, okunabilirlik için biçimlendirilmiş bir örnek verilmiştir:
{ "iss": "https://accounts.google.com", "azp": "1234987819200.apps.googleusercontent.com", "aud": "1234987819200.apps.googleusercontent.com", "sub": "10769150350006150715113082367", "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q", "hd": "example.com", "email": "jsmith@example.com", "email_verified": "true", "iat": 1353601026, "exp": 1353604926, "nonce": "0394852-3190485-2490358" }
Google ID Jetonları aşağıdaki alanları içerebilir (hak talepleri olarak bilinir):
Hak talebi | Sağlandı | Açıklama |
---|---|---|
aud |
always | Bu kimlik jetonunun hedeflendiği kitle. Uygulamanızın OAuth 2.0 istemci kimliklerinden biri olmalıdır. |
exp |
always | Kimlik jetonunun kabul edilmemesi gereken son kullanma tarihi. Unix saatiyle (tamsayı saniyesi) gösterilir. |
iat |
always | Kimlik jetonunun verildiği zaman. Unix zamanında temsil edilir (tamsayı saniyesi). |
iss |
always | Yanıtın Veren Kuruluş Kimliği. Google kimliği jetonları için her zaman https://accounts.google.com veya accounts.google.com . |
sub |
always | Kullanıcının tüm Google hesapları için benzersiz ve hiçbir zaman tekrar kullanılmayan tanımlayıcısı. Bir Google hesabı, farklı noktalarda birden fazla e-posta adresine sahip olabilir. Ancak sub değeri hiçbir zaman değişmez. Uygulamanızda kullanıcı için benzersiz tanımlayıcı anahtar olarak sub kullanın. Maksimum 255 büyük/küçük harfe duyarlı 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 bir access_token değeriyle yayınlanırsa 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 jetonunun doğrulanması gerekmez. |
|
azp |
Yetkili sunucunun client_id . Bu hak talebi yalnızca kimlik jetonunu isteyen taraf, kimlik jetonunun kitlesiyle aynı olmadığında gereklidir. Bir web uygulaması ve Android uygulaması farklı bir OAuth 2.0 client_id sürümüne sahip ancak aynı Google API'leri projesini paylaşan karma uygulamalar için Google'da bu durum geçerli olabilir. |
|
email |
Kullanıcının e-posta adresi. Bu değer, kullanıcıya özel olmayabilir ve birincil anahtar olarak kullanılamaz. Yalnızca kapsamınız email kapsam değerini içeriyorsa sağlanır. |
|
email_verified |
Kullanıcının e-posta adresi doğrulandıysa doğru, aksi takdirde yanlış değerini alır. | |
family_name |
Kullanıcının soyadı veya soyadı. name hak talebi mevcut olduğunda sağlanabilir. |
|
given_name |
Kullanıcıya verilen adlar veya adlar. name hak talebi mevcut olduğunda sağlanabilir. |
|
hd |
Kullanıcının Google Cloud kuruluşuyla ilişkilendirilmiş alan adı. Yalnızca kullanıcı bir Google Cloud kuruluşuna aitse sağlanır. | |
locale |
Kullanıcının yerel ayarı (BCP 47 dil etiketiyle gösterilir).
name hak talebi mevcut olduğunda sağlanabilir. |
|
name |
Kullanıcının tam adı, gösterilen bir biçimde olmalıdır. Aşağıdaki durumlarda sağlanabilir:
|
|
nonce |
Uygulamanızın kimlik doğrulama isteğinde sağladığı nonce değeridir.
Videoların yalnızca bir defa sunulduğundan emin olarak tekrarlı saldırılara karşı koruma sağlamalısınız. |
|
picture |
Kullanıcının profil resminin URL'si. Aşağıdaki durumlarda sağlanabilir:
|
|
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ğrulama
Kimlik jetonundan kullanıcı bilgilerini aldıktan sonra uygulamanızın kullanıcı veritabanını sorgulamalısınız. Kullanıcı, veritabanınızda zaten mevcutsa tüm giriş gereksinimleri Google API yanıtı tarafından karşılanı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 kaydettirebilir ya da en azından kayıt formunuzda gerekli olan alanların çoğunu önceden doldurabilirsiniz. Kimlik jetonundaki bilgilere ek olarak, kullanıcı profili uç noktalarımızda ek kullanıcı profili bilgileri edinebilirsiniz.
İleri düzey konular
Aşağıdaki bölümlerde Google OAuth 2.0 API'si daha ayrıntılı olarak açıklanmaktadır. Bu bilgi, kimlik doğrulama ve yetkilendirmeyle ilgili gelişmiş şartları olan geliştiriciler için hazırlanmıştır.
Diğer Google API'lerine erişme
Kimlik doğrulama için OAuth 2.0 kullanmanın avantajlarından biri, uygulamanızın kimlik doğrulaması sırasında aynı anda kullanıcı adına (YouTube, Google Drive, Takvim veya Kişiler gibi) diğer Google API'lerini kullanma izni alabilmesidir. Bunu yapmak için ihtiyacınız olan diğer kapsamları Google'a gönderdiğiniz kimlik doğrulama isteğine 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ıya, izin ekranında uygun şekilde mesaj 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şmenize olanak tanır.
Jetonları yenile
API erişimi isteğinizde, code
değişimi sırasında döndürülecek bir jeton isteyebilirsiniz. Yenileme jetonu, uygulamanızda kullanıcı mevcut değilken uygulamanızın Google API'lerine sürekli erişebilmesini 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ği için alabileceğinizden emin olun.
- Sunulan yenileme jetonlarının sayısı sınırlıdır: İstemci/kullanıcı kombinasyonu başına bir sınır ve tüm istemciler genelinde kullanıcı başına bir sınır. Uygulamanız çok fazla yenileme jetonu istiyorsa bu sınırlarla karşılaşabilirsiniz. Bu durumda, eski yenileme jetonlarının çalışması durur.
Daha fazla bilgi için Erişim jetonunu yenileme (çevrimdışı erişim) başlıklı makaleye bakın.
Yeniden izin isteniyor
Kimlik doğrulama isteğinizde prompt
parametresini consent
olarak ayarlayarak kullanıcıdan uygulamanızı yeniden yetkilendirmesini isteyebilirsiniz. prompt=consent
dahil edildiğinde, uygulamanız daha önce Google API'leri projenize verilmiş olsa bile izin kapsamları her yetkilendirme isteğinde bulunduğunda 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'sı parametreleri tablosunda 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 parametrelerle ilgili daha kapsamlı açıklamalar sunulmaktadır.
Parametre | Zorunlu | Açıklama |
---|---|---|
client_id |
(Gerekli) | OAuth 2.0 kimlik bilgilerini edinme bölümünde açıklandığı şekilde, API ConsoleCredentials pagearacılığıyla edindiğiniz istemci kimliği dizesi. |
nonce |
(Gerekli) | Tekrar oluşturulan korumayı etkinleştiren, uygulamanız tarafından oluşturulan rastgele bir değerdir. |
response_type |
(Gerekli) | Değer code ise jetonları almak için jeton uç noktasına POST kullanılmasını gerektiren bir Temel yetkilendirme kodu akışı başlatır. Değer token id_token veya id_token token ise URI #fragment tanımlayıcısından jetonları almak için yönlendirme URI'sinde JavaScript kullanılmasını gerektiren bir Dolaylı akış başlatır. |
redirect_uri |
(Gerekli) | Yanıtın gönderileceği yeri belirler. Bu parametrenin değeri, API Consoleiçinde ayarladığınız yetkili yönlendirme değerlerinden biriyle tam olarak eşleşmelidir. Credentials page (HTTP veya HTTPS şeması, büyük/küçük harf durumu ve varsa '/' dahil). |
scope |
(Gerekli) | Kapsam parametresi
Bu OpenID'ye özel kapsamlara ek olarak, kapsam bağımsız değişkeniniz de diğer kapsam değerlerini içerebilir. Tüm kapsam değerleri boşlukla ayrılmalıdır. Örneğin, bir kullanıcının Google Drive'ına dosya başına erişim istiyorsanız kapsam parametreniz Kullanılabilir kapsamlar hakkında bilgi edinmek için Google API'leri için OAuth 2.0 Kapsamları veya kullanmak istediğiniz Google API'si ile ilgili dokümanları inceleyin. |
state |
(İsteğe bağlıdır, ancak kesinlikle önerilir) | Protokolde yuvarlatılmış opak bir dize. Yani dizenin Temel akıştaki URI parametresi ve Örtük akıştaki URI
|
access_type |
(İsteğe bağlı) | offline ve online değerlerine izin verilir. Etki, Çevrimdışı Erişim bölümünde belgelenmiştir. 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 kullanıcı rızası arayüzü sayfalarını nasıl görüntüleyeceğini belirtmek için kullanılan bir ASCII dize değeri. Şu değerler belirtilir ve Google sunucuları tarafından kabul edilir, ancak davranışı üzerinde herhangi bir etkisi yoktur: page , popup , touch ve wap . |
hd |
(İsteğe bağlı) | Bir Google Cloud kuruluşunun sahip olduğu hesaplar için giriş işlemini kolaylaştırın. Google Cloud kuruluş alanını (örneğin, mycollege.edu) ekleyerek hesap seçimi kullanıcı arayüzünün söz konusu alandaki hesaplar için optimize edilmesi gerektiğini belirtebilirsiniz. Yalnızca bir Google Cloud kuruluş alanı yerine Google Cloud kuruluş hesapları için optimizasyon yapmak istiyorsanız yıldız işaretini ( İstemci tarafı istekleri değiştirilebileceğinden uygulamanıza kimlerin erişebileceğini kontrol etmek için bu kullanıcı arayüzü optimizasyonuna güvenmeyin. İade edilen kimlik jetonunun, beklediğinizle eşleşen bir |
include_granted_scopes |
(İsteğe bağlı) | Bu parametre true değeriyle sağlanırsa ve yetkilendirme isteği verilirse yetkilendirme, diğer kapsamlar için bu kullanıcıya/uygulama kombinasyonuna verilen önceki yetkilendirmeleri de içerir. Ek yetkilendirme bölümüne bakın.
Yüklü uygulama akışıyla artımlı yetkilendirme yapamayacağınızı unutmayın. |
login_hint |
(İsteğe bağlı) | Uygulamanız hangi kullanıcının kimliğini doğrulamaya çalıştığını bilirse bu parametreyi kimlik doğrulama sunucusuna ipucu olarak sağlayabilir. Bu ipucunun iletilmesi, hesap seçiciyi gizler ve oturum açma formundaki e-posta kutusunu önceden doldurur ya da uygun oturumu (kullanıcı çoklu oturum açma kullanıyorsa) seçer. Uygulamanız yanlış kullanıcı hesabına giriş yaparsa ortaya çıkabilecek sorunlardan kaçınmanıza yardımcı olabilir.
Değer, kullanıcının Google kimliğiyle eşdeğer olan bir e-posta adresi veya 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 listesi. Olası değerler:
Herhangi bir değer belirtilmemişse ve kullanıcı daha önce erişim yetkisi vermemişse kullanıcıya bir izin ekranı gösterilir. |
Kimlik jetonu doğrulama
Sunucunuzdaki tüm kimlik jetonlarının doğrudan Google'dan geldiğini bilmiyorsanız bunları doğrulamanız gerekir. Örneğin, sunucunuzun istemci uygulamalarınızdan aldığı tüm kimlik jetonlarını orijinal olarak doğrulaması gerekir.
Sunucunuza kimlik jetonları gönderebileceğiniz yaygın durumlar şunlardır:
- Kimlik doğrulaması gerektiren istekler içeren kimlik jetonları gönderme. Kimlik jetonları, istekte bulunan belirli bir kullanıcıyı ve bu kimlik jetonunun hangi istemciye verildiğini bildirir.
Kimlik jetonları hassastır ve ele geçirilirse yanlış kullanılabilir. Bu jetonların yalnızca HTTPS üzerinden ve yalnızca POST verileri aracılığıyla ya da istek başlıkları içinde iletilerek güvenli bir şekilde işlendiğinden emin olmanız gerekir. Kimlik jetonlarını sunucunuzda depoluyorsanız bunları da güvenli bir şekilde depolamanız gerekir.
Kimlik jetonlarını kullanışlı yapan bir özellik, bunları uygulamanızın farklı bileşenlerinin etrafına geçirebilmenizdir. Bu bileşenler, uygulamanın ve kullanıcının kimliğini doğrulayan basit bir kimlik doğrulama mekanizması olarak bir kimlik jetonu kullanabilir. Ancak, kimlik jetonundaki bilgileri kullanabilmek veya kullanıcının kimlik doğrulaması yaptığını doğrulamak için bu kodu kullanmadan önce bu kodu doğrulamanız gerekir.
Kimlik jetonunun doğrulanması için birkaç adım gereklidir:
- Kimlik jetonunun, kartı veren kuruluş tarafından doğru şekilde imzalandığını doğrulayın. Google tarafından verilen jetonlar, Discovery dokümanındaki
jwks_uri
meta veri değerinde belirtilen URI'da bulunan sertifikalardan biri kullanılarak imzalanır. - Kimlik jetonundaki
iss
hak talebinin değerininhttps://accounts.google.com
veyaaccounts.google.com
değerine eşit olduğunu doğrulayın. - Kimlik jetonundaki
aud
hak talebinin değerinin, uygulamanızın istemci kimliğine eşit olduğunu doğrulayın. - Kimlik jetonunun geçerlilik süresinin (
exp
hak talebi) iletilmediğini doğrulayın. - İstekte hd parametresi değeri belirlediyseniz kimlik jetonunun, Google Cloud kuruluşuyla ilişkili kabul edilen bir alan adıyla eşleşen
hd
hak talebinde bulunduğunu doğrulayın.
2. ila 5. adımlarda, yalnızca oldukça basit olan dize ve tarih karşılaştırmaları yer alır. Bu nedenle, bu ayrıntıları burada ayrıntılı olarak açıklamayız.
İlk adım daha karmaşıktır ve kriptografik imza kontrolü 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. Bu durumda https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123
URI'sının referansını kaldırırsınız. Jeton imzası geçerliyse yanıt, kodu çözülmüş JSON nesne biçiminde JWT yükü olur.
tokeninfo
uç noktası, hata ayıklama için faydalı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. Anahtarların URI'sini, jwks_uri
meta veri değerini kullanarak Discovery dokümanından almalısınız. Hata ayıklama uç noktasına yapılan istekler kısıtlanabilir veya başka şekillerde aralıklı hatalara neden olabilir.
Google, ortak anahtarlarını yalnızca nadiren değiştirdiğinden, HTTP yanıtının önbellek yönergelerini kullanarak bunları önbelleğe alabilir ve çoğu durumda yerel doğrulamayı tokeninfo
uç noktasına kıyasla çok daha verimli bir şekilde gerçekleştirebilirsiniz. Bu doğrulama, sertifikaların alınıp ayrıştırılmasını ve imzayı kontrol etmek için uygun kriptografik çağrıların yapılmasını gerektirir. Neyse ki, bunu yapmak için çok çeşitli dillerde kullanılabilen, hata ayıklamaya uygun kitaplıklar mevcut (bkz. jwt.io).
Kullanıcı profili bilgilerini elde etme
Kullanıcı hakkında ek profil bilgileri almak için erişim jetonunu (uygulamanızın kimlik doğrulama akışı sırasında aldığı adres) ve OpenID Connect standardını kullanabilirsiniz:
OpenID ile uyumlu olmak için kimlik doğrulama isteğinize
openid profile
kapsam değerlerini eklemeniz gerekir.Kullanıcının e-posta adresinin dahil edilmesini istiyorsanız
email
şeklinde ek bir kapsam değeri belirtebilirsiniz. Hemprofile
hem deemail
değ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 kullanıcı bilgileri uç noktasına bir HTTPS
GET
isteği gönderin. Bu isteği,userinfo_endpoint
meta veri değerini kullanarak Keşif dokümanından almanız gerekir. Userinfo yanıtı,OpenID Connect Standard Claims
bölümünde açıklandığı şekilde ve Discovery dokümanınınclaims_supported
meta veri değeri gibi kullanıcıyla ilgili bilgileri içerir. Kullanıcılar veya kuruluşları, belirli alanları sunmayı veya saklamayı tercih edebilir. Bu nedenle, yetkili erişim kapsamlarınız için her alanla ilgili bilgi alamayabilirsiniz.
Keşif dokümanı
OpenID Connect protokolü, kullanıcıların kimliğini doğrulamak ve jetonlar, kullanıcı bilgileri, ortak anahtarlar gibi kaynaklar için istek göndermek üzere birden fazla uç nokta kullanılmasını gerektirir.
OpenID Connect, uygulamaları basitleştirmek ve esnekliği artırmak için "Keşif dokümanı"nın kullanılmasına izin verir. Bu doküman, bilinen bir konumda bulunan ve anahtar/değer çiftleri içeren bir JSON dokümanıdır. Bu doküman; yetkilendirme, jeton, iptal, kullanıcı bilgileri ve ortak anahtar uç noktalarının URI'leri gibi OpenID Connect sağlayıcısının yapılandırması hakkında ayrıntılı bilgi sağlar. Google'ın OpenID Connect hizmetiyle ilgili Discovery dokümanı şuradan alınabilir:
https://accounts.google.com/.well-known/openid-configuration
Google'ın OpenID Connect hizmetlerini kullanmak için Discovery doküman URI'sını (https://accounts.google.com/.well-known/openid-configuration
) uygulamanıza sabit olarak kodlamanız gerekir.
Uygulamanız dokümanı getirir, yanıtta önbelleğe alma kurallarını uygular ve ardından gerektiğinde uç nokta URI'larını 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.
Aşağıda bu tür bir doküman örneği verilmiştir. Alan adları, OpenID Connect Discovery 1.0'da belirtilen alanlardır (anlamları için söz konusu dokümana bakın). Değerler tamamen açıklama amaçlıdır ve gerçek Google Discovery dokümanının en yeni sürümünden kopyalanmış olsa bile 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 dokümanındaki değerleri önbelleğe alarak bir HTTP gidiş dönüşünü önlemek isteyebilirsiniz. Standart HTTP önbelleğe alma üst bilgileri kullanılır ve bunlara saygı gösterilmelidir.
İ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ığı
- Yakut için Google API'leri İstemci Kitaplığı
- PHP için Google API'leri İstemci Kitaplığı
- Google Web Araç Seti için OAuth 2.0 Kitaplığı
- Mac OAuth 2.0 Kumandaları için Google Araç Kutusu
OpenID Connect uygunluğu
Google'ın OAuth 2.0 kimlik doğrulama sistemi, OpenID Connect Core spesifikasyonunun gerekli özelliklerini destekler. OpenID Connect ile çalışacak şekilde tasarlanmış tüm istemciler, bu hizmet ile çalışmalıdır (OpenID İstek Nesnesi hariç).