자습서: 네이티브 인증을 사용하여 Android 모바일 앱에 등록 추가

적용 대상: 외부 테넌트에 다음 내용이 적용되었음을 나타내는 흰색 확인 표시 기호가 있는 녹색 원입니다. 외부 테넌트(자세한 정보)

이 자습서에서는 네이티브 인증을 사용하여 Android 모바일 앱에서 전자 메일 일회용 암호 또는 사용자 이름(이메일) 및 암호를 사용하여 사용자를 등록하는 방법을 보여 줍니다. 등록하는 동안 사용자 이름(별칭)을 포함하여 사용자 특성을 수집하고 오류를 처리하는 방법도 알아봅니다.

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

  • 전자 메일 일회용 암호 또는 사용자 이름(전자 메일) 및 암호를 사용하여 사용자를 등록합니다.
  • 등록하는 동안 사용자 이름(별칭)을 포함하여 사용자 특성을 수집합니다.
  • 등록 오류를 처리합니다.

필수 구성 요소

  • 자습서: Android 앱을 네이티브 인증을 위해 준비하라의 단계를 완료하세요.
  • 등록하는 동안 사용자 특성을 수집하려면, 등록 및 로그인 사용자 흐름을 생성할 때사용자 특성을 구성합니다.
  • 등록하는 동안 사용자 이름(별칭)을 수집하려면 테넌트의 등록 사용자 흐름에서 Username 기본 제공 사용자 특성을 사용하도록 설정합니다.

사용자 등록

전자 메일 일회용 암호 또는 사용자 이름(전자 메일) 및 암호를 사용하여 사용자를 등록하려면 사용자로부터 전자 메일을 수집한 다음 전자 메일 일회용 암호가 포함된 전자 메일을 사용자에게 보냅니다. 사용자가 유효한 전자 메일 일회용 암호를 입력하여 사용자 이름의 유효성을 검사합니다.

사용자를 등록하려면 다음을 수행해야 합니다.

  1. UI(사용자 인터페이스)를 만들어 다음을 수행합니다.

    • 사용자로부터 전자 메일을 수집합니다. 입력에 유효성 검사를 추가하여 사용자가 유효한 전자 메일 주소를 입력하는지 확인합니다.
    • 사용자 이름(전자 메일) 및 암호를 사용하여 등록하는 경우 암호를 수집합니다.
    • 앱에서 별칭 기반 로그인을 지원하는 경우 사용자 이름(별칭)을 수집합니다.
    • 사용자로부터 전자 메일 일회용 암호를 수집합니다.
    • 필요한 경우 사용자 특성을 수집합니다.
    • 일회성 암호를 다시 보냅니다(권장).
    • 등록 흐름을 시작합니다.

  2. 앱에서 선택 이벤트가 다음 코드 조각을 트리거하는 단추를 추가합니다.

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

     if (actionResult is SignUpResult.CodeRequired) {
         val nextState = actionResult.nextState
         val submitCodeActionResult = nextState.submitCode(
            code = code
         )
         if (submitCodeActionResult is SignUpResult.Complete) {
            // Handle sign up success
         }
    }
}
    • SDK의 인스턴스 메서드 signUp(parameters) 사용하여 등록 흐름을 시작합니다.
    • 사용자 이름(전자 메일 주소) 및 암호를 사용하여 등록하려면 NativeAuthSignUpParameters 클래스의 인스턴스를 만들고 사용자 이름과 암호를 할당합니다.
    • username등록 매개 변수는 사용자로부터 수집한 이메일 주소입니다.
    • 가장 일반적인 시나리오 signUp(parameters) 에서 SDK는 앱이 사용자의 전자 메일 주소로 전송된 전자 메일 일회용 암호를 제출할 것으로 예상한다는 결과를 SignUpResult.CodeRequired반환합니다.
    • 개체에는 SignUpResult.CodeRequired를 통해 검색할 수 있는 새 상태 참조가 포함되어 있습니다.
    • 새 상태는 두 가지 새 메서드에 대한 액세스를 제공합니다.
      • submitCode() 앱이 사용자로부터 수집하는 이메일 일회용 암호를 제출합니다.
      • resendCode() 사용자가 코드를 받지 못하면 전자 메일 일회용 암호를 다시 보냅니다.
    • submitCode() 흐름이 완료되고 사용자가 등록되었음을 나타내는 SignUpResult.Complete반환합니다.
    • signUp(parameters) 오류가 발생했음을 나타내는 SignUpError 반환할 수도 있습니다.

