Add an API connector to a sign-up user flow

You can create an API endpoint using one of our samples.

In this scenario, we'll add the ability for users to enter a loyalty number into the Azure AD B2C sign-up page. The REST API validates whether the combination of email and loyalty number is mapped to a promotional code. If the REST API finds a promotional code for this user, it will be returned to Azure AD B2C. Finally, the promotional code will be inserted into the token claims for the application to consume.

You can also design the interaction as an orchestration step. This is suitable when the REST API will not be validating data on screen, and always return claims. For more information, see Walkthrough: Integrate REST API claims exchanges in your Azure AD B2C user journey as an orchestration step.

• Create a user flow so users can sign up and sign in to your application.
• Register a web application.

• Complete the steps in Get started with custom policies in Active Directory B2C. This tutorial guides you how to update custom policy files to use your Azure AD B2C tenant configuration.
• Register a web application.

Create an API connector

To use an API connector, you first create the API connector and then enable it in a user flow.

1. Sign in to the Azure portal.

2. Under Azure services, select Azure AD B2C.

3. Select API connectors, and then select New API connector.

   

4. Provide a display name for the call. For example, Validate user information.

5. Provide the Endpoint URL for the API call.

6. Choose the Authentication type and configure the authentication information for calling your API. Learn how to Secure your API Connector.

   

7. Select Save.

The request sent to your API

An API connector materializes as an HTTP POST request, sending user attributes ('claims') as key-value pairs in a JSON body. Attributes are serialized similarly to Microsoft Graph user properties.

Example request

POST <API-endpoint>
Content-type: application/json

{
 "email": "[email protected]",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "objectId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "step": "<step-name>",
 "client_id":"00001111-aaaa-2222-bbbb-3333cccc4444",
 "ui_locales":"en-US"
}

Only user properties and custom attributes listed in the Azure AD B2C > User attributes experience are available to be sent in the request.

Custom attributes exist in the extension_<extensions-app-id>_CustomAttribute format in the directory. Your API should expect to receive claims in this same serialized format. For more information on custom attributes, see Define custom attributes in Azure AD B2C.

Additionally, these claims are typically sent in all requests:

• UI Locales ('ui_locales') - An end-user's locale(s) as configured on their device. This can be used by your API to return internationalized responses.
• Step ('step') - The step or point on the user flow that the API connector was invoked for. Values include:
  • PostFederationSignup - corresponds to "After federating with an identity provider during sign-up"
  • PostAttributeCollection - corresponds to "Before creating the user"
  • PreTokenIssuance - corresponds to "Before sending the token (preview)". Learn more about this step
• Client ID ('client_id') - The appId value of the application that an end-user is authenticating to in a user flow. This is not the resource application's appId in access tokens.
• Email Address ('email') or identities ('identities') - these claims can be used by your API to identify the end-user that is authenticating to the application.

Enable the API connector in a user flow

Follow these steps to add an API connector to a sign-up user flow.

1. Sign in to the Azure portal.

2. Under Azure services, select Azure AD B2C.

3. Select User flows, and then select the user flow you want to add the API connector to.

4. Select API connectors, and then select the API endpoints you want to invoke at the following steps in the user flow:

   • After federating with an identity provider during sign-up
   • Before creating the user
   • Before sending the token (preview)

   

5. Select Save.

These steps only exist for Sign up and sign in (Recommended) and Sign up (Recommended) but only apply to the sign-up part of the experience.

After federating with an identity provider during sign-up

An API connector at this step in the sign-up process is invoked immediately after the user authenticates with an identity provider (like Google, Facebook, and Microsoft Entra ID). This step precedes the attribute collection page, which is the form presented to the user to collect user attributes. This step is not invoked if a user is registering with a local account.

Example request sent to the API at this step

POST <API-endpoint>
Content-type: application/json

