네이티브 인증을 사용하여 Android 앱에서 로그인 추가 - Microsoft identity platform

아티클
2025-03-05

적용: 회색 X 기호가 있는 흰색 원. 워크포스 사용자 흰색 확인 표시 기호가 있는 녹색 원. 외부 사용자(더 알아보기)

이 자습서에서는 네이티브 인증을 사용하여 Android 모바일 앱에서 전자 메일 일회용 암호 또는 사용자 이름 및 암호를 사용하여 사용자를 로그인하고 로그아웃하는 방법을 보여 줍니다.

이 자습서에서는 다음을 수행합니다.

전자 메일 일회용 암호 또는 사용자 이름(전자 메일) 및 암호를 사용하여 사용자를 로그인합니다.
사용자를 로그아웃합니다.
로그인 오류 처리

필수 구성 요소

자습서: Android 앱을 네이티브 인증을 위해 준비하라의 단계를 완료하세요. 이 자습서에서는 네이티브 인증을 위해 Android 프로젝트 또는 앱을 준비하는 방법을 보여 줍니다.

일회성 암호를 사용하여 사용자를 로그인하려면 전자 메일을 수집하고 사용자가 전자 메일을 확인할 수 있도록 일회성 암호가 포함된 전자 메일을 보냅니다. 사용자가 유효한 일회용 암호를 입력하면 앱이 로그인합니다.

사용자 이름(전자 메일) 및 암호를 사용하여 사용자를 로그인하려면 사용자로부터 전자 메일 및 암호를 수집합니다. 사용자 이름과 암호가 유효한 경우 앱은 사용자를 로그인합니다.

사용자를 로그인하려면 다음을 수행해야 합니다.

UI(사용자 인터페이스)를 만들어 다음을 수행합니다.
- 사용자로부터 전자 메일을 수집합니다. 입력에 유효성 검사를 추가하여 사용자가 유효한 전자 메일 주소를 입력하는지 확인합니다.
- 사용자 이름(이메일) 및 암호를 사용하여 로그인하는 경우 암호를 수집합니다.
- 전자 메일 일회용 암호로 로그인하는 경우 사용자로부터 전자 메일 일회용 암호를 수집합니다.
- 전자 메일 일회용 암호로 로그인하는 경우 일회성 암호를 다시 보냅니다(권장).

UI에서 다음 코드 조각과 같이 선택 이벤트가 로그인을 시작하는 단추를 추가합니다.

 CoroutineScope(Dispatchers.Main).launch {
     val parameters = NativeAuthSignInParameters(username = email)
     // Assign 'password' param if you sign in with username (email) and password
     // parameters.password = password
     val actionResult: SignInResult = authClient.signIn(parameters)

     if (actionResult is SignInResult.CodeRequired) {
         val nextState = actionResult.nextState
         val submitCodeActionResult = nextState.submitCode(
             code = code
         )
         if (submitCodeActionResult is SignInResult.Complete) {
             // Handle sign in success
             val accountState = submitCodeActionResult.resultValue

             val getAccessTokenParameters = NativeAuthGetAccessTokenParameters()
             val accessTokenResult = accountState.getAccessToken(getAccessTokenParameters)

             if (accessTokenResult is GetAccessTokenResult.Complete) {
                 val accessToken = accessTokenResult.resultValue.accessToken
                 val idToken = accountState.getIdToken()
             }
         }
     }
 }

사용자가 전자 메일 및 암호로 로그인하는 위치와 같이 암호를 제출할 필요가 없는 경우 다음 코드 조각을 사용합니다.

CoroutineScope(Dispatchers.Main).launch {
    val parameters = NativeAuthSignInParameters(username = email)
    parameters.password = password
    val actionResult: SignInResult = authClient.signIn(parameters)

    if (actionResult is SignInResult.Complete) -> {
        // Handle sign in success
        val accountState = actionResult.resultValue

        val getAccessTokenParameters = NativeAuthGetAccessTokenParameters()
        val accessTokenResult = accountState.getAccessToken(getAccessTokenParameters)

        if (accessTokenResult is GetAccessTokenResult.Complete) {
            val accessToken = accessTokenResult.resultValue.accessToken
            val idToken = accountState.getIdToken()
        }
    }
}

