处理适用于 Android 的 MSAL 中的异常和错误Handle exceptions and errors in MSAL for Android

Microsoft 身份验证库 (MSAL) 中的异常旨在帮助应用开发人员对其应用程序进行故障排除。Exceptions in the Microsoft Authentication Library (MSAL) are intended to help app developers troubleshoot their application. 异常消息未经本地化。Exception messages are not localized.

处理异常和错误时,可以使用异常类型本身和错误代码来区分不同的异常。When processing exceptions and errors, you can use the exception type itself and the error code to distinguish between exceptions. 有关错误代码的列表,请参阅身份验证和授权错误代码For a list of error codes, see Authentication and authorization error codes.

在登录体验期间,可能会遇到有关许可、条件访问(MFA、设备管理、基于位置的限制)、令牌颁发和兑换以及用户属性的错误。During the sign-in experience, you may encounter errors about consents, Conditional Access (MFA, Device Management, Location-based restrictions), token issuance and redemption, and user properties.

错误类Error class 原因/错误字符串Cause/error string 处理方式How to handle
MsalUiRequiredException
  • INVALID_GRANT:用于兑换访问令牌的刷新令牌无效、已过期或已撤销。INVALID_GRANT: The refresh token used to redeem access token is invalid, expired, or revoked. 此异常可能是由于密码更改导致的。This exception may be because of a password change.
  • NO_TOKENS_FOUND:访问令牌不存在,并且找不到用于兑换访问令牌的刷新令牌。NO_TOKENS_FOUND: Access token doesn't exist and no refresh token can be found to redeem access token.
  • 必需的升级Step-up required
    • MFAMFA
    • 缺少声明Missing claims
  • 被条件访问阻止(例如,需要安装身份验证代理Blocked by Conditional Access (for example, authentication broker installation required)
  • NO_ACCOUNT_FOUND:缓存中没有可用于无提示身份验证的帐户。NO_ACCOUNT_FOUND: No account available in the cache for silent authentication.
调用 acquireToken() 以提示用户输入用户名和密码,可能还需要同意并执行多重身份验证。Call acquireToken() to prompt the user to enter their username and password, and possibly consent and perform multi factor authentication.
MsalDeclinedScopeException
  • DECLINED_SCOPE:用户或服务器尚未接受所有作用域。DECLINED_SCOPE: User or server has not accepted all scopes. 如果请求的作用域不受支持、无法识别或不支持某个特定帐户,服务器可能会拒绝该作用域。The server may decline a scope if the requested scope is not supported, not recognized, or not supported for a particular account.
开发人员应该决定是继续使用授予的作用域进行身份验证还是结束身份验证过程。The developer should decide whether to continue authentication with the granted scopes or end the authentication process. 选项仅为已授予的范围重新提交获取令牌请求,并通过传递 silentParametersForGrantedScopes 和调用 acquireTokenSilent 提供有关已授予了哪些权限的提示。Option to resubmit the acquire token request only for the granted scopes and provide hints for which permissions have been granted by passing silentParametersForGrantedScopes and calling acquireTokenSilent.
MsalServiceException
  • INVALID_REQUEST:请求中缺少必需的参数、包含无效的参数、多次包含某个参数,或格式不正确。INVALID_REQUEST: This request is missing a required parameter, includes an invalid parameter, includes a parameter more than once, or is otherwise malformed.
  • SERVICE_NOT_AVAILABLE:表示由于服务中断而导致的 500/503/506 错误代码。SERVICE_NOT_AVAILABLE: Represents 500/503/506 error codes due to the service being down.
  • UNAUTHORIZED_REQUEST:客户端无权请求授权代码。UNAUTHORIZED_REQUEST: The client is not authorized to request an authorization code.
  • ACCESS_DENIED:资源所有者或授权服务器拒绝了请求。ACCESS_DENIED: The resource owner or authorization server denied the request.
  • INVALID_INSTANCEAuthorityMetadata 验证失败INVALID_INSTANCE: AuthorityMetadata validation failed
  • UNKNOWN_ERROR:对服务器的请求失败,但没有从服务返回错误和 error_descriptionUNKNOWN_ERROR: Request to server failed, but no error and error_description are returned back from the service.
    此异常类表示与服务通信时的错误,可以来自授权终结点或令牌终结点。This exception class represents errors when communicating to the service, can be from the authorize or token endpoints. MSAL 从服务器响应中读取错误和 error_description。MSAL reads the error and error_description from the server response. 通常,通过在代码中或在应用注册门户中修复应用配置来解决这些错误。Generally, these errors are resolved by fixing app configurations either in code or in the app registration portal. 服务中断很少会触发此警告,只有等待服务恢复才能缓解此警告。Rarely a service outage can trigger this warning, which can only be mitigated by waiting for the service to recover.
    MsalClientException
    • MULTIPLE_MATCHING_TOKENS_DETECTED:找到多个缓存项,sdk 无法从缓存中识别正确的访问或刷新令牌。MULTIPLE_MATCHING_TOKENS_DETECTED: There are multiple cache entries found and the sdk cannot identify the correct access or refresh token from the cache. 此异常通常表示 sdk 中存在用于存储令牌的错误,或者在无提示请求中未提供颁发机构,并且找到多个匹配的令牌。This exception usually indicates a bug in the sdk for storing tokens or that the authority is not provided in the silent request and multiple matching tokens are found.
    • DEVICE_NETWORK_NOT_AVAILABLE:设备上没有可用的活动网络。DEVICE_NETWORK_NOT_AVAILABLE: No active network is available on the device.
    • JSON_PARSE_FAILURE:sdk 未能分析 JSON 格式。JSON_PARSE_FAILURE: The sdk failed to parse the JSON format.
    • IO_ERROR:发生 IOException,可能是设备或网络错误。IO_ERROR: IOException happened, could be a device or network error.
    • MALFORMED_URL:Url 格式不正确。MALFORMED_URL: The url is malformed. 可能是在构造身份验证请求、颁发机构或重定向 URI 时导致的。Likely caused when constructing the auth request, authority, or redirect URI.
    • UNSUPPORTED_ENCODING:设备不支持编码。UNSUPPORTED_ENCODING: The encoding is not supported by the device.
    • NO_SUCH_ALGORITHM:不支持用于生成 PKCE 质询的算法。NO_SUCH_ALGORITHM: The algorithm used to generate PKCE challenge is not supported.
    • INVALID_JWTJWT 服务器返回的值无效、为空或格式错误。INVALID_JWT: JWT returned by the server is not valid or is empty or malformed.
    • STATE_MISMATCH:授权响应的状态与授权请求中的状态不匹配。STATE_MISMATCH: State from authorization response did not match the state in the authorization request. 对于授权请求,sdk 将验证重定向返回的状态和请求中发送的状态。For authorization requests, the sdk will verify the state returned from redirect and the one sent in the request.
    • UNSUPPORTED_URL:Url 不受支持,无法执行 ADFS 证书颁发机构验证。UNSUPPORTED_URL: Unsupported url, cannot perform ADFS authority validation.
    • AUTHORITY_VALIDATION_NOT_SUPPORTED:该颁发机构不支持颁发机构验证。AUTHORITY_VALIDATION_NOT_SUPPORTED: The authority is not supported for authority validation. sdk 支持 B2C 权限,但不支持 B2C 颁发机构验证。The sdk supports B2C authorities, but doesn't support B2C authority validation. 只支持已知主机。Only well-known host will be supported.
    • CHROME_NOT_INSTALLED:设备上未安装 Chrome。CHROME_NOT_INSTALLED: Chrome is not installed on the device. sdk 使用 chrome 自定义选项卡执行授权请求(如果可用),并回退到 chrome 浏览器。The sdk uses chrome custom tab for authorization requests if available, and will fall back to chrome browser.
    • USER_MISMATCH:获取令牌请求中提供的用户与从服务器返回的用户不匹配。USER_MISMATCH: The user provided in the acquire token request doesn't match the user returned from server.
    此异常类表示库本地的常规错误。This exception class represents general errors that are local to the library. 可以通过更正请求来处理这些异常。These exceptions can be handled by correcting the request.
    MsalUserCancelException
    • USER_CANCELED:用户启动了交互流,并在收到返回的令牌之前取消了请求。USER_CANCELED: The user initiated interactive flow and prior to receiving tokens back they canceled the request.
    MsalArgumentException
    • ILLEGAL_ARGUMENT_ERROR_CODE
    • AUTHORITY_REQUIRED_FOR_SILENT:必须为 acquireTokenSilent 指定颁发机构。AUTHORITY_REQUIRED_FOR_SILENT: Authority must be specified for acquireTokenSilent.
    开发人员可以通过以下方式缓解这些错误:更正参数并确保完成了交互式验证、完成回调、设置作用域,并提供了具有有效 ID 的帐户。These errors can be mitigated by the developer correcting arguments and ensuring activity for interactive auth, completion callback, scopes, and an account with a valid ID have been provided.

    捕获错误Catching errors

    下面的代码片段显示了在无提示 acquireToken 调用的情况下捕获错误的示例。The following code snippet shows an example of catching errors in the case of silent acquireToken calls.

    /**
     * Callback used in for silent acquireToken calls.
     */
    private SilentAuthenticationCallback getAuthSilentCallback() {
        return new SilentAuthenticationCallback() {
    
            @Override
            public void onSuccess(IAuthenticationResult authenticationResult) {
                Log.d(TAG, "Successfully authenticated");
    
                /* Successfully got a token, use it to call a protected resource - MSGraph */
                callGraphAPI(authenticationResult);
            }
    
            @Override
            public void onError(MsalException exception) {
                /* Failed to acquireToken */
                Log.d(TAG, "Authentication failed: " + exception.toString());
                displayError(exception);
    
                if (exception instanceof MsalClientException) {
                    /* Exception inside MSAL, more info inside MsalError.java */
                } else if (exception instanceof MsalServiceException) {
                    /* Exception when communicating with the STS, likely config issue */
                } else if (exception instanceof MsalUiRequiredException) {
                    /* Tokens expired or no session, retry with interactive */
                }
            }
        };
    }
    

    后续步骤Next steps

    详细了解日志记录错误Learn more about logging errors