등록하는 동안 사용자 특성 수집

전자 메일 일회용 암호 또는 사용자 이름(전자 메일) 및 암호를 사용하여 사용자를 등록하든 사용자의 계정을 만들기 전에 사용자 특성을 수집할 수 있습니다.

  • NativeAuthSignUpParameters 인스턴스는 attributes 매개 변수를 허용합니다.

        CoroutineScope(Dispatchers.Main).launch {
        val parameters = NativeAuthSignUpParameters(username = email)
        // Assign 'password' param if you sign in with username (email) and password
        // parameters.password = password
        parameters.attributes = userAttributes
        val actionResult: SignUpResult = authClient.signUp(parameters)
        //...
    }

  • Android SDK는 사용자 특성을 만드는 데 사용하는 유틸리티 클래스 UserAttribute.Builder 제공합니다. 예를 들어 도시 및 국가 사용자 특성을 제출하려면 다음 코드 조각을 사용하여 userAttributes 변수를 빌드합니다.

         val userAttributes = UserAttributes.Builder ()
    .country(country) 
    .city(city) 
    .build()

    UserAttribute.Builder 클래스의 메서드 이름은 빌드하는 사용자 특성의 프로그래밍 가능한 이름과 동일합니다. Android SDK 특성 작성기 대해 자세히 알아봅니다.

  • signUp(parameters) 메서드는 Microsoft Entra에서 계정을 만들기 전에 앱이 하나 이상의 필수 특성을 제출해야 함을 나타내는 SignUpResult.AttributesRequired 반환할 수 있습니다. 이러한 특성은 관리자가 Microsoft Entra 관리 센터에서 필수로 구성합니다. Microsoft Entra는 선택적 사용자 특성을 명시적으로 요청하지 않습니다.

  • SignUpResult.AttributesRequired 결과에는 requiredAttributes 매개 변수가 포함됩니다. requiredAttributes 앱이 제출해야 하는 사용자 특성에 대한 세부 정보를 포함하는 RequiredUserAttribute 개체 목록입니다. actionResult is SignUpResult.AttributesRequired처리하려면 다음 코드 조각을 사용합니다.

    val parameters = NativeAuthSignUpParameters(username = email)
// Assign 'password' param if you sign in with username (email) and password
// parameters.password = password
parameters.attributes = userAttributes
val actionResult: SignUpResult = authClient.signUp(parameters)

if (actionResult is SignUpResult.AttributesRequired) {
        val requiredAttributes = actionResult.requiredAttributes 
        // Handle "attributes required" result 
        val nextState = actionResult.nextState
        nextState.submitAttributes(
            attributes = moreAttributes
        )
}

등록하는 동안 사용자 이름(별칭) 수집

사용자 이름(별칭)은 특수한 사용자 특성입니다. 도시 또는 국가와 같은 다른 특성과 마찬가지로 등록하는 동안 수집합니다. 이러한 특성과 달리 사용자는 나중에 별칭을 사용하여 로그인할 수 있습니다. 별칭(예: "johndoe")은 사용자에게 전자 메일 주소보다 더 짧고 친숙한 로그인 방법을 제공합니다.