{
 "email": "[email protected]",
 "identities": [ 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "step": "PostFederationSignup",
 "client_id":"<guid>",
 "ui_locales":"en-US"
}

The exact claims sent to the API depend on the information is provided by the identity provider. 'email' is always sent.

Expected response types from the web API at this step

When the web API receives an HTTP request from Microsoft Entra ID during a user flow, it can return these responses:

• Continuation response
• Blocking response

Continuation response

A continuation response indicates that the user flow should continue to the next step: the attribute collection page.

In a continuation response, the API can return claims. If a claim is returned by the API, the claim does the following:

• Pre-fills the input field in the attribute collection page.

See an example of a continuation response.

Blocking Response

A blocking response exits the user flow. It can be purposely issued by the API to stop the continuation of the user flow by displaying a block page to the user. The block page displays the userMessage provided by the API.

See an example of a blocking response.

Before creating the user

An API connector at this step in the sign-up process is invoked after the attribute collection page, if one is included. This step is always invoked before a user account is created.

Example request sent to the API at this step

POST <API-endpoint>
Content-type: application/json

{
 "email": "[email protected]",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "step": "PostAttributeCollection",
 "client_id":"00001111-aaaa-2222-bbbb-3333cccc4444",
 "ui_locales":"en-US"
}

The claims that are sent to the API depend on the information is collected from the user or is provided by the identity provider.

Expected response types from the web API at this step

When the web API receives an HTTP request from Microsoft Entra ID during a user flow, it can return these responses:

• Continuation response
• Blocking response
• Validation response

Continuation response

A continuation response indicates that the user flow should continue to the next step: create the user in the directory.

In a continuation response, the API can return claims. If a claim is returned by the API, the claim does the following:

• Overrides any value that has already been provided by a user in the attribute collection page.

To write claims to the directory on sign-up that shouldn't be collected from the user, you should still select the claims under User attributes of the user flow, which will by default ask the user for values, but you can use custom JavaScript or CSS to hide the input fields from an end user.

See an example of a continuation response.

Blocking Response

A blocking response exits the user flow. It can be purposely issued by the API to stop the continuation of the user flow by displaying a block page to the user. The block page displays the userMessage provided by the API.

See an example of a blocking response.

Validation-error response

When the API responds with a validation-error response, the user flow stays on the attribute collection page and a userMessage is displayed to the user. The user can then edit and resubmit the form. This type of response can be used for input validation.

See an example of a validation-error response.

Before sending the token (preview)

An API connector at this step is invoked when a token is about to be issued during sign-ins and sign-ups. An API connector for this step can be used to enrich the token with claim values from external sources.

Example request sent to the API at this step

POST <API-endpoint>
Content-type: application/json

{
 "clientId": "11112222-bbbb-3333-cccc-4444dddd5555",
 "step": "PreTokenApplicationClaims",
 "ui_locales":"en-US",
 "email": "[email protected]",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
}

The claims that are sent to the API depend on the information defined for the user.

Expected response types from the web API at this step

When the web API receives an HTTP request from Microsoft Entra ID during a user flow, it can return these responses:

• Continuation response

Continuation response

A continuation response indicates that the user flow should continue to the next step: issue the token.

In a continuation response, the API can return additional claims. A claim returned by the API that you want to return in the token must be a built-in claim or defined as a custom attribute and must be selected in the Application claims configuration of the user flow.

The claim value in the token will be the value returned by the API, not the value in the directory. Some claim values cannot be overwritten by the API response. Claims that can be returned by the API correspond to the set found under User attributes with the exception of email.

See an example of a continuation response.

Example responses

Example of a continuation response

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "Continue",
    "postalCode": "12349", // return claim
    "extension_<extensions-app-id>_CustomAttribute": "value" // return claim
}

Example of a blocking response

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "There was a problem with your request. You are not able to sign up at this time. Please contact your system administrator",
}

End-user experience with a blocking response

Example of a validation-error response

HTTP/1.1 400 Bad Request
Content-type: application/json

{
    "version": "1.0.0",
    "status": 400,
    "action": "ValidationError",
    "userMessage": "Please enter a valid Postal Code."
}

End-user experience with a validation-error response

Prepare a REST API endpoint

For this walkthrough, you should have a REST API that validates whether an email address is registered in your back-end system with a loyalty ID. If registered, the REST API should return a registration promotion code, which the customer can use to buy goods within your application. Otherwise, the REST API should return an HTTP 409 error message: "Loyalty ID '{loyalty ID}' is not associated with '{email}' email address.".

The following JSON code illustrates the data Azure AD B2C will send to your REST API endpoint.

{
    "email": "User email address",
    "language": "Current UI language",
    "loyaltyId": "User loyalty ID"
}

