Kullanıcılarınızın geçiş anahtarlarıyla kimlik doğrulaması yapabilmesi için uygulamanızın önce hesapları için geçiş anahtarını kaydetmesi veya oluşturması gerekir.
Geçiş anahtarı oluşturmak için geçiş anahtarı oluşturmak üzere gereken ayrıntıları uygulama sunucunuzdan alın ve ardından ortak ve özel anahtar çifti döndüren Credential Manager API'yi çağırın. Döndürülen özel anahtar, Google Şifre Yöneticisi gibi bir kimlik bilgisi sağlayıcıda geçiş anahtarı olarak saklanır. Ortak anahtar, uygulama sunucunuzda depolanır.
Ön koşullar
Digital Asset Links'ı ayarladığınızdan ve Android 9 (API düzeyi 28) veya sonraki sürümlerin yüklü olduğu cihazları hedeflediğinizden emin olun.
Genel Bakış
Bu kılavuzda, geçiş anahtarı oluşturmak için bağlı taraf istemci uygulamanızda yapılması gereken değişiklikler ele alınmakta ve bağlı taraf uygulama sunucusu uygulaması hakkında kısa bir genel bakış sunulmaktadır. Sunucu tarafı entegrasyonu hakkında daha fazla bilgi edinmek için Sunucu tarafı geçiş anahtarı kaydı başlıklı makaleyi inceleyin.
- Uygulamanıza bağımlılıklar ekleme: Gerekli Kimlik Bilgisi Yöneticisi kitaplıklarını ekleyin.
- Kimlik Bilgisi Yöneticisi'ni örneklendirme: Bir Kimlik Bilgisi Yöneticisi örneği oluşturun.
- Uygulama sunucusundan kimlik bilgisi oluşturma seçeneklerini alma: Uygulama sunucunuzdan istemci uygulamasına geçiş anahtarı oluşturmak için gereken ayrıntıları (ör. uygulama, kullanıcı ve
challengeile ilgili bilgiler) gönderin. - Geçiş anahtarı isteyin: Uygulamanızda, uygulama sunucusundan alınan ayrıntıları kullanarak bir
GetPublicKeyCredentialOptionnesnesi oluşturun ve bu nesneyi kullanarakcredentialManager.getCredential()yöntemini çağırıp geçiş anahtarı oluşturun. - Geçiş anahtarı oluşturma yanıtını işleme: İstemci uygulamanızda kimlik bilgilerini aldığınızda ortak anahtarı kodlamanız, serileştirmeniz ve ardından uygulama sunucusuna göndermeniz gerekir. Ayrıca, geçiş anahtarı oluşturulurken oluşabilecek her bir istisnayı da ele almanız gerekir.
- Ortak anahtarı sunucuda doğrulayın ve kaydedin: Kimlik bilgisinin kaynağını doğrulamak için sunucu tarafı adımlarını tamamlayın ve ardından ortak anahtarı kaydedin.
- Kullanıcıyı bilgilendirin: Kullanıcıya geçiş anahtarının oluşturulduğunu bildirin.
Uygulamanıza bağımlılık ekleme
Uygulama modülünüzün build.gradle dosyasına aşağıdaki bağımlılıkları ekleyin:
Kotlin
dependencies { implementation("androidx.credentials:credentials:1.7.0-alpha02") implementation("androidx.credentials:credentials-play-services-auth:1.7.0-alpha02") }
Groovy
dependencies { implementation "androidx.credentials:credentials:1.7.0-alpha02" implementation "androidx.credentials:credentials-play-services-auth:1.7.0-alpha02" }
Kimlik Bilgisi Yöneticisi'ni başlatma
CredentialManager nesnesi oluşturmak için uygulamanızı veya etkinlik bağlamınızı kullanın.
// Use your app or activity context to instantiate a client instance of
// CredentialManager.
private val credentialManager = CredentialManager.create(context)
Uygulama sunucunuzdan kimlik bilgisi oluşturma seçeneklerini alma
Kullanıcı "Geçiş Anahtarı Oluştur" düğmesini tıkladığında veya yeni bir kullanıcı kaydolduğunda, geçiş anahtarı kayıt sürecini başlatmak için gereken bilgileri almak üzere uygulamanızdan uygulama sunucunuza bir istek gönderin.
İstemci uygulamanıza geçiş anahtarı oluşturmak için gereken bilgileri (ör. kullanıcı, uygulama ve ek yapılandırma özellikleri hakkında bilgiler) göndermek üzere uygulama sunucunuzda FIDO uyumlu bir kitaplık kullanın. Daha fazla bilgi için Sunucu tarafında geçiş anahtarı kaydı başlıklı makaleyi inceleyin.
İstemci uygulamasında, uygulama sunucusu tarafından gönderilen herkese açık anahtar oluşturma seçeneklerinin kodunu çözün. Bunlar genellikle JSON biçiminde gösterilir. Web istemcileri için bu kod çözme işleminin nasıl yapıldığı hakkında daha fazla bilgi edinmek için Kodlama ve Kod Çözme başlıklı makaleyi inceleyin. Android istemci uygulamalarında kod çözme işlemini ayrı olarak yapmanız gerekir.
Aşağıdaki snippet'te, uygulama sunucusu tarafından gönderilen ortak anahtar oluşturma seçeneklerinin yapısı gösterilmektedir:
{
"challenge": "<base64url-encoded challenge>",
"rp": {
"name": "<relying party name>",
"id": "<relying party host name>"
},
"user": {
"id": "<base64url-encoded user ID>",
"name": "<user name>",
"displayName": "<user display name>"
},
"pubKeyCredParams": [
{
"type": "public-key",
"alg": -7
}
],
"attestation": "none",
"excludeCredentials": [
{
"id": "<base64url-encoded credential ID to exclude>",
"type": "public-key"
}
],
"authenticatorSelection": {
"requireResidentKey": true,
"residentKey": "required",
"userVerification": "required"
}
}
Ortak anahtar oluşturma seçeneklerindeki önemli alanlar şunlardır:
challenge: Tekrar oynatma saldırılarını önlemek için kullanılan, sunucu tarafından oluşturulan rastgele bir dize.rp: Uygulama hakkında ayrıntılar.rp.name: Uygulamanın adı.rp.id: Uygulamanın alanı veya alt alanı.
user: Kullanıcıyla ilgili ayrıntılar.id: Kullanıcının benzersiz kimliği. Bu değer, e-posta adresleri veya kullanıcı adları gibi kimliği tanımlayabilecek bilgiler içermemelidir. Rastgele bir 16 baytlık değer kullanabilirsiniz.name: Kullanıcının tanıyacağı hesap için benzersiz bir tanımlayıcı (ör. e-posta adresi veya kullanıcı adı). Bu ad, hesap seçicide gösterilir. Kullanıcı adı kullanıyorsanız şifre kimlik doğrulamadaki değerle aynı değeri kullanın.displayName: Hesap seçicide gösterilmesi amaçlanan hesap için isteğe bağlı, kullanıcı dostu bir ad.
authenticatorSelection: Kimlik doğrulama için kullanılacak cihazla ilgili ayrıntılar.authenticatorAttachment: Tercih edilen kimlik doğrulayıcıyı gösterir. Olası değerler şunlardır: -platform: Bu değer, kullanıcının cihazına yerleştirilmiş bir kimlik doğrulayıcı (ör. parmak izi sensörü) için kullanılır. -cross-platform: Bu değer, güvenlik anahtarları gibi dolaşım cihazları için kullanılır. Genellikle geçiş anahtarı bağlamında kullanılmaz. - Belirtilmemiş (önerilir): Bu değerin belirtilmemesi, kullanıcıların tercih ettikleri cihazlarda geçiş anahtarı oluşturma esnekliği sağlar. Çoğu durumda, parametreyi belirtmemek en iyi seçenektir.requireResidentKey: Geçiş anahtarı oluşturmak için buBooleanalanının değerinitrueolarak ayarlayın.residentKey: Geçiş anahtarı oluşturmak için değerirequiredolarak ayarlayın.userVerification: Geçiş anahtarı kaydı sırasında kullanıcı doğrulamasıyla ilgili şartları belirtmek için kullanılır. Olası değerler şunlardır: -preferred: Kullanıcı deneyimine korumadan daha fazla öncelik veriyorsanız bu değeri kullanın. Örneğin, kullanıcı doğrulaması korumadan daha fazla sürtünmeye neden olan ortamlarda bu değeri kullanabilirsiniz. -required: Cihazda bulunan bir kullanıcı doğrulama yönteminin çağrılması gerekiyorsa bu değeri kullanın. -discouraged: Kullanıcı doğrulama yöntemi kullanılması önerilmiyorsa bu değeri kullanın.
hakkında daha fazla bilgi edinmek içinuserVerification, userVerification ayrıntılı incelemesine bakın.
excludeCredentials: Aynı kimlik bilgisi sağlayıcısıyla zaten bir geçiş anahtarı varsa yinelenen geçiş anahtarı oluşturulmasını önlemek için kimlik bilgisi kimliklerini bir dizide listeleyin.
Geçiş anahtarı oluşturun
Sunucu tarafında herkese açık anahtar oluşturma seçeneklerini ayrıştırdıktan sonra, bu seçenekleri bir CreatePublicKeyCredentialRequest nesnesine sarmalayıp createCredential() işlevini çağırarak geçiş anahtarı oluşturun.
createPublicKeyCredentialRequest şunları içerir:
requestJson: Uygulama sunucusu tarafından gönderilen kimlik bilgisi oluşturma seçenekleri.preferImmediatelyAvailableCredentials: Bu, isteği karşılamak için güvenlik anahtarlarından veya karma anahtar akışlarından gelen kimlik bilgileri yerine yalnızca yerel olarak kullanılabilen ya da kimlik bilgisi sağlayıcıyla senkronize edilmiş kimlik bilgilerinin kullanılıp kullanılmayacağını tanımlayan isteğe bağlı bir Boole alanıdır. Olası kullanımlar şunlardır:false(varsayılan): Kimlik Bilgisi Yöneticisi'ne yapılan çağrı açık bir kullanıcı işlemiyle tetiklendiyse bu değeri kullanın.true: Kimlik Bilgisi Yöneticisi fırsatçı bir şekilde çağrılıyorsa (ör. uygulama ilk kez açıldığında) bu değeri kullanın.
Değeritrueolarak ayarlarsanız ve hemen kullanılabilir kimlik bilgisi yoksa Kimlik Bilgisi Yöneticisi herhangi bir kullanıcı arayüzü göstermez ve istek hemen başarısız olur. Bu durumda, GET istekleri için NoCredentialException, create istekleri için iseCreateCredentialNoCreateOptionExceptiondöndürülür.
origin: Bu alan, Android uygulamaları için otomatik olarak ayarlanır.originayarlaması gereken tarayıcılar ve benzer ayrıcalıklara sahip uygulamalar için Ayrıcalıklı uygulamalar için diğer taraflar adına kimlik bilgisi yöneticisi çağrıları yapma başlıklı makaleyi inceleyin.isConditional: Bu, varsayılan olarakfalsedeğerini alan isteğe bağlı bir alandır. Daha fazla bilgi için Otomatik olarak geçiş anahtarı oluşturma başlıklı makaleyi inceleyin.
createCredential() işlevini çağırmak, Kimlik Bilgisi Yöneticisi'nin yerleşik alt sayfa kullanıcı arayüzünü başlatır. Bu arayüz, kullanıcıdan geçiş anahtarı kullanmasını ve depolama için bir kimlik bilgisi sağlayıcı ile hesap seçmesini ister. Ancak isConditional, true olarak ayarlanırsa alt sayfa kullanıcı arayüzü gösterilmez ve geçiş anahtarı otomatik olarak oluşturulur.
Otomatik olarak geçiş anahtarı oluşturma
Geçiş anahtarı oluştururken isConditional parametresini CreatePublicKeyCredentialRequest içinde true olarak ayarlayarak başarılı bir şifreyle giriş işleminden sonra kullanıcı için otomatik olarak geçiş anahtarı oluşturabilirsiniz. Kullanıcının zaten geçiş anahtarı yoksa uygulamanız otomatik olarak arka planda geçiş anahtarı oluşturmaya çalışır ve bunu kullanıcının kimlik bilgisi sağlayıcısında (ör. Google Şifre Yöneticisi) saklar. Bunun nasıl uygulandığına dair bir örnek için herkese açık örneğe bakın.
Yanıtı işleme
Kullanıcı, cihazın ekran kilidi kullanılarak doğrulandıktan sonra bir geçiş anahtarı oluşturulur ve kullanıcının seçtiği kimlik bilgisi sağlayıcısında saklanır.
createCredential() işlevini başarıyla çağırdıktan sonraki yanıt, PublicKeyCredential nesnesidir.
PublicKeyCredential şu şekilde görünür:
{
"id": "<identifier>",
"type": "public-key",
"rawId": "<identifier>",
"response": {
"clientDataJSON": "<ArrayBuffer encoded object with the origin and signed challenge>",
"attestationObject": "<ArrayBuffer encoded object with the public key and other information.>"
},
"authenticatorAttachment": "platform"
}
İstemci uygulamasında nesneyi serileştirin ve uygulama sunucusuna gönderin.
Aşağıdaki snippet'te gösterildiği gibi hataları işlemek için kod ekleyin:
fun handleFailure(e: CreateCredentialException) {
when (e) {
is CreatePublicKeyCredentialDomException -> {
// Handle the passkey DOM errors thrown according to the
// WebAuthn spec.
}
is CreateCredentialCancellationException -> {
// The user intentionally canceled the operation and chose not
// to register the credential.
}
is CreateCredentialInterruptedException -> {
// Retry-able error. Consider retrying the call.
}
is CreateCredentialProviderConfigurationException -> {
// Your app is missing the provider configuration dependency.
// Most likely, you're missing the
// "credentials-play-services-auth" module.
}
is CreateCredentialCustomException -> {
// You have encountered an error from a 3rd-party SDK. If you
// make the API call with a request object that's a subclass of
// CreateCustomCredentialRequest using a 3rd-party SDK, then you
// should check for any custom exception type constants within
// that SDK to match with e.type. Otherwise, drop or log the
// exception.
}
else -> Log.w(TAG, "Unexpected exception type ${e::class.java.name}")
}
}
Ortak anahtarı uygulama sunucusunda doğrulayın ve kaydedin.
Uygulama sunucusunda, ortak anahtar kimlik bilgisini doğrulamanız ve ardından ortak anahtarı kaydetmeniz gerekir.
Ortak anahtar kimlik bilgisinin kaynağını doğrulamak için onaylı uygulamaların izin verilenler listesiyle karşılaştırın. Bir anahtarın kaynağı tanınmıyorsa anahtarı reddedin.
Uygulamanın SHA 256 parmak izini almak için:
Terminalde aşağıdaki komutu çalıştırarak yayın uygulamanızın imzalama sertifikasını yazdırın:
keytool -list -keystore <path-to-apk-signing-keystore>Yanıtınızda, imzalama sertifikasının SHA 256 parmak izini
Certificate fingerprints block:SHA256olarak belirtin.SHA256 parmak izini base64url kodlamasıyla kodlayın. Bu Python örneğinde, parmak izinin nasıl düzgün şekilde kodlanacağı gösterilmektedir:
import binascii import base64 fingerprint = '<SHA256 finerprint>' # your app's SHA256 fingerprint print(base64.urlsafe_b64encode(binascii.a2b_hex(fingerprint.replace(':', ''))).decode('utf8').replace('=', ''))Önceki adımdaki çıkışın başına
android:apk-key-hash: ekleyerek aşağıdakine benzer bir sonuç elde edin:android:apk-key-hash:<encoded SHA 256 fingerprint>Sonuç, uygulama sunucunuzdaki izin verilen bir kaynakla eşleşmelidir. Hata ayıklama ve yayınlama sertifikaları gibi birden fazla imzalama sertifikanız veya birden fazla uygulamanız varsa işlemi tekrarlayın ve tüm kaynakları uygulama sunucusunda geçerli olarak kabul edin.
Kullanıcıyı bilgilendirme
Geçiş anahtarı başarıyla oluşturulduktan sonra kullanıcılarınızı geçiş anahtarı hakkında bilgilendirin ve kimlik bilgisi sağlayıcı uygulamalarından veya uygulama ayarlarından geçiş anahtarlarını yönetebileceklerini bildirin. Kullanıcıları özel bir iletişim kutusu, bildirim veya snackbar kullanarak bilgilendirin. Kötü niyetli bir tarafın beklenmedik bir geçiş anahtarı oluşturması durumunda anında güvenlik uyarısı gönderilmesi gerektiğinden bu uygulama içi yöntemleri e-posta gibi harici iletişimlerle desteklemenizi öneririz.
Kullanıcı deneyimini iyileştirme
Credential Manager ile kayıt özelliğini uygularken kullanıcı deneyimini iyileştirmek için kimlik bilgilerini geri yükleme ve otomatik doldurma iletişim kutularını gizleme işlevlerini eklemeyi düşünebilirsiniz.
Yeni bir cihazda kimlik bilgilerini geri yükleme işlevi ekleme
Kullanıcıların yeni bir cihazda hesaplarına sorunsuz bir şekilde giriş yapmasına izin vermek için Kimlik Bilgilerini Geri Yükleme işlevini uygulayın. Geri yükleme kimlik bilgilerini eklemek, kullanıcılar yeni bir cihazda geri yüklenen uygulamanızı açtığında BackupAgent ile oturum açmalarını sağlar ve uygulamayı hemen kullanmalarına olanak tanır.
Kimlik bilgisi alanlarında otomatik doldurmayı devre dışı bırakma (isteğe bağlı)
Kullanıcıların kimlik doğrulama için Kimlik Bilgisi Yöneticisi'nin alt sayfa kullanıcı arayüzünü kullanmasının beklendiği uygulama ekranlarında, kullanıcı adı ve şifre alanlarına isCredential özelliğini ekleyin. Bu, otomatik doldurma iletişim kutularının (FillDialog ve SaveDialog) Kimlik Bilgisi Yöneticisi'nin alt sayfa kullanıcı arayüzüyle çakışmasını engeller.
isCredential özelliği, Android 14 ve sonraki sürümlerde desteklenir.
Aşağıdaki örnekte, uygulamanızın ilgili görünümlerindeki alakalı kullanıcı adı ve şifre alanlarına isCredential özelliğini nasıl ekleyebileceğiniz gösterilmektedir:
<TextView
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:isCredential="true" />
Sonraki adımlar
- Geçiş anahtarlarıyla oturum açma
- Geçiş anahtarlarını yönetme
- Geçiş anahtarı kullanıcı deneyimi akışlarını anlama