사용자 이름(별칭)은 사용자 이름(이메일)을 대체하지 않습니다. 등록하는 동안 앱은 항상 사용자 이름(이메일)을 기본 식별자로 수집해야 하며, 이메일과 함께 별칭을 특성으로 수집합니다. 로그인 시 사용자는 사용자 이름(이메일) 또는 사용자 이름(별칭)으로 로그인하도록 선택할 수 있습니다.

가입 사용자 흐름에서 Username 기본 제공 사용자 특성이 활성화되면, SDK는 다른 특성에 사용되는 동일한 UserAttributes 작성기를 통해 flatUsername() 메서드를 사용하여 이를 전달받습니다. 사용자가 별도의 특성 필수 단계를 거치지 않아도 되도록 등록 호출에서 직접 사용자 이름(별칭)을 전달할 수 있습니다.

사용자 이름(별칭)을 수집하려면 전자 메일 필드와 함께 등록 UI에서 사용자 이름에 대한 입력 필드를 추가한 다음 등록 호출에서 별칭을 특성으로 전달합니다.

val email = binding.emailText.text.toString()
val password = binding.passwordText.text.toString()
val username = binding.usernameText.text.toString()

val attributes = UserAttributes.Builder()
    .flatUsername(username)
    .build()

CoroutineScope(Dispatchers.Main).launch {
    val actionResult = authClient.signUpUsingPassword(
        username = email,
        password = password,
        attributes = attributes
    )

    when (actionResult) {
        is SignUpResult.CodeRequired -> {
            // Navigate to code verification
            navigateToCodeVerification(actionResult.nextState)
        }
        is SignUpUsingPasswordError -> {
            handleSignUpError(actionResult)
        }
    }
}

이메일 일회용 패스코드 흐름(비밀번호 없이)의 경우 signUpUsingPassword 대신 signUp를 사용합니다:

val actionResult = authClient.signUp(
    username = email,
    attributes = attributes
)

등록 오류 처리

등록하는 동안 모든 작업이 성공하는 것은 아닙니다. 예를 들어 사용자가 이미 사용한 전자 메일 주소로 등록하거나 잘못된 전자 메일 일회용 암호를 제출하려고 할 수 있습니다.

시작 등록 오류 처리

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

 val parameters = NativeAuthSignUpParameters(username = email)
 // Assign 'password' param if you sign in with username (email) and password
 // parameters.password = password
val actionResult: SignUpResult = authClient.signUp(parameters)

if (actionResult is SignUpResult.CodeRequired) {
    // Next step: submit code
} else if (actionResult is SignUpError) {
     when {
         actionResult.isUserAlreadyExists() -> {
             // Handle "user already exists" error
         }
         else -> {
             // Handle other errors
         }
     }
}

  • signUp(parameters) SignUpError반환할 수 있습니다.

  • SignUpError signUp() 반환된 실패한 작업 결과를 나타내며 새 상태에 대한 참조를 포함하지 않습니다.

  • 경우 actionResult is SignUpErrorMSAL(Microsoft 인증 라이브러리) Android SDK는 특정 오류를 추가로 분석하는 유틸리티 메서드를 제공합니다.

    • 이 메서드 isUserAlreadyExists() 는 사용자 이름 또는 별칭이 계정을 만드는 데 이미 사용되었는지 여부를 확인합니다.
    • isInvalidAttributes() 앱이 제출한 하나 이상의 특성이 잘못된 데이터 형식과 같은 유효성 검사에 실패했는지 여부를 확인합니다. 여기에는 앱이 invalidAttributes 제출했지만 유효성 검사에 실패한 모든 특성의 목록인 매개 변수가 포함되어 있습니다.
    • isInvalidPassword() 암호가 모든 암호 복잡성 요구 사항을 충족하지 않는 경우와 같이 암호가 잘못된지 여부를 확인합니다. Microsoft Entra의 암호 정책 대해 자세히 알아보기
    • isInvalidUsername() 사용자 전자 메일이 잘못된 경우와 같이 사용자 이름이 잘못된지 여부를 확인합니다.
    • isBrowserRequired() 는 인증 흐름을 완료하는 데 브라우저(웹 대체)가 필요한지 여부를 확인합니다. 이 시나리오는 네이티브 인증이 인증 흐름을 완료하기에 충분하지 않은 경우에 발생합니다. 예를 들어 관리자는 전자 메일 및 암호를 인증 방법으로 구성하지만 앱은 암호를 챌린지 유형으로 보내지 못하거나 지원하지 않습니다. Android 앱에서 웹 대체 처리 지원의 단계를 따라 이 시나리오를 처리하세요.
    • isAuthNotSupported() 앱이 Microsoft Entra에서 지원하지 않는 챌린지 형식을 보내는지, 즉 oob 또는 암호 이외의 챌린지 형식 값인지 확인합니다. 챌린지 유형에 대해 자세히 알아봅니다.

    앱의 UI에서 친숙한 메시지를 사용하여 전자 메일이 이미 사용 중이거나 일부 특성이 잘못되었음을 사용자에게 알립니다.

  • 잘못된 특성의 오류를 처리하려면 다음 코드 조각을 사용합니다.

    val parameters = NativeAuthSignUpParameters(username = email)
