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

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

버전 호환성

Credential Manager의 Restore Credentials는 Android 9 이상, Google Play 서비스 (GMS) 코어 버전 24220000 이상, androidx.credentials 라이브러리 버전 1.5.0 이상을 실행하는 기기에서 작동합니다.

기본 요건

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

참고: 서버 측 구현은 패스키와 복구 키가 동일하지만 클라이언트 측 앱은 패스키를 지원하지 않고 복구 키를 지원할 수 있습니다. 복구 키는 앱의 인증 방법(예: 비밀번호 또는 Google로 로그인)과 독립적으로 작동하므로 앱 코드의 기존 인증 방법을 추가로 변경하지 않아도 됩니다.

종속 항목

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

Kotlin

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

Groovy

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

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

참고: 사용자 인증 정보 복원 기능은 manifest에 allowBackup가 설정되어 있는지와 관계없이 작동합니다.

개요

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

복원 키 만들기

사용자가 앱을 인증한 후 복원 키를 만듭니다. 로그인 직후 또는 이미 로그인한 경우 후속 앱 실행 중에 만듭니다.

참고: 복원 키는 애플리케이션의 고유한 패키지 이름과 연결됩니다. 조직의 기본 앱과 하위 앱의 패키지 이름이 다른 경우 앱마다 별도의 복원 키를 만드세요.

인증 관리자 인스턴스화

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

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

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

앱 서버에서 FIDO 규격 라이브러리를 사용하여 복구 사용자 인증 정보를 만드는 데 필요한 정보(예: 사용자, 앱, 추가 구성 속성에 관한 정보)를 클라이언트 앱에 전송합니다. 서버 측 구현에 관한 자세한 내용은 서버 측 안내를 참고하세요.

복원 키 만들기

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

val credentialManager = CredentialManager.create(context)

// On a successful authentication create a Restore Key
// Pass in the context and CreateRestoreCredentialRequest object
val response = credentialManager.createCredential(context, createRestoreRequest)

코드에 관한 핵심 사항

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

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

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

    • true: (권장) 이 값은 사용자가 Google 백업 및 화면 잠금과 같은 엔드 투 엔드 암호화를 사용 설정한 경우 복구 키를 클라우드에 백업할 수 있도록 합니다.
    • false: 이 값은 클라우드가 아닌 로컬에 키를 저장합니다. 사용자가 클라우드에서 복원하도록 선택하면 새 기기에서 키를 사용할 수 없습니다.
  주의: isCloudBackupEnabled를 true로 설정하는 것이 좋습니다. 클라우드 백업이 사용 중지되어 있고 사용자가 클라우드 백업에서 복원하는 경우 복원 키를 가져오는 호출이 실패합니다. 클라우드 백업으로 앱을 복원하는 사용자는 복원 키를 받지 못하며 자동으로 로그인되지 않습니다.

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

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

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

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

• CreateRestoreCredentialDomException: 이 예외는 requestJson이 유효하지 않고 PublicKeyCredentialCreationOptionsJSON의 WebAuthn 형식을 따르지 않는 경우 발생합니다.
• E2eeUnavailableException: 이 예외는 isCloudBackupEnabled이 true이지만 사용자의 기기에 화면 잠금과 같은 데이터 백업이나 엔드 투 엔드 암호화가 없는 경우 발생합니다.
• IllegalArgumentException: 이 예외는 createRestoreRequest이 비어 있거나 유효한 JSON이 아니거나 WebAuthn 사양을 준수하는 유효한 user.id이 없는 경우 발생합니다.

복구 키로 로그인하기

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

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

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

복원 키 가져오기

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

다음 시나리오에서 복원 키를 가져올 수 있습니다.

• (권장) 앱 데이터가 복원된 직후 BackupAgent를 사용하여 앱의 백업을 구성하고 onRestore 콜백 내에서 getCredential 기능을 완료하여 앱 데이터가 복원된 직후 앱의 사용자 인증 정보가 복원되도록 합니다. 이렇게 하면 사용자가 새 기기를 처음 열 때 발생할 수 있는 지연을 방지하고 사용자가 앱이 열릴 때까지 기다리지 않고도 상호작용할 수 있습니다.
• 기기에서 앱을 처음 실행할 때

사용자가 새 기기에서 앱을 처음 열기 전에 사용자에게 알림을 보내려면 BackupAgent의 onRestore 콜백 내에서 복원 키를 가져옵니다. 이는 특히 메시지 또는 커뮤니케이션 앱과 관련이 있습니다.

// Fetch the Authentication JSON from server
val authenticationJson = fetchAuthenticationJson()

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

// The restore key can be fetched in two scenarios to
// 1. On the first launch of app on the device, fetch the Restore Key
// 2. In the onRestore callback (if the app implements the Backup Agent)
val response = credentialManager.getCredential(context, getRequest)

사용자 인증 정보 관리자 API는 GetCredentialResponse 유형의 응답을 반환합니다. 이 응답은 공개 키를 보유합니다.

로그인 응답 처리

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

참고: 복구 키와 패스키는 동일한 기본 서버 구현을 사용하지만 앱 서버의 데이터베이스에 저장할 때는 구분하세요. 이 구분은 패스키 관리 페이지가 있는 경우에 중요합니다. 사용자가 직접 생성한 패스키는 사용자가 직접 관리할 수 있지만 복구 키는 시스템에서 관리하며 패스키 관리 페이지에서 숨겨져 있기 때문입니다.

복원 키 삭제

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

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

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

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

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

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

// On user log-out, clear the restore key
val response = credentialManager.clearCredentialState(clearRequest)