로그인 흐름을 시작하려면 SDK의 signIn(parameters) 메서드를 사용합니다.
사용자로부터 수집한 전자 메일 주소인 NativeAuthSignInParameters 포함하는 username 클래스의 인스턴스입니다.
로그인 메서드가 사용자 이름(전자 메일) 및 암호인 경우 메서드의 매개 변수인 password 사용자로부터 수집한 암호입니다.
가장 일반적인 시나리오에서 signIn(parameters)SignInResult.CodeRequired결과를 반환합니다. 즉, SDK는 앱이 사용자의 이메일 주소로 전송된 전자 메일 일회용 암호를 제출할 것으로 예상합니다.
SignInResult.CodeRequired 개체에는 actionResult.nextState통해 검색할 수 있는 새 상태 참조가 포함되어 있습니다.
새 상태는 두 가지 새로운 메서드에 대한 액세스 권한을 제공합니다.
- submitCode() 앱이 사용자로부터 수집하는 이메일 일회용 암호를 제출합니다.
- resendCode() 사용자가 코드를 받지 못하면 전자 메일 일회용 암호를 다시 보냅니다.

로그인하는 동안 모든 작업이 성공하는 것은 아닙니다. 예를 들어 사용자가 존재하지 않는 전자 메일 주소로 로그인하거나 잘못된 코드를 제출하려고 할 수 있습니다.

signIn(parameters) 메서드에서 오류를 처리하려면 다음 코드 조각을 사용합니다.

 val parameters = NativeAuthSignInParameters(username = email)
 // Assign 'password' param if you sign in with username (email) and password
 // parameters.password = password
val actionResult: SignInResult = authClient.signIn(parameters)

if (actionResult is SignInResult.CodeRequired) {
    // Next step: submit code
} else if (actionResult is SignInError) {
    // Handle sign in errors
    when {
         actionResult.isUserNotFound() -> {
             // Handle "user not found" error
         }
         actionResult.isAuthNotSupported() -> {
             // Handle "authentication type not support" error
         }
         actionResult.isInvalidCredentials() -> {
             // Handle specific errors
         }
         else -> {
             // Handle other errors
         }
     }
}

SignInError signIn(parameters)반환된 실패한 작업 결과를 나타내므로 작업 결과에 새 상태에 대한 참조가 포함되지 않습니다.
actionResult is SignUpError경우 Android SDK는 특정 오류를 추가로 분석할 수 있는 유틸리티 메서드를 제공합니다.
- 이 메서드는 isUserNotFound() 사용자가 존재하지 않는 사용자 이름(전자 메일 주소)으로 로그인하는지 여부를 확인합니다.
- 이 메서드는 isBrowserRequired() 인증 흐름을 완료하기 위해 브라우저(웹 대체)가 필요한지 확인합니다. 이 시나리오는 네이티브 인증이 인증 흐름을 완료하기에 충분하지 않은 경우에 발생합니다. 예를 들어 관리자는 전자 메일 및 암호를 인증 방법으로 구성하지만 앱은 암호 챌린지 유형으로 보내지 못하거나 단순히 지원하지 않습니다. Android 앱에서 지원 웹 폴백의 단계를 사용하여 그런 상황이 발생할 때 시나리오를 처리합니다.
- 이 메서드 isAuthNotSupported()는 앱이 Microsoft Entra에서 지원하지 않는 도전 형식을 보내는지, 즉 oob 및 암호이외의 도전 형식 값인지 확인합니다. 챌린지 유형에 대해 자세히 알아봅니다.
- 사용자 이름(이메일) 및 암호 로그인의 경우 메서드는 isInvalidCredentials() 사용자 이름과 암호의 조합이 잘못된지 여부를 확인합니다.

코드 제출 오류 처리

submitCode() 메서드에서 오류를 처리하려면 다음 코드 조각을 사용합니다.

val submitCodeActionResult = nextState.submitCode(
    code = code
)
if (submitCodeActionResult is SignInResult.Complete) {
    // Sign in flow complete, handle success state.
} else if (submitCodeActionResult is SubmitCodeError && submitCodeActionResult.isInvalidCode()) {
    // Handle "invalid code" error
}