// Assign 'password' param if you sign in with username (email) and password
// parameters.password = password
parameters.attributes = userAttributes
val actionResult: SignUpResult = authClient.signUp(parameters)

if (actionResult is SignUpError && actionResult.isInvalidAttributes()) {
    val invalidAttributes = actionResult.invalidAttributes

    // Handle "invalid attributes" error, this time submit valid attributes
    val parameters = NativeAuthSignUpParameters(username = email)
    // Assign 'password' param if you sign in with username (email) and password
    // parameters.password = password
    parameters.attributes = userAttributes
    authClient.signUp(parameters)
} 
//...

이메일 일회성 암호 제출 오류 처리

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

val submitCodeActionResult = nextState.submitCode(
    code = code
)
if (submitCodeActionResult is SignUpResult.Complete) {
    // Sign up flow complete, handle success state.
} else if (submitCodeActionResult is SubmitCodeError) {
    // Handle errors under SubmitCodeError
     when {
         submitCodeActionResult.isInvalidCode() -> {
             // Handle "code invalid" error
         }
         else -> {
             // Handle other errors
         }
     }
}

  • submitCode() SubmitCodeError반환할 수 있습니다.

  • isInvalidCode() 메서드를 사용하여 제출된 코드가 유효하지 않은 것과 같은 특정 오류를 확인합니다. 이 경우 이전 상태 참조를 사용하여 작업을 다시 생성해야 합니다.

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

    val submitCodeActionResult = nextState.submitCode(
    code = code
)
if (submitCodeActionResult is SubmitCodeError && submitCodeActionResult.isInvalidCode()) {
    // Inform the user that the submitted code was incorrect or invalid and ask for a new code to be supplied
    val newCode = retrieveNewCode()
    nextState.submitCode(
        code = newCode
    )
}

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

앱에서 사용자를 등록하는 데 필요한 모든 단계를 완료했습니다. 애플리케이션을 빌드하고 실행합니다. 모든 항목이 올바르게 구성된 경우 전자 메일 일회용 암호 또는 전자 메일 및 암호를 사용하여 사용자를 등록하고 사용자 이름(별칭)을 포함한 사용자 특성을 수집할 수 있어야 합니다.

선택 사항: 등록 흐름 후 로그인

성공적인 등록 흐름 후에는 로그인 흐름을 시작하지 않고도 사용자를 로그인할 수 있습니다. 사용자가 사용자 이름(별칭)으로 등록한 경우 전자 메일 주소 또는 별칭을 사용하여 로그인할 수 있습니다. Android 문서의 자습서를 통해 가입 후 사용자 로그인을 더 자세히 알아보세요.

다음 단계

자습서: Android 앱에서 이메일 일회용 암호를 사용하여 로그인 및 로그아웃 기능 추가하기.

  • Last updated on