Once your REST API validates the data, it must return an HTTP 200 (Ok), with the following JSON data:

{
    "promoCode": "24534"
}

If the validation failed, the REST API must return an HTTP 409 (Conflict), with the userMessage JSON element. The IEF expects the userMessage claim that the REST API returns. This claim will be presented as a string to the user if the validation fails.

{
    "version": "1.0.1",
    "status": 409,
    "userMessage": "LoyaltyId ID '1234' is not associated with '[email protected]' email address."
}

The setup of the REST API endpoint is outside the scope of this article. We have created an Azure Functions sample. You can access the complete Azure function code at GitHub.

Define claims

A claim provides temporary storage of data during an Azure AD B2C policy execution. You can declare claims within the claims schema section.

1. Open the extensions file of your policy. For example, SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
2. Search for the BuildingBlocks element. If the element doesn't exist, add it.
3. Locate the ClaimsSchema element. If the element doesn't exist, add it.
4. Add the following claims to the ClaimsSchema element.

<ClaimType Id="loyaltyId">
  <DisplayName>Your loyalty ID</DisplayName>
  <DataType>string</DataType>
  <UserInputType>TextBox</UserInputType>
</ClaimType>
<ClaimType Id="promoCode">
  <DisplayName>Your promo code</DisplayName>
  <DataType>string</DataType>
  <UserInputType>Paragraph</UserInputType>
</ClaimType>
  <ClaimType Id="userLanguage">
  <DisplayName>User UI language (used by REST API to return localized error messages)</DisplayName>
  <DataType>string</DataType>
</ClaimType>

Add the RESTful API technical profile

A Restful technical profile provides support for interfacing to your own RESTful service. Azure AD B2C sends data to the RESTful service in an InputClaims collection and receives data back in an OutputClaims collection. Find the ClaimsProviders element and add a new claims provider as follows:

<ClaimsProvider>
  <DisplayName>REST APIs</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="REST-ValidateProfile">
      <DisplayName>Check loyaltyId Azure Function web hook</DisplayName>
      <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
      <Metadata>
        <!-- Set the ServiceUrl with your own REST API endpoint -->
        <Item Key="ServiceUrl">https://your-account.azurewebsites.net/api/ValidateProfile?code=your-code</Item>
        <Item Key="SendClaimsIn">Body</Item>
        <!-- Set AuthenticationType to Basic or ClientCertificate in production environments -->
        <Item Key="AuthenticationType">None</Item>
        <!-- REMOVE the following line in production environments -->
        <Item Key="AllowInsecureAuthInProduction">true</Item>
      </Metadata>
      <InputClaims>
        <!-- Claims sent to your REST API -->
        <InputClaim ClaimTypeReferenceId="loyaltyId" />
        <InputClaim ClaimTypeReferenceId="email" />
        <InputClaim ClaimTypeReferenceId="userLanguage" PartnerClaimType="lang" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
      </InputClaims>
      <OutputClaims>
        <!-- Claims parsed from your REST API -->
        <OutputClaim ClaimTypeReferenceId="promoCode" />
      </OutputClaims>
      <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

In this example, the userLanguage will be sent to the REST service as lang within the JSON payload. The value of the userLanguage claim contains the current user language ID. For more information, see claim resolver.

Configure the RESTful API technical profile

After you deploy your REST API, set the metadata of the REST-ValidateProfile technical profile to reflect your own REST API, including:

• ServiceUrl. Set the URL of the REST API endpoint.
• SendClaimsIn. Specify how the input claims are sent to the RESTful claims provider.
• AuthenticationType. Set the type of authentication being performed by the RESTful claims provider.
• AllowInsecureAuthInProduction. In a production environment, make sure to set this metadata to true

See the RESTful technical profile metadata for more configurations.

The comments above AuthenticationType and AllowInsecureAuthInProduction specify changes you should make when you move to a production environment. To learn how to secure your RESTful APIs for production, see Secure RESTful API.

Validate the user input

To obtain the user's loyalty number during sign-up, you must allow the user to enter this data on the screen. Add the loyaltyId output claim to the sign-up page by adding it to the existing sign-up technical profile section's OutputClaims element. Specify the entire list of output claims to control the order the claims are presented on the screen.

