콘텐츠로 이동

비밀번호 변경

Method

ChangeUsernamePasswordAsync

유저네임 계정의 로그인 비밀번호를 바꾸려면 ChangeUsernamePasswordAsync()를 호출하세요. 유저네임 로그인 수단이 연결된 계정에서만 사용할 수 있으며, 현재 비밀번호를 함께 보내 본인 확인을 거칩니다.

비밀번호를 변경하면 Hive Axyl 인증 서버가 현재 기기를 포함한 모든 기기의 로그인 세션을 폐기합니다. 변경에 성공하면 사용자가 새 비밀번호로 다시 로그인하도록 안내하세요.

Warning

Hive Axyl SDK는 비밀번호를 해싱하지 않습니다. 사용자가 입력한 원본 비밀번호를 앱 클라이언트에서 SHA256(raw_password)로 변환한 64자 16진수 문자열로 만들어 전달하고, 평문 비밀번호는 전송하지 마세요.

1. 호출 파라미터값 준비

현재 비밀번호와 새 비밀번호를 각각 해시 문자열로 변환합니다. 새 비밀번호는 현재 비밀번호와 달라야 합니다.

using System.Security.Cryptography;
using System.Text;

// 원본 비밀번호를 SHA256 64자 16진수 문자열로 변환합니다.
static string Sha256Hex(string raw)
{
    using var sha256 = SHA256.Create();
    byte[] hash = sha256.ComputeHash(Encoding.UTF8.GetBytes(raw));
    var sb = new StringBuilder(hash.Length * 2);
    foreach (byte b in hash) sb.Append(b.ToString("x2"));
    return sb.ToString();
}

2. 비밀번호 변경

호출 파라미터

필드명 타입 필수 여부 설명
request UsernamePasswordChangeRequest Required 변경할 비밀번호 정보
context ApiCallContext Optional 호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다.

UsernamePasswordChangeRequest

필드명 타입 필수 여부 설명
CurrentPassword string Required 현재 비밀번호의 SHA256(raw_password) 값
NewPassword string Required 새 비밀번호의 SHA256(raw_password) 값입니다. 현재 비밀번호와 달라야 합니다.

호출 예시

ChangeUsernamePasswordAsync()의 반환 객체 AuthChangeUsernamePasswordResult는 성공, 기능별 결과인 Outcome, 호출을 마치지 못한 Failure로 나뉩니다. 이 메서드는 예외를 던지지 않고 모든 처리 결과를 반환 객체로 전달하므로, try/catch 대신 switch 구문으로 분기해 처리하세요.

using Hive.Axyl.Auth;
using Hive.Axyl.Core;
using UnityEngine;

IAuthService auth = HiveCore.Resolve<IAuthService>();

// rawCurrentPassword·rawNewPassword는 사용자가 입력한 원본 비밀번호입니다.
var result = await auth.ChangeUsernamePasswordAsync(new UsernamePasswordChangeRequest {
    CurrentPassword = Sha256Hex(rawCurrentPassword),
    NewPassword     = Sha256Hex(rawNewPassword),
});

switch (result)
{
    case AuthChangeUsernamePasswordResult.Success:
        // 변경 완료 → 새 비밀번호로 다시 로그인하도록 안내합니다.
        Debug.Log("비밀번호 변경 완료");
        break;

    case AuthChangeUsernamePasswordResult.UsernameVerifyFailed:
        // 현재 비밀번호가 일치하지 않는 상태입니다.
        Debug.LogWarning("현재 비밀번호를 다시 입력하도록 안내하세요.");
        break;

    case AuthChangeUsernamePasswordResult.SamePassword:
        // 새 비밀번호가 현재 비밀번호와 같은 상태입니다.
        Debug.LogWarning("다른 비밀번호를 입력하도록 안내하세요.");
        break;

    // 공통 실패 처리 (네트워크·서버 오류)
    case AuthChangeUsernamePasswordResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

    // 안전망: 처리하지 않은 결과 및 알 수 없는 신규 결과(UnknownOutcome)
    default:
        Debug.LogWarning($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

응답 데이터

성공 시 별도의 응답 데이터가 없습니다.

응답 상태

반환 객체 AuthChangeUsernamePasswordResult는 아래 케이스 중 하나로 분기됩니다.

응답 케이스 설명 앱 클라이언트 대응
Success 비밀번호 변경 성공 새 비밀번호로 다시 로그인하도록 안내
UsernameVerifyFailed 현재 비밀번호가 일치하지 않는 경우 현재 비밀번호 재입력 안내
SamePassword 새 비밀번호가 현재 비밀번호와 같은 경우 다른 비밀번호 입력 안내
UsernameNotFound 유저네임 계정을 찾을 수 없는 경우 계정 상태 확인
ProviderNotExist 이 계정에 유저네임 로그인 수단이 연결되어 있지 않은 경우 유저네임 연동 여부 확인
TokenRevokeFailed 로그인 세션 폐기에 실패해 요청이 완료되지 않은 경우 잠시 후 다시 시도
IpBlocked 접속 IP가 차단된 경우 정책 안내
AppNotFound · TerminateService 앱 정보를 찾을 수 없거나 서비스가 종료된 앱인 경우 콘솔의 App ID 등록 상태와 서비스 운영 상태 확인
AppIdMismatch · InvalidGatewayContext 요청의 App ID가 인증 토큰의 프로젝트와 다르거나 인증 컨텍스트가 유효하지 않은 경우 SDK 초기화에 사용한 App ID와 세션 상태 확인
UnknownOutcome 이 SDK 버전이 알지 못하는 신규 결과 로깅 후 보수적으로 처리
Failure 공통 Failure입니다. 필수 파라미터 누락·형식 오류(invalid_parameter), 필수 필드 누락(missing_field), X-App-Id 헤더 누락(missing_app_id)도 여기로 분기하며 원인은 Failure.Problem.ExternalCode에 담깁니다. 공통 오류 처리를 참조하세요. 공통 오류 처리 기준에 따라 처리

연관 문서