自定义身份验证流程¶

Authany 让您可以精确定义用户如何注册和登录。您可以不使用默认界面，而是配置自定义身份验证流程：通过一系列步骤，控制接受哪些标识符、如何验证这些标识符，以及用户如何完成身份验证。

在 Authany 管理台的 管理台 > 高级 > 编辑配置 中，编辑 YAML 里的 authentication_flow 部分来配置流程。

核心概念¶

在查看示例之前，先了解一下您会在 YAML 中反复看到的这些基本组成部分：

术语	作用
`signup_flows`	定义新用户注册的步骤
`login_flows`	定义老用户登录验证的步骤
`signup_login_flows`	一个流程，可自动判断用户是新用户还是老用户，并路由到相应的 `signup_flow` 或 `login_flow`
`type: identify`	向用户请求标识符（邮箱、手机号等）的步骤
`type: verify`	确认用户拥有该标识符的步骤（例如通过 OTP）
`type: authenticate`	使用已注册凭据对用户进行身份验证的步骤
`type: create_authenticator`	为用户注册新的身份验证器的步骤
`one_of`	列出该步骤允许的选项。即使只有一个选项，也必须填写。
`target_step`	将 `verify` 或 `create_authenticator` 步骤关联回收集凭据的 `identify` 步骤

前提条件¶

本页示例使用基于 OTP 的无密码身份验证，通过邮箱和短信实现。在添加 YAML 配置之前，请先在管理台中启用相应的登录方式：

打开 身份验证 > 登录方式
选择 手机 / 邮箱
在 身份验证 下，选择 无密码

如果您使用其他登录方式（例如基于密码），示例中的 primary_oob_otp_email 和 primary_oob_otp_sms 身份验证器将无法使用，请根据您选择的登录方式调整 authentication 的取值。

默认情况下，当邮箱和手机号两种方式都启用时，用户注册时只能任选其一，不能同时使用两者。本示例改变了这一行为：要求用户在注册时同时提供并验证邮箱地址和手机号。注册完成后，用户可以使用其中任意一个登录。

authentication_flow:
  signup_flows:
  - name: default
    steps:
    - name: setup_email
      type: identify
      one_of:
      - identification: email
        steps:
        - type: verify
          target_step: setup_email
        - type: create_authenticator
          name: authenticate_primary_email
          one_of:
          - authentication: primary_oob_otp_email
            target_step: setup_email
    - name: setup_phone
      type: identify
      one_of:
      - identification: phone
        steps:
        - type: verify
          target_step: setup_phone
        - type: create_authenticator
          name: authenticate_primary_phone
          one_of:
          - authentication: primary_oob_otp_sms
            target_step: setup_phone  

该注册流程包含两个顺序执行的步骤：先是 setup_email，然后是 setup_phone。

每个步骤都会收集一个标识符，并立即通过一次性验证码进行验证。随后 create_authenticator 步骤会将该标识符注册为一种登录方式，以便用户之后用它登录。

这里需要用到 target_step，因为 verify 和 create_authenticator 步骤嵌套在 identify 步骤内部，需要显式引用收集凭据的父步骤。

注意

此配置仅定义了 signup_flow，不包含登录步骤。请在管理台中禁用 「如果登录时找不到登录 ID，则自动注册新用户」，否则老用户登录时可能会触发注册而不是登录。

signup_login_flows 用一个流程同时处理新用户和老用户。用户输入一个标识符（邮箱或手机号），Authany 会检查该账号是否已存在：

找到账号 → 路由到 login_flow
未找到账号 → 路由到 signup_flow

这意味着您的界面只需要一个页面，不需要分别设置“登录”和“注册”按钮。

下面的示例将这一点与前一个示例中的双标识符要求结合起来。用户可以使用自己拥有的任意一个标识符登录。新用户在注册时必须验证手机号和邮箱两者，以便日后可以用任意一个登录。

authentication_flow:
  signup_login_flows:
  - name: default
    steps:
    - type: identify
      one_of:
      - identification: phone
        login_flow: default
        signup_flow: default
      - identification: email
        login_flow: default
        signup_flow: default

  login_flows:
  - name: default
    steps:
    - type: identify
      one_of:
      - identification: phone
        steps:
        - type: authenticate
          one_of:
          - authentication: primary_oob_otp_sms
      - identification: email
        steps:
        - type: authenticate
          one_of:
          - authentication: primary_oob_otp_email

  signup_flows:
  - name: default
    steps:
    - type: identify
      name: setup_id1
      one_of:
      - identification: phone
        steps:
        - type: verify
          target_step: setup_id1
        - type: identify
          name: setup_id2
          one_of:
          - identification: email
            steps:
            - type: verify
              target_step: setup_id2
      - identification: email
        steps:
        - type: verify
          target_step: setup_id1
        - type: identify
          name: setup_id3
          one_of:
          - identification: phone
            steps:
            - type: verify
              target_step: setup_id3
    - type: create_authenticator
      one_of:
      - authentication: primary_oob_otp_sms
      - authentication: primary_oob_otp_email

各部分的作用¶

signup_login_flows

用户选择一个标识符：手机号或邮箱。两个选项都指向同一个 login_flow: default 和 signup_flow: default。Authany 会查找该标识符并自动完成路由。

login_flows

面向老用户。用户完成身份标识后会收到一次性验证码：如果输入的是手机号，通过短信发送；如果输入的是邮箱地址，则通过邮件发送。

signup_flows

面向新用户。无论用户先输入哪一个标识符，该流程都会收集并验证两个标识符。

用户先输入手机号（setup_id1: phone）：Authany 先验证手机号，然后请求邮箱地址（setup_id2）并同样进行验证。
用户先输入邮箱（setup_id1: email）：Authany 先验证邮箱地址，然后请求手机号（setup_id3）并同样进行验证。

两个标识符都验证通过后，create_authenticator 步骤会注册用户之后登录时使用的 OTP 验证方式。

说明

setup_id2 和 setup_id3 是两个单独命名的步骤，因为第二个要收集的标识符取决于用户最初输入的是哪一个。每条路径都需要有自己命名的步骤，以便 target_step 能引用正确的步骤。

注意

使用 signup_login_flows 时，请在管理台中禁用 「如果登录时找不到登录 ID，则自动注册新用户」。该设置会与 signup_login_flows 的路由逻辑冲突。

延伸阅读¶

身份验证流程 API 概览：使用该 API 构建完全自定义的登录界面
身份验证流程 API 规范：所有流程类型、步骤类型和选项的完整参考