|
| 1 | +--- |
| 2 | +title: REST API claims exchanges in B2C custom policy |
| 3 | +titleSuffix: Azure AD B2C |
| 4 | +description: An introduction to creating an Azure AD B2C user journey that interacts with RESTful services. |
| 5 | +services: active-directory-b2c |
| 6 | +author: msmimart |
| 7 | +manager: celestedg |
| 8 | + |
| 9 | +ms.service: active-directory |
| 10 | +ms.workload: identity |
| 11 | +ms.topic: conceptual |
| 12 | +ms.date: 03/23/2020 |
| 13 | +ms.author: mimart |
| 14 | +ms.subservice: B2C |
| 15 | +--- |
| 16 | + |
| 17 | +# Integrate REST API claims exchanges in your Azure AD B2C custom policy |
| 18 | + |
| 19 | +[!INCLUDE [active-directory-b2c-advanced-audience-warning](../../includes/active-directory-b2c-advanced-audience-warning.md)] |
| 20 | + |
| 21 | +The Identity Experience Framework, which underlies Azure Active Directory B2C (Azure AD B2C), can integrate with RESTful APIs within a user journey. This article shows how to create a user journey that interacts with a RESTful service using a [RESTful technical profile](https://identitydivision.visualstudio.com/defaultcollection/Identity%20CXP/_git/GTP?path=%2Fyoelh%2Fdocs%2Frest-api%2Frestful-technical-profile.md&version=GBmaster). |
| 22 | + |
| 23 | +Using Azure AD B2C, you can add your own business logic to a user journey by calling your own RESTful service. The Identity Experience Framework can send and receive data from your RESTful service to exchange claims. For example, you can: |
| 24 | + |
| 25 | +- **Validate user input data**. For example, you can verify that the email address provided by the user exists in your customer's database, and if not, present an error. |
| 26 | +- **Process claims**. If a user enters their first name in all lowercase or all uppercase letters, your REST API can format the name with only the first letter capitalized and return it to Azure AD B2C. |
| 27 | +- **Enrich user data by further integrating with corporate line-of-business applications**. Your RESTful service can receive the user's email address, query the customer's database, and return the user's loyalty number to Azure AD B2C. Then return claims can be stored in the user's Azure AD account, evaluated in the next orchestration steps, or included in the access token. |
| 28 | +- **Run custom business logic**. You can send push notifications, update corporate databases, run a user migration process, manage permissions, audit databases, and perform any other workflows. |
| 29 | + |
| 30 | + |
| 31 | + |
| 32 | +## Calling a RESTful service |
| 33 | + |
| 34 | +The interaction includes a claims exchange of information between the REST API claims and Azure AD B2C. You can design the integration with the RESTful services in the following ways: |
| 35 | + |
| 36 | +- **Validation technical profile**. The call to the RESTful service happens within a [validation technical profile](validation-technical-profile.md) of the specified [self-asserted technical profile](self-asserted-technical-profile.md), or a [verification display control](display-control-verification.md) of a [display control](display-controls.md). The validation technical profile validates the user-provided data before the user journey moves forward. With the validation technical profile, you can: |
| 37 | + |
| 38 | + - Send claims to your REST API. |
| 39 | + - Validate claims, and throw custom error messages that are displayed to the user. |
| 40 | + - Send back claims from the REST API to subsequent orchestration steps. |
| 41 | + |
| 42 | +- **Claims exchange**. A direct claims exchange can be configured by calling a REST API technical profile directly from an orchestration step of a [user journey](userjourneys.md). This definition is limited to: |
| 43 | + |
| 44 | + - Send claims to your REST API. |
| 45 | + - Validate claims, and throw custom error messages that are returned to the application. |
| 46 | + - Send back claims from the REST API to subsequent orchestration steps. |
| 47 | + |
| 48 | +You can add a REST API call at any step in the user journey defined by a custom policy. For example, you can call a REST API: |
| 49 | + |
| 50 | +- During sign-in, just before Azure AD B2C validates the credentials. |
| 51 | +- Immediately after sign-in. |
| 52 | +- Before Azure AD B2C creates a new account in the directory. |
| 53 | +- After Azure AD B2C creates a new account in the directory. |
| 54 | +- Before Azure AD B2C issues an access token. |
| 55 | + |
| 56 | + |
| 57 | + |
| 58 | +## Sending data |
| 59 | + |
| 60 | +In the [RESTful technical profile](restful-technical-profile.md), the `InputClaims` element contains a list of claims to send to your RESTful service. You can map the name of your claim to the name defined in the RESTful service, set a default value, and use [claims resolvers](claim-resolver-overview.md). |
| 61 | + |
| 62 | +You can configure how the input claims are sent to the RESTful claims provider by using the SendClaimsIn attribute. The possible values are: |
| 63 | + |
| 64 | +- **Body**, sent in the HTTP POST request body in JSON format. |
| 65 | +- **Form**, sent in the HTTP POST request body in an ampersand '&' separated key value format. |
| 66 | +- **Header**, sent in the HTTP GET request header. |
| 67 | +- **QueryString**, sent in the HTTP GET request query string. |
| 68 | + |
| 69 | +When the **Body** option is configured, the REST API technical profile allows you to send a complex JSON payload to an endpoint. For more information, see [Send a JSON payload](restful-technical-profile.md#send-a-json-payload). |
| 70 | + |
| 71 | +## Receiving data |
| 72 | + |
| 73 | +The `OutputClaims` element of the [RESTful technical profile](restful-technical-profile.md) contains a list of claims returned by the REST API. You may need to map the name of the claim defined in your policy to the name defined in the REST API. You can also include claims that aren't returned by the REST API identity provider, as long as you set the DefaultValue attribute. |
| 74 | + |
| 75 | +The output claims parsed by the RESTful claims provider always expect to parse a flat JSON Body response, such as: |
| 76 | + |
| 77 | +```json |
| 78 | +{ |
| 79 | + "name": "Emily Smith", |
| 80 | + |
| 81 | + "loyaltyNumber": 1234 |
| 82 | +} |
| 83 | +``` |
| 84 | + |
| 85 | +The output claims should look like the following: |
| 86 | + |
| 87 | +```xml |
| 88 | +<OutputClaims> |
| 89 | + <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" /> |
| 90 | + <OutputClaim ClaimTypeReferenceId="email" /> |
| 91 | + <OutputClaim ClaimTypeReferenceId="loyaltyNumber" /> |
| 92 | +</OutputClaims> |
| 93 | +``` |
| 94 | + |
| 95 | +To parse a nested JSON Body response, set the ResolveJsonPathsInJsonTokens metadata to true. In the output claim, set the PartnerClaimType to the JSON path element you want to output. |
| 96 | + |
| 97 | +```json |
| 98 | +"contacts": [ |
| 99 | + { |
| 100 | + "id": "MAINCONTACT_1", |
| 101 | + "person": { |
| 102 | + "name": "Emily Smith", |
| 103 | + "loyaltyNumber": 1234, |
| 104 | + "emails": [ |
| 105 | + { |
| 106 | + "id": "EMAIL_1", |
| 107 | + "type": "WORK", |
| 108 | + |
| 109 | + } |
| 110 | + ] |
| 111 | + } |
| 112 | + } |
| 113 | +], |
| 114 | +``` |
| 115 | + |
| 116 | + |
| 117 | +The output claims should look like following: |
| 118 | + |
| 119 | +```xml |
| 120 | +<OutputClaims> |
| 121 | + <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="contacts.0.person.name" /> |
| 122 | + <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="contacts.0.person.emails.0.email" /> |
| 123 | + <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="contacts.0.person.loyaltyNumber" /> |
| 124 | +</OutputClaims> |
| 125 | +``` |
| 126 | + |
| 127 | +## Security considerations |
| 128 | + |
| 129 | +You must protect your REST API endpoint so that only authenticated clients can communicate with it. The REST API must use an HTTPS endpoint. Set the AuthenticationType metadata to one of the following authentication methods: |
| 130 | + |
| 131 | +- **Client certificate** restricts access by using client certificate authentication. Only services that have the appropriate certificates can access your API. You store the client certificate in an Azure AD B2C Policy Key. Learn more about how to [secure your RESTful service by using client certificates](secure-rest-api.md#https-client-certificate-authentication). |
| 132 | +- **Basic** secures the REST API with HTTP basic authentication. Only verified users, including Azure AD B2C, can access your API. The username and password are stored in Azure AD B2C policy keys. Learn how to [secure your RESTful services by using HTTP basic authentication](secure-rest-api.md#http-basic-authentication). |
| 133 | +- **Bearer** restricts access using a client OAuth2 access token. The access token is stored in an Azure AD B2C policy key. Learn more about how to [secure your RESTful service by using Bearer token](secure-rest-api.md#oauth2-bearer-authentication). |
| 134 | + |
| 135 | +## REST API platform |
| 136 | +Your REST API can be based on any platform and written in any programing language, as long as it's secure and can send and receive claims as specified in [RESTful technical profile](restful-technical-profile.md). |
| 137 | + |
| 138 | +## Localize the REST API |
| 139 | +In a RESTful technical profile, you may want to send the current session's language/locale, and if necessary, raise a localized error message. Using the [claims resolver](claim-resolver-overview.md), you can send a contextual claim, such as the user language. The following example shows a RESTful technical profile demonstrating this scenario. |
| 140 | + |
| 141 | +```XML |
| 142 | +<TechnicalProfile Id="REST-ValidateUserData"> |
| 143 | + <DisplayName>Validate user input data</DisplayName> |
| 144 | + <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" /> |
| 145 | + <Metadata> |
| 146 | + <Item Key="ServiceUrl">https://your-app.azurewebsites.net/api/identity</Item> |
| 147 | + <Item Key="AuthenticationType">None</Item> |
| 148 | + <Item Key="SendClaimsIn">Body</Item> |
| 149 | + <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item> |
| 150 | + </Metadata> |
| 151 | + <InputClaims> |
| 152 | + <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" /> |
| 153 | + <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="emailAddress" /> |
| 154 | + </InputClaims> |
| 155 | + <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" /> |
| 156 | +</TechnicalProfile> |
| 157 | +``` |
| 158 | + |
| 159 | +## Handling error messages |
| 160 | + |
| 161 | +Your REST API may need to return an error message, such as "The user was not found in the CRM system." If an error occurs, the REST API should return an HTTP 409 error message (Conflict response status code). For more information, see the [RESTful technical profile](https://identitydivision.visualstudio.com/defaultcollection/Identity%20CXP/_git/GTP?path=%2Fyoelh%2Fdocs%2Frest-api%2Frestful-technical-profile.md&version=GBmaster&anchor=returning-error-message). |
| 162 | + |
| 163 | +This can only be achieved by calling a REST API technical profile from a validation technical profile. This allows the user to correct the data on the page and run the validation again upon page submission. |
| 164 | + |
| 165 | +An HTTP 409 response is required to prevent the processing of any subsequent validation technical profiles within this orchestration step. |
| 166 | + |
| 167 | +If you reference a REST API technical profile directly from a user journey, the user is redirected back to the relying party application with the relevant error message. |
| 168 | + |
| 169 | +## Publishing your REST API |
| 170 | + |
| 171 | +The request to your REST API service comes from Azure AD B2C servers. The REST API service must be published to a publicly accessible HTTPS endpoint. The REST API calls will arrive from an Azure data center IP address. |
| 172 | + |
| 173 | +Design your REST API service and its underlying components (such as the database and file system) to be highly available. |
| 174 | + |
| 175 | +## Next steps |
| 176 | + |
| 177 | +See the following articles for examples of using a RESTful technical profile: |
| 178 | + |
| 179 | +- [Walkthrough: Integrate REST API claims exchanges in your Azure AD B2C user journey as validation of user input](custom-policy-rest-api-claims-validation.md) |
| 180 | +- [Walkthrough: Add REST API claims exchanges to custom policies in Azure Active Directory B2C](custom-policy-rest-api-claims-validation.md) |
| 181 | +- [Secure your REST API services](secure-rest-api.md) |
| 182 | +- [Reference: RESTful technical profile](restful-technical-profile.md) |
0 commit comments