Geçiş anahtarı oluşturun

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 genel 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

Dijital Varlık Bağlantıları'nı 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 uygulaması sunucusu uygulaması hakkında kısa bir genel bakış sunulmaktadır. Sunucu tarafı entegrasyonu hakkında daha fazla bilgi edinmek için Sunucu tarafı şifre anahtarı kaydı başlıklı makaleyi inceleyin.

1. Uygulamanıza bağımlılıklar ekleme: Gerekli Credential Manager kitaplıklarını ekleyin.
2. Kimlik Bilgisi Yöneticisi'ni başlatma: Bir Kimlik Bilgisi Yöneticisi örneği oluşturun.
3. 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 challenge ile ilgili bilgiler) gönderin.
4. Geçiş anahtarı isteyin: Uygulamanızda, uygulama sunucusundan alınan ayrıntıları kullanarak bir GetPublicKeyCredentialOption nesnesi oluşturun ve bu nesneyi kullanarak credentialManager.getCredential() yöntemini çağırıp geçiş anahtarı oluşturun.
5. 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.
6. 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.
7. Kullanıcıyı bilgilendirin: Kullanıcıya geçiş anahtarının oluşturulduğunu bildirin.

1. 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:

dependencies {
    implementation("androidx.credentials:credentials:1.6.0-beta03")
    implementation("androidx.credentials:credentials-play-services-auth:1.6.0-beta03")
}

dependencies {
    implementation "androidx.credentials:credentials:1.6.0-beta03"
    implementation "androidx.credentials:credentials-play-services-auth:1.6.0-beta03"
}

2. 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)

3. 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.

Uygulama sunucunuzda FIDO uyumlu bir kitaplık kullanarak istemci 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önderin. Daha fazla bilgi edinmek 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 temel 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 bilgi, 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 bu Boolean alanının değerini true olarak ayarlayın.
    • residentKey: Geçiş anahtarı oluşturmak için değeri required olarak ayarlayın.
    • userVerification: Geçiş anahtarı kaydı sırasında kullanıcı doğrulamasıyla ilgili koşulları belirtmek için kullanılır. Olası değerler şunlardır: - preferred: Kullanıcı deneyimini korumaya göre önceliklendiriyorsanı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çin userVerification, userVerification ayrıntılı incelemesine bakın.

• excludeCredentials: Aynı kimlik bilgisi sağlayıcıyla zaten bir geçiş anahtarı varsa yinelenen geçiş anahtarı oluşturulmasını önlemek için kimlik bilgisi kimliklerini bir dizide listeleyin.

4. Geçiş anahtarı isteğinde bulunma

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ğeri true olarak 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 ise CreateCredentialNoCreateOptionException döndürülür.
• origin: Bu alan, Android uygulamaları için otomatik olarak ayarlanır. origin ayarlaması 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 olarak false değerini alan isteğe bağlı bir alandır. Bu ayarı true olarak ayarladığınızda ve kullanıcının geçiş anahtarı yoksa kaydedilmiş bir şifreyle bir sonraki oturum açma işleminde kullanıcı adına otomatik olarak geçiş anahtarı oluşturursunuz. Geçiş anahtarı, kullanıcının kimlik bilgisi sağlayıcısında saklanır. Koşullu oluşturma özelliği için androidx.credentials'ın en yeni sürümü gerekir.

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.

5. 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}")
    }
}

6. Ortak anahtarı uygulama sunucusunda doğrulayıp 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. Tanınmayan bir kaynağı olan anahtarları reddedin.

Uygulamanın SHA 256 parmak izini almak için:

1. 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 : SHA256 olarak belirtin.

2. 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('=', ''))
   

3. Ö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.

7. 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 geçiş anahtarlarını kimlik bilgisi sağlayıcı uygulamalarından veya uygulama ayarlarından 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ı verilmesi 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 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 BackupAgentoturum 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