기본 인증을 사용하여 Android 앱에 등록 추가 - Microsoft Entra External ID

아티클
08/01/2024

이 자습서에서는 이메일 일회용 암호 또는 사용자 이름(이메일)과 암호를 사용하여 사용자를 등록하고 기본 인증을 사용하여 Android 모바일 앱에서 사용자 특성을 수집하는 방법을 보여 줍니다.

이 자습서에서는 다음을 하는 방법을 알아볼 수 있습니다.

이메일 일회용 암호 또는 사용자 이름(이메일)과 암호를 사용하여 사용자를 등록합니다.
가입 시 사용자 특성을 수집합니다.
등록 오류를 처리합니다.

필수 조건

자습서: 기본 인증을 위한 Android 앱 준비 문서의 단계를 완료합니다.
등록 중에 사용자 특성을 수집하려면 등록 및 로그인 사용자 흐름을 만들기할 때 사용자 특성을 구성합니다.

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

사용자를 등록하려면 다음이 필요합니다.

다음을 위한 UI(사용자 인터페이스)를 만듭니다.
- 사용자로부터 메일을 수집합니다. 사용자가 유효한 이메일 주소를 입력했는지 유효성을 검사하기 위해 입력에 유효성 검사를 추가합니다.
- 사용자 이름(이메일)과 암호로 등록하는 경우 암호를 수집합니다.
- 사용자로부터 이메일 일회용 암호를 수집합니다.
- 필요한 경우 사용자 특성을 수집합니다.
- 일회용 암호를 다시 보냅니다(권장).
- 등록 절차를 시작합니다.
앱에서 선택 이벤트가 다음 코드 조각을 트리거하는 단추를 추가합니다.
```
CoroutineScope(Dispatchers.Main).launch {
    val actionResult = authClient.signUp(
        username = emailAddress
        //password = password, Pass 'password' param if you sign up with username (email) and password
    )
    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(username)을 사용하여 등록 흐름을 시작합니다.
  - 사용자 이름(이메일 주소)과 암호를 사용하여 등록하려면 암호 매개 변수를 signUp 함수 signUp(username, password)에 전달합니다.
- 메서드의 매개 변수 username은 사용자로부터 수집한 이메일 주소입니다.
- 가장 일반적인 시나리오에서 signUp(username) 또는 signUp(username, password)는 결과 SignUpResult.CodeRequired를 반환합니다. 이는 SDK가 앱이 사용자의 이메일 주소로 전송된 이메일 일회용 암호를 제출할 것으로 예상함을 나타냅니다.
- SignUpResult.CodeRequired 개체에는 actionResult.nextState를 통해 검색할 수 있는 새로운 상태 참조가 포함되어 있습니다.
- 새로운 상태를 통해 두 가지 새로운 메서드에 액세스할 수 있습니다.
  - submitCode()는 앱이 사용자로부터 수집하는 메일 일회용 암호를 제출합니다.
  - 사용자가 코드를 받지 못한 경우 resendCode()는 이메일 일회용 암호를 다시 보냅니다.
- submitCode()는 흐름이 완료되고 사용자가 가입되었음을 나타내는 SignUpResult.Complete를 반환합니다.
- signUp(username) 또는 signUp(username, password)는 오류가 발생했음을 나타내기 위해 SignUpError를 반환할 수도 있습니다.

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

signUp() 메서드는 attributes 매개 변수를 다음과 같이 signUp(username, attributes)로 허용합니다.

    CoroutineScope(Dispatchers.Main).launch {
        val actionResult = authClient.signUp(
            username = emailAddress,
            attributes = userAttributes
            //password = password, Pass 'password' param if you sign up with username (email) and password
        )
        //...
    }

Android SDK는 사용자 특성을 만드는 데 사용하는 유틸리티 클래스 UserAttribute.Builder를 제공합니다. 예를 들어, city 및 country 사용자 특성을 제출하려면 다음 코드 조각을 사용하여 userAttributes 변수를 빌드합니다.
```
     val userAttributes = UserAttributes.Builder ()
    .country(country) 
    .city(city) 
    .build()   
