Add an API connector to a sign-up user flow

 

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

HTTP

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

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "objectId": "11111111-0000-0000-0000-000000000000",
 "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":"93fd07aa-333c-409d-955d-96008fd08dd9",
 "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.

 Important

If a claim does not have a value at the time the API endpoint is called, the claim will not be sent to the API. Your API should be designed to explicitly check and handle the case in which a claim is not in the request.

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

HTTP

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

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "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

HTTP

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

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "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":"93fd07aa-333c-409d-955d-96008fd08dd9",
 "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)

 Important

API connectors used in this step are in preview. For more information about previews, see Product Terms for Online Services.

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

HTTP

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

{
 "clientId": "231c70e8-8424-48ac-9b5d-5623b9e4ccf3",
 "step": "PreTokenApplicationClaims",
 "ui_locales":"en-US",
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "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.

 Note

The API is only invoked during an initial authentication. When using refresh tokens to silently get new access or ID tokens, the token will include the values evaluated during the initial authentication.

Example responses

Example of a continuation response

HTTP

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
}

Parameter	Type	Required	Description
version	String	Yes	The version of your API.
action	String	Yes	Value must be Continue.
<builtInUserAttribute>	<attribute-type>	No	Returned values can overwrite values collected from a user.
<extension_{extensions-app-id}_CustomAttribute>	<attribute-type>	No	The claim does not need to contain _<extensions-app-id>_, it is optional. Returned values can overwrite values collected from a user.

Example of a blocking response

HTTP

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",
}

Parameter	Type	Required	Description
version	String	Yes	The version of your API.
action	String	Yes	Value must be ShowBlockPage
userMessage	String	Yes	Message to display to the user.

End-user experience with a blocking response

Example of a validation-error response

HTTP

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."
}

Parameter	Type	Required	Description
version	String	Yes	The version of your API.
action	String	Yes	Value must be ValidationError.
status	Integer / String	Yes	Must be value 400, or "400" for a ValidationError response.
userMessage	String	Yes	Message to display to the user.

 Note

HTTP status code has to be "400" in addition to the "status" value in the body of the response.

End-user experience with a validation-error response

Best practices and how to troubleshoot

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.

 Important

Your endpoints must comply with the Azure AD B2C security requirements. Older TLS versions and ciphers are deprecated. For more information, see Azure AD B2C TLS and cipher suite requirements.

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.