Add the validation technical profile reference to the sign-up technical profile, which calls the REST-ValidateProfile. The new validation technical profile will be added to the top of the <ValidationTechnicalProfiles> collection defined in the base policy. This behavior means that only after successful validation, Azure AD B2C moves on to create the account in the directory.

1. Find the ClaimsProviders element. Add a new claims provider as follows:

   <ClaimsProvider>
     <DisplayName>Local Account</DisplayName>
     <TechnicalProfiles>
       <TechnicalProfile Id="LocalAccountSignUpWithLogonEmail">
         <OutputClaims>
           <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="Verified.Email" Required="true"/>
           <OutputClaim ClaimTypeReferenceId="newPassword" Required="true"/>
           <OutputClaim ClaimTypeReferenceId="reenterPassword" Required="true"/>
           <OutputClaim ClaimTypeReferenceId="displayName"/>
           <OutputClaim ClaimTypeReferenceId="givenName"/>
           <OutputClaim ClaimTypeReferenceId="surName"/>
           <!-- Required to present the text box to collect the data from the user -->
           <OutputClaim ClaimTypeReferenceId="loyaltyId"/>
           <!-- Required to pass the promoCode returned from "REST-ValidateProfile" 
           to subsequent orchestration steps and token issuance-->
           <OutputClaim ClaimTypeReferenceId="promoCode" />
         </OutputClaims>
         <ValidationTechnicalProfiles>
           <ValidationTechnicalProfile ReferenceId="REST-ValidateProfile" />
         </ValidationTechnicalProfiles>
       </TechnicalProfile>
     </TechnicalProfiles>
   </ClaimsProvider>
   <ClaimsProvider>
     <DisplayName>Self Asserted</DisplayName>
     <TechnicalProfiles>
       <TechnicalProfile Id="SelfAsserted-Social">
         <InputClaims>
           <InputClaim ClaimTypeReferenceId="email" />
         </InputClaims>
           <OutputClaims>
           <OutputClaim ClaimTypeReferenceId="email" />
           <OutputClaim ClaimTypeReferenceId="displayName"/>
           <OutputClaim ClaimTypeReferenceId="givenName"/>
           <OutputClaim ClaimTypeReferenceId="surname"/>
           <!-- Required to present the text box to collect the data from the user -->
           <OutputClaim ClaimTypeReferenceId="loyaltyId"/>
           <!-- Required to pass the promoCode returned from "REST-ValidateProfile" 
           to subsequent orchestration steps and token issuance-->
           <OutputClaim ClaimTypeReferenceId="promoCode" />
         </OutputClaims>
         <ValidationTechnicalProfiles>
           <ValidationTechnicalProfile ReferenceId="REST-ValidateProfile"/>
         </ValidationTechnicalProfiles>
       </TechnicalProfile>
     </TechnicalProfiles>
   </ClaimsProvider>
   

Include a claim in the token

To return the promo code claim back to the relying party application, add an output claim to the SocialAndLocalAccounts/SignUpOrSignIn.xml file. The output claim will allow the claim to be added into the token after a successful user journey, and will be sent to the application. Modify the technical profile element within the relying party section to add the promoCode as an output claim.

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="OpenIdConnect" />
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="displayName" />
      <OutputClaim ClaimTypeReferenceId="givenName" />
      <OutputClaim ClaimTypeReferenceId="surname" />
      <OutputClaim ClaimTypeReferenceId="email" />
      <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
      <OutputClaim ClaimTypeReferenceId="identityProvider" />
      <OutputClaim ClaimTypeReferenceId="tenantId" AlwaysUseDefaultValue="true" DefaultValue="{Policy:TenantObjectId}" />
      <OutputClaim ClaimTypeReferenceId="promoCode" DefaultValue="" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

Test the custom policy

