인증 관리자로 사용자 인증 정보 복원 구현

이 페이지에서는 복원 키를 만들고, 복원 키로 로그인하고, 복원 키를 삭제하는 방법을 설명합니다.

버전 호환성

인증 관리자의 사용자 인증 정보 복원은 Android 9 이상, Google Play 서비스 (GMS) 코어 버전 24220000 이상, androidx.credentials 라이브러리 버전 1.5.0 이상을 실행하는 기기에서 작동합니다.

기본 요건

패스키 서버와 유사한 신뢰 당사자 서버를 설정합니다. 패스키로 인증을 처리하도록 서버가 이미 설정되어 있는 경우 복원 키에 동일한 서버 측 구현을 사용합니다.

종속 항목

앱 모듈의 build.gradle 파일에 다음 종속 항목을 추가합니다.

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"
}

사용자 인증 정보 복원은 androidx.credentials 라이브러리 버전 1.5.0 이상에서 사용할 수 있습니다. 하지만 가능한 경우 종속 항목의 최신 안정화 버전을 사용하는 것이 좋습니다.

개요

  1. 복원 키 만들기: 복원 키를 만들려면 다음 단계를 완료합니다.
    1. 인증 관리자 인스턴스화: CredentialManager 객체를 만듭니다.
    2. 앱 서버에서 사용자 인증 정보 생성 옵션 가져오기: 앱 서버에서 복원 키를 만드는 데 필요한 세부정보를 클라이언트 앱에 보냅니다.
    3. 복원 키 만들기: 사용자가 앱에 로그인한 경우 사용자 계정의 복원 키를 만듭니다.
    4. **사용자 인증 정보 생성 응답 처리**: 처리를 위해 클라이언트 앱의 사용자 인증 정보를 앱 서버로 보내고 예외를 처리합니다.
  2. 복원 키로 로그인: 복원 키로 로그인하려면 다음 단계를 완료합니다.
    1. 앱 서버에서 사용자 인증 정보 검색 옵션 가져오기: 앱 서버에서 복원 키를 검색하는 데 필요한 세부정보를 클라이언트 앱에 보냅니다.
    2. 복원 키 가져오기: 사용자가 새 기기를 설정할 때 인증 관리자에서 복원 키를 요청합니다. 이렇게 하면 사용자가 추가 입력을 하지 않고도 로그인할 수 있습니다.
    3. 사용자 인증 정보 검색 응답 처리: 사용자를 로그인 처리하기 위해 클라이언트 앱의 복원 키 를 앱 서버로 보냅니다.
  3. 복원 키 삭제.

복원 키 만들기

활성 사용자가 복원 키를 만들 수 있도록 앱에서 사용자의 모든 로그인 사례를 처리해야 합니다. 다음 시나리오에서 복원 키를 만듭니다.

  • 사용자가 로그인되어 있고 복원 키가 아직 생성되지 않은 경우 (예: 기본 Activity의 onCreate 메서드).
  • 사용자가 로그인하거나 새 계정 등록 흐름을 완료할 때.

성능을 최적화하고 모든 로그인에서 복원 사용자 인증 정보를 만들거나 확인하는 오버헤드를 방지하려면 키가 이미 생성되었는지 추적하도록 로컬 저장소(예: has_synced_restore_credential)에 boolean 플래그 또는 사용자 인증 정보 생성 타임스탬프를 설정합니다.

인증 관리자 인스턴스화

앱의 활동 컨텍스트를 사용하여 CredentialManager 객체를 인스턴스화합니다.

// Use your app or activity context to instantiate a client instance of
// CredentialManager.
private val credentialManager = CredentialManager.create(context)

앱 서버에서 사용자 인증 정보 생성 옵션 가져오기

앱 서버에서 FIDO 호환 라이브러리를 사용하여 사용자, 앱, 추가 구성 속성과 같은 복원 사용자 인증 정보를 만드는 데 필요한 정보를 클라이언트 앱에 보냅니다. 서버 측 구현에 관한 자세한 내용은 서버 측 안내를 참고하세요.

