本机身份验证密码重置 API 参考

适用于: 绿色圆圈,带有白色复选标记符号,指示以下内容适用于外部租户。 外部租户(了解详细信息)

身份验证方法: 嵌入式本机身份验证。

密码重置验证客户的恢复方法、接受替换密码并轮询异步更新。 电子邮件和短信一次性密码(OTP)方法支持恢复。 多重身份验证(MFA)和条件访问要求可以在重置后和授权完成之前应用。

对于现有的 V1 集成,请使用 V1 API 参考。

Prerequisites

Important

本机身份验证 API V2 以预览版提供。 本机身份验证 API V1 仍然正式发布。 有关适用于预览功能的法律条款,请参阅Microsoft Azure预览版的补充使用条款。

这些示例使用 租户验证的自定义域颁发机构。 custom_domain 是身份验证域, tenant 是租户 GUID。

无密码电子邮件 OTP 帐户没有重置密码。

启动密码重置

此图显示了使用电子邮件一次性密码验证的独立恢复序列。 内联恢复改用活动登录事务中的密码方法 recover 链接。

密码恢复、密码验证、密码更新、可选轮询和授权代码交换的序列图。

启动授权 并遵循返回的重置密码链接(resetPassword 或 reset_password)。 不要先调用登录发现:

POST https://{custom_domain}/{tenant}/api/v2.0/resetpassword/start
Content-Type: application/json
Accept: application/hal+json
{
  "username": "user@contoso.com",
  "continuationToken": "******"
}

在中 username 发送客户的标识符和当前授权令牌 continuationToken。 该示例使用电子邮件地址。 响应可以播发电子邮件恢复方法:

{
  "state": "interactionRequired",
  "action": "challenge",
  "continuationToken": "******",
  "_links": {
    "self": {
      "href": "/{tenant}/api/v2.0/resetpassword/start"
    }
  },
  "_embedded": {
    "methods": [
      {
        "id": "{email_method_id}",
        "type": "email",
        "hint": "j****n@c****o",
        "_links": {
          "challenge": {
            "href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/challenge"
          },
          "verify": {
            "href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/verify"
          }
        }
      }
    ]
  }
}

通过用户选择或应用程序流逻辑选择返回的电子邮件或短信恢复方法。 该示例显示电子邮件;对于 SMS,请遵循返回的 SMS 方法的链接,而无需重写示例 URL。 使用接口需要目标标签的屏蔽提示。

登录期间内联恢复

仅在当前登录响应中的密码方法播发 recover 链接时提供内联恢复。 使用以下链接使用当前登录继续标记。 不要启动另一个授权请求或重新提交用户名或密码。

POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/recover
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******"
}

这两个入口点都使用服务返回的恢复方法、质询、验证、密码更新和轮询操作。

质询并验证恢复方法

发布到所选方法 challenge 的链接:

{
  "continuationToken": "******"
}

使用 JSON 和 Accept: application/hal+json. 共享质询操作返回当前方法类型、掩码hintcodeLength和verify可选resend链接。

将输入的密码发布到返回 verify 的链接:

{
  "otp": "{one_time_passcode}",
  "continuationToken": "******"
}

为每个请求使用最新的令牌。 对于另一个代码,请使用当前 resend 链接和服务限制,而不是早期的质询 URL/令牌对。

成功的验证可以返回密码方法:

{
  "state": "interactionRequired",
  "action": "update",
  "id": "{password_method_id}",
  "type": "password",
  "continuationToken": "******",
  "_links": {
    "update": {
      "href": "/{tenant}/api/v2.0/auth/methods/password/{password_method_id}"
    }
  }
}

使用返回 update 的链接中的密码方法 ID,而不是电子邮件或短信恢复方法 ID。 内联恢复可以从父登录中保留密码方法 ID。

更新密码

使用 PUT 提交替换密码,而不是 POST:

PUT https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}
Content-Type: application/json
Accept: application/hal+json
{
  "newPassword": "{new_password}",
  "continuationToken": "******"
}
Property 类型 必填 Description
continuationToken String. Yes. 请求密码更新的当前令牌。
newPassword String. Yes. 替换密码。 密码确认是接口本地的,而不是额外的请求字段。

该服务可以返回:

{
  "state": "interactionRequired",
  "action": "poll",
  "pollInterval": "2",
  "id": "{password_method_id}",
  "type": "password",
  "continuationToken": "******",
  "_links": {
    "poll": {
      "href": "/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/pollUpdate"
    }
  }
}

这表示异步更新,而不是最终授权。 在等待或自动重复更新时,不要在出现不明确的网络故障后再次提交密码。

轮询密码更新

按照最新 poll 链接操作:

POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/pollUpdate
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******"
}

在更新正在进行时,服务会返回 interactionRequired 带有 action: poll更新令牌和 poll 链接。 在下一轮投票之前替换之前的响应。

如果包含, pollInterval 则为包含间隔(以秒为单位)的字符串。 使用当前响应的下一个请求间隔,并遵循服务器重试指南。 该示例 "2" 不是固定的服务间隔。 当操作更改或返回错误时停止轮询,并处理策略所需的任何后续身份验证。

延续响应为:

{
  "state": "continue",
  "continuationToken": "******",
  "_links": {
    "continue": {
      "href": "/{tenant}/oauth2/v2.0/authorize-challenge"
    }
  }
}

完成策略要求并获取令牌

密码重置不会绕过 MFA 或条件访问。 如果返回另一个质询,请使用共享方法操作完成它。 令牌交换遵循剩余策略步骤和授权延续的完成。

之后 state: continue,使用最新的令牌 恢复授权 并 交换代码。 请求的范围和声明仍然是在事务开始时建立的范围和声明。

结果和错误

使用 共享错误处理。 恢复协定描述了以下结果:

条件 结果和客户端处理
未知用户名 恢复不会启动。 使用面向客户的通用消息。
电子邮件或短信密码不正确 HTTP 400 invalidGrant 与 innerError.code: invalidOneTimeCode. 让用户使用可用当前状态或播发的重新发送来更正代码。
缺少密码 HTTP 400 invalidRequest. 更正缺少的输入。
重新发送 通过返回 resend 的链接发送新密码。
密码更新令牌过期 HTTP 400 expiredToken 与 innerError.code: expiredContinuationToken. 重启授权。
弱或常见的替换密码 HTTP 400 invalidRequest 具有适用的内部错误,例如 passwordTooWeak 或 passwordTooCommon。 收集合规的密码。
正在进行更新 遵循最新的轮询响应和服务器重试指南。
轮询失败密码策略 具有内部错误的 HTTP 400 invalidRequest ,例如 passwordTooCommon 或 passwordBannedByPolicy。 处理错误,而不是无限期轮询。
轮询期间锁定或禁用帐户 HTTP 403 forbidden 与 innerError.code: accountLocked. 停止恢复操作。
密码更新作业失败 HTTP 500 serverError. 显示明确的失败,无需自动重复密码更新。
已完成的恢复 处理任何剩余的策略操作、恢复授权和请求令牌。

下表描述了特定结果,而不是详尽的错误目录。 密码更新验收、轮询完成和令牌颁发是单独的边界。

不要记录恢复密码、替换密码或事务令牌。 仅记录安全诊断 ID、时间戳和 HTTP 状态。 不要自动重播验证或密码更新。