```
UserAttribute.Builder 클래스의 메서드 이름은 빌드하는 사용자 특성의 프로그래밍 가능한 이름과 동일합니다. Android SDK 특성 작성기에 대해 자세히 알아봅니다.
signUp(username, attributes) 또는 signUp(username, attributes, password) 메서드는 SignUpResult.AttributesRequired를 반환하여 Microsoft Entra가 계정을 만들기 전에 앱이 하나 이상의 필수 특성을 제출해야 함을 나타낼 수 있습니다. 이러한 특성은 관리자가 Microsoft Entra 관리 센터에서 필수로 구성합니다. Microsoft Entra는 선택적 사용자 특성을 명시적으로 요청하지 않습니다.

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

val actionResult = authClient.signUp(
    username = email,
    attributes = attributes
    //password = password, Pass 'password' param if you sign up with username (email) and password
)
if (actionResult is SignUpResult.AttributesRequired) {
        val requiredAttributes = actionResult.requiredAttributes 
        // Handle "attributes required" result 
        val nextState = actionResult.nextState
        nextState.submitAttributes(
            attributes = moreAttributes
        )
}

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

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

val actionResult = authClient.signUp(
    username = email
)
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(username, attributes) 또는 signUp(username, password, attributes)는 SignUpError를 반환할 수 있습니다.
SignUpError는 signUp()에서 반환한 실패한 작업 결과를 나타내며 새 상태에 대한 참조를 포함하지 않습니다.
actionResult is SignUpError의 경우 MSAL Android SDK는 특정 오류를 추가로 분석할 수 있는 다음과 같은 유틸리티 메서드를 제공합니다.
- isUserAlreadyExists() 메서드는 사용자 이름이 이미 계정을 만드는 데 사용되었는지 확인합니다.
- isInvalidAttributes()는 잘못된 데이터 형식과 같이 앱이 제출한 하나 이상의 특성의 유효성이 검사에 실패했는지 확인합니다. 여기에는 앱이 제출했지만 유효성 검사에 실패한 모든 특성의 목록인 invalidAttributes 매개 변수가 포함되어 있습니다.
- isInvalidPassword() 암호가 모든 암호 복잡성 요구 사항을 충족하지 않는 경우와 같이 암호가 유효하지 않은지 확인합니다. Microsoft Entra의 암호 정책에 대해 자세히 알아보기
- isInvalidUsername() 사용자 이메일이 유효하지 않은 경우와 같이 사용자 이름이 유효하지 않은지 확인합니다.
- isBrowserRequired()는 인증 흐름을 완료하기 위해 브라우저(웹 대체)가 필요한지 확인합니다. 이 시나리오는 기본 인증이 인증 흐름을 완료하는 데 충분하지 않을 때 발생합니다. 예를 들어, 관리자가 인증 방법으로 메일과 암호를 구성했지만 앱이 질문 형식으로 암호를 보내지 못하거나 이를 지원하지 않는 경우가 있습니다. 이러한 상황이 발생하면 Android 앱에서 웹 대체 지원의 단계에서 시나리오를 처리합니다.
- isAuthNotSupported()는 앱이 Microsoft Entra가 지원하지 않는 질문 형식, 즉 oob 또는 password가 아닌 질문 형식 값을 전송하는지 확인합니다. 도전 형식에 대해 자세히 알아봅니다.
앱 UI에서 친숙한 메시지를 사용하여 이메일이 이미 사용 중이거나 일부 특성이 유효하지 않음을 사용자에게 알립니다.

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

val actionResult = authClient.signUp(
    username = email,
    attributes = attributes
    //password = password, Pass 'password' param if you sign up with username (email) and password
)
if (actionResult is SignUpError && actionResult.isInvalidAttributes()) {
    val invalidAttributes = actionResult.invalidAttributes
    // Handle "invalid attributes" error, this time submit valid attributes
    authClient.signUp(
        username = emailAddress,
        attributes = resubmittedAttributes
        //password = password, Pass 'password' param if you sign up with username (email) and password
    )
} 
//...

메일 일회용 암호 제출 오류 처리

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에는 import 문이 자동으로 포함되어야 합니다.

사용자를 앱에 성공적으로 등록하는 데 필요한 모든 단계를 완료했습니다. 애플리케이션을 빌드하고 실행합니다. 모든 것이 정상이라면 이메일 일회용 암호 또는 이메일과 암호를 사용하여 사용자를 성공적으로 등록할 수 있어야 합니다.

등록 흐름이 성공적으로 완료되면 로그인 흐름을 시작하지 않고도 사용자가 로그인할 수 있습니다. 자습서: Android에 등록한 후 사용자 로그인 문서에서 자세히 알아봅니다.

다음 단계

자습서: Android 앱에 이메일 일회용 암호로 로그인 및 로그아웃을 추가합니다.

다음을 통해 공유

필수 조건

메일 일회용 암호 제출 오류 처리

다음 단계

피드백

추가 리소스

다음을 통해 공유

자습서: 기본 인증을 사용하여 Android 모바일 앱에 등록 추가

필수 조건

사용자 등록

가입 시 사용자 특성 수집

등록 오류 처리

시작 등록 오류 처리

메일 일회용 암호 제출 오류 처리

선택 사항: 등록 절차 후 로그인

다음 단계

피드백

추가 리소스