1. Sign in to the Azure portal.
2. If you have access to multiple tenants, select the Settings icon in the top menu to switch to your Microsoft Entra ID tenant from the Directories + subscriptions menu.
3. Choose All services in the top-left corner of the Azure portal, and then search for and select App registrations.
4. Select Identity Experience Framework.
5. Select Upload Custom Policy, and then upload the policy files that you changed: TrustFrameworkExtensions.xml, and SignUpOrSignin.xml.
6. Select the sign-up or sign-in policy that you uploaded, and click the Run now button.
7. You should be able to sign up using an email address.
8. Click on the Sign-up now link.
9. In the Your loyalty ID, type 1234, and click Continue. At this point, you should get a validation error message.
10. Change to another value and click Continue.
11. The token sent back to your application includes the promoCode claim.

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
  "exp": 1584295703,
  "nbf": 1584292103,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/",
  "aud": "22223333-cccc-4444-dddd-5555eeee6666",
  "acr": "b2c_1a_signup_signin",
  "nonce": "defaultNonce",
  "iat": 1584292103,
  "auth_time": 1584292103,
  "name": "Emily Smith",
  "email": "[email protected]",
  "given_name": "Emily",
  "family_name": "Smith",
  "promoCode": "84362"
  ...
}

Using serverless cloud functions

Serverless functions, like HTTP triggers in Azure Functions, provide a way create API endpoints to use with the API connector. You can use the serverless cloud function to, for example, perform validation logic and limit sign-ups to specific email domains. The serverless cloud function can also call and invoke other web APIs, data stores, and other cloud services for complex scenarios.

Best practices

Ensure that:

• Your API is following the API request and response contracts as outlined above.
• The Endpoint URL of the API connector points to the correct API endpoint.
• Your API explicitly checks for null values of received claims that it depends on.
• Your API implements an authentication method outlined in secure your API Connector.
• Your API responds as quickly as possible to ensure a fluid user experience.
  • Azure AD B2C will wait for a maximum of 20 seconds to receive a response. If none is received, it will make one more attempt (retry) at calling your API.
  • If using a serverless function or scalable web service, use a hosting plan that keeps the API "awake" or "warm" in production. For Azure Functions, it's recommended to use at minimum the Premium plan in production.
• Ensure high availability of your API.
• Monitor and optimize performance of downstream APIs, databases, or other dependencies of your API.

Use logging

In general, it's helpful to use the logging tools enabled by your web API service, like Application insights, to monitor your API for unexpected error codes, exceptions, and poor performance.

• Monitor for HTTP status codes that aren't HTTP 200 or 400.
• A 401 or 403 HTTP status code typically indicates there's an issue with your authentication. Double-check your API's authentication layer and the corresponding configuration in the API connector.
• Use more aggressive levels of logging (for example "trace" or "debug") in development if needed.
• Monitor your API for long response times.

Additionally, Azure AD B2C logs metadata about the API transactions that happen during user authentications via a user flow. To find these:

1. Go to Azure AD B2C.
2. Under Activities, select Audit logs.
3. Filter the list view: For Date, select the time interval you want, and for Activity, select An API was called as part of a user flow.
4. Inspect individual logs. Each row represents an API connector attempting to be called during a user flow. If an API call fails and a retry occurs, it's still represented as a single row. The numberOfAttempts indicates the number of times your API was called. This value can be 1or 2. Other information about the API call is detailed in the logs.

Using serverless cloud functions

Serverless cloud functions, like HTTP triggers in Azure Functions, provide a simple, highly available, high performant way to create API endpoints to use as API connectors.

Best practices

Ensure that:

• Your API explicitly checks for null values of received claims that it depends on.
• Your API implements an authentication method outlined in secure your API Connector.
• Your API responds as quickly as possible to ensure a fluid user experience.
  • If using a serverless function or scalable web service, use a hosting plan that keeps the API "awake" or "warm" in production. For Azure Functions, it's recommended to use at minimum the Premium plan
• Ensure high availability of your API.
• Monitor and optimize performance of downstream APIs, databases, or other dependencies of your API.

Use logging

In general, it's helpful to use the logging tools enabled by your web API service, like Application insights, to monitor your API for unexpected error codes, exceptions, and poor performance.

• Monitor for HTTP status codes that aren't HTTP 200 or 400.
• A 401 or 403 HTTP status code typically indicates there's an issue with your authentication. Double-check your API's authentication layer and the corresponding configuration in the API connector.
• Use more aggressive levels of logging (for example "trace" or "debug") in development if needed.
• Monitor your API for long response times.

• Get started with our samples.
• Secure your API Connector

• Walkthrough: Integrate REST API claims exchanges in your Azure AD B2C user journey as an orchestration step
• Secure your API Connector
• Reference: RESTful technical profile