복원 키 만들기

서버에서 보낸 공개 키 생성 옵션을 파싱한 후 이러한 옵션을 CreateRestoreCredentialRequest 객체로 래핑하고 CredentialManager 객체로 createCredential() 메서드를 호출하여 복원 키를 만듭니다.

// createRestoreRequest contains the details sent by the server 
val response = credentialManager.createCredential(context, createRestoreRequest)

코드에 관한 주요 사항

  • CreateRestoreCredentialRequest 객체에는 다음 필드가 포함됩니다.

    • requestJson: PublicKeyCredentialCreationOptionsJSON의 Web Authentication API 형식으로 앱 서버에서 보낸 사용자 인증 정보 생성 옵션입니다.

    • isCloudBackupEnabled: 복원 키를 클라우드에 백업해야 하는지 결정하는 Boolean 필드입니다. 기본적으로 이 플래그는 true입니다. 이 필드에는 다음과 같은 값이 있습니다.

      • true: (권장) 사용자가 Google 백업 및 엔드 투 엔드 암호화(예: 화면 잠금)를 사용 설정한 경우 이 값을 사용하면 복원 키를 클라우드에 백업할 수 있습니다.
      • false: 이 값은 키를 클라우드가 아닌 로컬에 저장합니다. 사용자가 클라우드에서 복원하도록 선택하면 새 기기에서 키를 사용할 수 없습니다.

사용자 인증 정보 생성 응답 처리

Credential Manager API는 CreateRestoreCredentialResponse 유형의 응답을 반환합니다. 이 응답은 공개 키 사용자 인증 정보 등록 응답을 JSON 형식으로 보유합니다.

앱의 공개 키를 신뢰 당사자 서버로 보냅니다. 이 공개 키는 패스키를 만들 때 생성되는 공개 키와 유사합니다. 서버에서 패스키 생성을 처리하는 동일한 코드가 복원 키 생성도 처리할 수 있습니다. 서버 측 구현에 관한 자세한 내용은 the 패스키 안내를 참고하세요.

복원 키 생성 프로세스 중에 다음 예외를 처리합니다.

  • CreateRestoreCredentialDomException: 이 예외는 requestJson이 잘못되었고 PublicKeyCredentialCreationOptionsJSON의 WebAuthn 형식을 따르지 않는 경우 발생합니다.
  • E2eeUnavailableException: 이 예외는 isCloudBackupEnabled가 true이지만 사용자 기기에 데이터 백업 또는 엔드 투 엔드 암호화(예: 화면 잠금)가 없는 경우 발생합니다.
    모든 경우에 사용자 인증 정보 복원이 생성되도록 하려면 isCloudBackupEnabled를 true로 설정하여 createCredential을 호출하여 E2eeUnavailableException을 명시적으로 처리해야 합니다. E2eeUnavailableException이 발생하면 isCloudBackupEnabled를 false로 설정하여 createCredential을 다시 포착하고 호출합니다.
  • IllegalArgumentException: 이 예외는 createRestoreRequest 가 비어 있거나 유효한 JSON이 아니거나 WebAuthn 사양을 준수하는 유효한 user.id가 없는 경우 발생합니다.

복원 키로 로그인

기기 설정 프로세스 중에 사용자 인증 정보 복원을 사용하여 사용자를 자동으로 로그인 처리합니다.

앱 서버에서 사용자 인증 정보 검색 옵션 가져오기

서버에서 복원 키를 가져오는 데 필요한 옵션을 클라이언트 앱에 보냅니다. 이 단계와 유사한 패스키 안내는 패스키로 로그인하기를 참고하세요. 서버 측 구현에 관한 자세한 내용은 서버 측 인증 가이드를 참고하세요.

복원 키 가져오기

