Define phone number claims transformations in Azure AD B2C

  • Article

This article provides reference and examples for using the phone number claims transformations in Azure Active Directory B2C (Azure AD B2C) custom policy. For more information about claims transformations in general, see ClaimsTransformations.

Note

This feature is in public preview.

ConvertPhoneNumberClaimToString

Converts a phoneNumber data type into a string data type. Check out the Live demo of this claims transformation.

Element TransformationClaimType Data Type Notes
InputClaim phoneNumber phoneNumber The claim to convert to a string.
OutputClaim phoneNumberString string The claim that is produced after this claims transformation has been invoked.

Example of ConvertPhoneNumberClaimToString

In this example, the cellPhoneNumber claim with a value type of phoneNumber is converted to a cellPhone claim with a value type of string.

<ClaimsTransformation Id="PhoneNumberToString" TransformationMethod="ConvertPhoneNumberClaimToString">
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="cellPhoneNumber" TransformationClaimType="phoneNumber" />
  </InputClaims>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="cellPhone" TransformationClaimType="phoneNumberString" />
  </OutputClaims>
</ClaimsTransformation>
  • Input claims:
    • phoneNumber: +11234567890 (phoneNumber)
  • Output claims:
    • phoneNumberString: +11234567890 (string)

ConvertStringToPhoneNumberClaim

Validates the format of a phone number. If valid, change it to a standard format used by Azure AD B2C. If the provided phone number isn't in a valid format, an error message is returned. Check out the Live demo of this claims transformation.

Element TransformationClaimType Data Type Notes
InputClaim phoneNumberString string The string claim for the phone number. The phone number has to be in international format, complete with a leading "+" and country/region code. If input claim country is provided, the phone number is in local format (without the country/region code).
InputClaim country string [Optional] The string claim for the country/region code of the phone number in ISO3166 format (the two-letter ISO-3166 country/region code).
OutputClaim outputClaim phoneNumber The result of this claims transformation.

The ConvertStringToPhoneNumberClaim claims transformation is always executed from a validation technical profile that is called by a self-asserted technical profile or display control. The UserMessageIfClaimsTransformationInvalidPhoneNumber self-asserted technical profile metadata controls the error message that is presented to the user.

Diagram of error message execution path

Example of ConvertStringToPhoneNumberClaim

The following example checks that the phoneString claim is indeed a valid phone number, and then returns the phone number in the standard Azure AD B2C format. Otherwise, an error message is thrown.

<ClaimsTransformation Id="ConvertStringToPhoneNumber" TransformationMethod="ConvertStringToPhoneNumberClaim">
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="phoneString" TransformationClaimType="phoneNumberString" />
    <InputClaim ClaimTypeReferenceId="countryCode" TransformationClaimType="country" />
  </InputClaims>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="phoneNumber" TransformationClaimType="outputClaim" />
  </OutputClaims>
</ClaimsTransformation>
  • Input claims:
    • phoneNumberString: 033 456-7890
    • country: DK
  • Output claims:
    • outputClaim: +450334567890

Example of ConvertStringToPhoneNumberClaim without country code claim

Check out the Live demo of this mode of the claims transformation.

  • Input claims:
    • phoneNumberString: +1 (123) 456-7890
  • Output claims:
    • outputClaim: +11234567890

Calling the ConvertStringToPhoneNumberClaim claims transformation

The self-asserted technical profile that calls the validation technical profile that contains this claims transformation can define the error message.

<TechnicalProfile Id="SelfAsserted-LocalAccountSignUp-Phone">
  <Metadata>
    <Item Key="UserMessageIfClaimsTransformationInvalidPhoneNumber">Custom error message if the phone number is not valid.</Item>
  </Metadata>
  ...
</TechnicalProfile>

GetNationalNumberAndCountryCodeFromPhoneNumberString

Extracts the country/region code and the national number from the input claim, and optionally throws an exception if the supplied phone number isn't valid. Check out the Live demo of this claims transformation.