SubmitCodeError 오류는 submitCode() 반환된 실패한 작업 결과를 나타내므로 작업 결과에 새 상태에 대한 참조가 포함되지 않습니다.
isInvalidCode() 특정 오류를 확인합니다. 이 경우 이전 상태 참조를 사용하여 작업을 다시 생성해야 합니다.

새 전자 메일 일회용 암호를 검색하려면 다음 코드 조각을 사용합니다.

val submitCodeActionResult = nextState.submitCode(
    code = code
)
if (submitCodeActionResult is SignInError && submitCodeActionResult.isInvalidCode) {
    // Inform the user that the submitted code was incorrect or invalid, then ask them to input a new email one-time passcode
    val newCode = retrieveNewCode()
    nextState.submitCode(
        code = newCode
    )
}

앱에서 사용자를 성공적으로 로그인하는 데 필요한 모든 단계를 완료했습니다. 애플리케이션을 빌드하고 실행합니다. 모두 좋은 경우 전자 메일을 제공하고, 전자 메일에 코드를 수신하고, 이를 사용하여 사용자를 성공적으로 로그인할 수 있어야 합니다.

ID 토큰 클레임 읽기

앱이 ID 토큰을 획득하면 현재 계정과 연결된 클레임을 검색할 수 있습니다. 이렇게 하려면 다음 코드 조각을 사용합니다.

val preferredUsername = accountState.getClaims()?.get("preferred_username")
val city = accountState.getClaims()?.get("City")
val givenName = accountState.getClaims()?.get("given_name")
//custom attribute
val loyaltyNumber = accountState.getClaims()?.get("loyaltyNumber")

클레임 값에 액세스하는 데 사용하는 키는 사용자 특성을 토큰 클레임으로 추가할 때 지정하는 이름입니다.

토큰 클레임에 사용자 특성 추가 문서에서 토큰 클레임으로 기본 제공 및 사용자 지정 특성을 추가하는 방법을 알아봅니다.

사용자 로그아웃

사용자를 로그아웃하려면 현재 캐시에 저장된 계정을 제거해야 합니다.

다음을 포함하는 사용자 지정 UI(사용자 인터페이스)를 만듭니다.
- 사용자가 로그아웃 요청을 보내기 위해 선택하는 로그아웃 단추입니다.

사용자를 로그아웃하려면 다음 코드를 사용합니다.

private fun performSignOut(accountState: AccountState) {
     CoroutineScope(Dispatchers.Main).launch {
         val accountResult = authClient.getCurrentAccount()
         if (accountResult is GetAccountResult.AccountFound) {
             val signOutResult = accountResult.resultValue.signOut()
             if (signOutResult is SignOutResult.Complete) {
                 // Show sign out successful UI
             }
         }
     }
 }

로그아웃 오류 처리

로그아웃은 오류가 없어야 합니다. 오류가 발생하면 다음 코드 조각을 사용하여 오류 결과를 검사합니다.

val actionResult = accountResult.signOut()
if (actionResult is SignOutResult.Complete) {
    // Show sign out successful UI
} else {
    // Handle errors
}

import 문을 반드시 포함하시기 바랍니다. Android Studio가 자동으로 가져오기 문을 포함할 것입니다.

앱에서 사용자를 성공적으로 로그아웃하는 데 필요한 모든 단계를 완료했습니다. 애플리케이션을 빌드하고 실행합니다. 모두 좋은 경우 로그아웃 단추를 선택하여 성공적으로 로그아웃할 수 있어야 합니다.

사용자 지정 클레임 공급자 구성

외부 시스템의 클레임을 앱에 발급된 토큰에 추가하려면 사용자 지정 클레임 공급자사용합니다. 사용자 지정 클레임 공급자는 외부 REST API를 호출하여 외부 시스템에서 클레임을 가져오는 사용자 지정 인증 확장으로 구성됩니다.

사용자 지정 클레임 공급자 구성의 단계에 따라 외부 시스템의 클레임을 보안 토큰에 추가합니다.

다음을 통해 공유

자습서: 네이티브 인증을 사용하여 Android 앱에서 로그인 추가

필수 구성 요소

사용자 로그인

로그인 오류 처리

로그인 시작 오류 처리

코드 제출 오류 처리

ID 토큰 클레임 읽기

사용자 로그아웃

로그아웃 오류 처리

사용자 지정 클레임 공급자 구성

관련 콘텐츠

피드백

추가 리소스