새 기기에서 복원 키를 가져오려면 CredentialManager 객체에서 getCredential() 메서드를 호출합니다.

다음 두 시나리오 모두에서 복원 키를 가져오는 것이 좋습니다.

  • 기기에서 앱을 처음 실행할 때. 이 시나리오의 사용자 인증 정보 복원은 앱 데이터 복원과 독립적입니다.
  • 앱 데이터 백업 및 복원이 사용 설정된 경우 앱 데이터가 복원된 직후 복원 키를 가져옵니다. BackupAgent를 사용하여 앱의 백업을 구성하고 getCredential 기능을 onRestoreFinished 콜백 내에서 완료해야 합니다. onRestore 메서드는 키-값 백업에만 호출되는 반면 onRestoreFinished는 모든 종류의 백업 복원에 안정적으로 호출되므로 이 메서드를 사용하지 마세요. 이렇게 하면 사용자가 새 기기를 처음 열 때 발생할 수 있는 지연을 방지하고 사용자가 앱을 열 때까지 기다리지 않고도 앱과 상호작용할 수 있습니다. 예를 들어 이렇게 하면 사용자가 새 기기에서 앱을 처음 열기 전에 앱에서 사용자 알림을 보낼 수 있습니다. 이는 특히 메시지 또는 커뮤니케이션 앱과 관련이 있습니다.
// Fetch the options required to get the restore key
val authenticationJson = fetchAuthenticationJson()

// Create the GetRestoreCredentialRequest object
val options = GetRestoreCredentialOption(authenticationJson)
val getRequest = GetCredentialRequest(listOf(options))

val response = credentialManager.getCredential(context, getRequest)

// Type-check and extract the restore credential
val credential = response.credential as RestoreCredential

인증 관리자 API는 GetCredentialResponse 유형의 응답을 반환합니다. 이 응답에 포함된 사용자 인증 정보는 공개 키를 보유하는 RestoreCredential 유형입니다.

로그인 응답 처리

앱의 공개 키를 신뢰 당사자 서버로 보냅니다. 그러면 이 공개 키를 사용하여 사용자를 로그인 처리할 수 있습니다. 서버 측에서 이 작업은 패스키를 사용하여 로그인하는 것과 유사합니다. 서버에서 패스키로 로그인을 처리하는 동일한 코드가 복원 키로 로그인도 처리할 수 있습니다. 패스키의 서버 측 구현에 관한 자세한 내용은 패스키로 로그인하기를 참고하세요.

복원 키 삭제

인증 관리자는 상태 비저장이며 사용자 활동을 인식하지 못하므로 사용 후 복원 키를 자동으로 삭제하지 않습니다. 복원 키를 삭제하려면 clearCredentialState() 메서드를 호출합니다. 보안을 위해 사용자가 로그아웃할 때마다 키를 삭제합니다. 이렇게 하면 사용자가 동일한 기기에서 다음에 앱을 열 때 사용자가 로그아웃되고 다시 로그인하라는 메시지가 표시됩니다.

앱 제거는 사용자가 로그아웃할 때의 의도와 마찬가지로 기기에서 상응하는 복원 키를 삭제하려는 의도로 해석됩니다.

복원 키는 다음 경우에만 삭제됩니다.

  • 시스템 수준 작업: 사용자가 앱을 제거하거나 데이터를 지웁니다.
  • 앱 수준 호출: 앱 코드에서 사용자 로그아웃을 처리할 때 clearCredentialState()를 호출하여 프로그래매틱 방식으로 키를 삭제합니다.

사용자가 앱에서 로그아웃하면 CredentialManager 객체에서 clearCredentialState() 메서드를 호출합니다.

// Create a ClearCredentialStateRequest object
val clearRequest = ClearCredentialStateRequest(TYPE_CLEAR_RESTORE_CREDENTIAL)

// When the user logs out, delete the restore key
val response = credentialManager.clearCredentialState(clearRequest)