Element TransformationClaimType Data Type Notes
InputClaim phoneNumber string The string claim of the phone number. The phone number has to be in international format, complete with a leading "+" and country/region code.
InputParameter throwExceptionOnFailure boolean [Optional] A parameter indicating whether an exception is thrown when the phone number isn't valid. Default value is false.
InputParameter countryCodeType string [Optional] A parameter indicating the type of country/region code in the output claim. Available values are CallingCode (the international calling code for a country/region, for example +1) or ISO3166 (the two-letter ISO-3166 country/region code).
OutputClaim nationalNumber string The string claim for the national number of the phone number.
OutputClaim countryCode string The string claim for the country/region code of the phone number.

If the GetNationalNumberAndCountryCodeFromPhoneNumberString claims transformation is executed from a validation technical profile that is called by a self-asserted technical profile or a display control action, then the UserMessageIfPhoneNumberParseFailure self-asserted technical profile metadata controls the error message that is presented to the user.

Diagram of error message execution path

You can use this claims transformation to split a full phone number into the country/region code and the national number. If the phone number provided isn't valid, you can choose to throw an error message.

Example of GetNationalNumberAndCountryCodeFromPhoneNumberString

The following example tries to split the phone number into national number and country/region code. If the phone number is valid, the phone number will be overridden by the national number. If the phone number isn't valid, an exception won't be thrown and the phone number still has its original value.

<ClaimsTransformation Id="GetNationalNumberAndCountryCodeFromPhoneNumberString" TransformationMethod="GetNationalNumberAndCountryCodeFromPhoneNumberString">
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="phoneNumber" TransformationClaimType="phoneNumber" />
  </InputClaims>
  <InputParameters>
    <InputParameter Id="throwExceptionOnFailure" DataType="boolean" Value="false" />
    <InputParameter Id="countryCodeType" DataType="string" Value="ISO3166" />
  </InputParameters>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="nationalNumber" TransformationClaimType="nationalNumber" />
    <OutputClaim ClaimTypeReferenceId="countryCode" TransformationClaimType="countryCode" />
  </OutputClaims>
</ClaimsTransformation>
  • Input claims:
    • phoneNumber: +49 (123) 456-7890
  • Input parameters:
    • throwExceptionOnFailure: false
    • countryCodeType: ISO3166
  • Output claims:
    • nationalNumber: 1234567890
    • countryCode: DE

Example of GetNationalNumberAndCountryCodeFromPhoneNumberString with CallingCode parameter

The following example tries to split the phone number into national number and country calling code.

<ClaimsTransformation Id="GetNationalNumberAndCountryCodeFromPhoneNumberString" TransformationMethod="GetNationalNumberAndCountryCodeFromPhoneNumberString">
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="phoneNumber" TransformationClaimType="phoneNumber" />
  </InputClaims>
  <InputParameters>
    <InputParameter Id="throwExceptionOnFailure" DataType="boolean" Value="false" />
    <InputParameter Id="countryCodeType" DataType="string" Value="CallingCode" />
  </InputParameters>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="nationalNumber" TransformationClaimType="nationalNumber" />
    <OutputClaim ClaimTypeReferenceId="countryCode" TransformationClaimType="countryCode" />
  </OutputClaims>
</ClaimsTransformation>
  • Input claims:
    • phoneNumber: +49 (123) 456-7890
  • Input parameters
    • throwExceptionOnFailure: false
    • countryCodeType: CallingCode
  • Output claims:
    • nationalNumber: 1234567890
    • countryCode: +49

Calling the GetNationalNumberAndCountryCodeFromPhoneNumberString claims transformation

The self-asserted technical profile that calls the validation technical profile that contains this claims transformation can define the error message.

<TechnicalProfile Id="SelfAsserted-LocalAccountSignup-Phone">
  <Metadata>
    <Item Key="UserMessageIfPhoneNumberParseFailure">Custom error message if the phone number is not valid.</Item>
  </Metadata>
  ...
</TechnicalProfile>

Next steps