แก้ไข

Native authentication user attribute concepts

Applies to: Green circle with a white check mark symbol that indicates the following content applies to external tenants. External tenants (learn more)

Authentication approach: Embedded native authentication.

Native authentication user attributes are values that your application collects during sign-up according to the application's user flow. The service describes the fields and validation requirements in its response. Your application controls the interface and collection logic, satisfies the returned requirements, and submits values by their returned identifiers.

Descriptors define the form

Important

The Native Authentication API V2 is in preview. The Native Authentication API V1 remains generally available. See the Supplemental Terms of Use for Microsoft Azure Previews for legal terms that apply to preview features.

A response with action: collectAttributes contains an attributes array and a submitAttributes link. Use the descriptors for the current interaction when deciding which values need user input.

Descriptor Client use
attributeId Use this exact value as the key in the submitted attributes object.
inputType Select the appropriate input control. Examples include text, boolean, date, and checkboxMultiSelect.
required Indicate that a value is required before the flow can complete.
hidden Determine whether the field is visible.
canChange Use the returned editability information when included.
label Present the returned label when included.
initialValue Use the prepopulated value when included.
validation.validationRegEx Help the customer correct invalid input without replacing service validation.
options Present the returned choices, using each option's label and value.
confirmationInput Apply the indicated confirmation behavior, such as retype, reveal, or none.

For example, an email-only form can be described as:

{
  "attributeId": "email",
  "inputType": "text",
  "hidden": false,
  "required": true,
  "canChange": true,
  "label": "Email"
}

The submission uses "email" as the key, not the display label "Email". Render labels and validation messages as text, not executable HTML.

Pages group the requested attributes

Your application can group fields into screens, but it doesn't need a pages member to render attribute collection. Field definitions and requirements come from the current attributes array. If page-grouping metadata is returned, treat it as additional presentation information, not a requirement for every response.

If the service asks for another collection round, replace the prior form model with the new response. Sign-up can require multiple attribute-collection steps.

Collection order and email verification

The service determines the collection and verification order. It can request email before other account details, collect several attributes together, or return to collection after verification. Submit only the attributes requested by the latest response, then follow the next response's action.

All required attributes and proofs still need to be satisfied. When the response returns verify for email, the service has sent the passcode. Your app collects it and follows the returned verification link instead of sending an extra challenge.

Email-with-password sign-up requests a password as an attribute. Email one-time passcode sign-up doesn't request a password. Collect the values requested for the selected user flow.

Values and validation

Attribute submission contains the latest continuation token and an object of string values:

{
  "continuationToken": "******",
  "attributes": {
    "email": "user@contoso.com"
  }
}

Use the returned identifiers for built-in and custom fields, including any custom-attribute prefix. Optional attributes can be omitted. Missing required values can cause a validation error or another collection response. An input control type doesn't change the request's string-value contract; don't substitute a JSON Boolean or array based only on the control.

Structured validation entries in error.innerError.details can identify affected attributeIds and include code, message, optional suggestions, and optional recovery. Associate a field error with the matching control. A corrected request still needs service validation; accepting input locally doesn't complete sign-up.

Profile values, methods, and tokens are different

Profile attribute collection, authentication-method registration, and credential verification have separate contracts. For example, a phone number collected as a profile attribute still requires the applicable registration and verification operations before use as an MFA method.

Submitted profile values aren't necessarily included in every token. Token requests use the scopes and claims established at the beginning of authorization. Avoid logging either submitted profile values or the issued tokens.

After account creation, don't replay successful attribute submissions. Follow the latest action, including additional policy requirements, until authorization can continue.