page_type	languages	products	description	urlFragment
sample	javascript nodejs	azure-active-directory	A sample to demonstrate how to use Arkose Lab's fraud and abuse protection in Azure AD B2C sign-up user flows.	active-directory-node-b2c-sign-up-user-flow-arkose

active-directory-node-b2c-user-flow-arkose

Contents

File/folder	Description
Assets/selfAsserted.html	Sample custom HTML and JS script file for user flow.
Assets	Contains UI/UX assets used by the user flows.
ArkoseAzureFunction	Sample source code for Node.js HTTP trigger.
README.md	This README file.
.gitignore	Define what to ignore at commit time.
CONTRIBUTING.md	Guidance on how to contribute to this repository.
LICENSE.md	The license for the sample.
SECURITY.md	The security notice for the sample.

Key Concepts

Arkose services are often used in authentication scenarios to protect against bots or other automated abuse. This sample demonstrates how to integrate an Azure AD B2C sign-up user flow with a Arkose service.

Key components:

• Arkose Labs - an fraud and abuse service for protecting against bots and other automated abuse.
• Azure AD B2C sign-up user flow - The sign-up experience that will be using the Arkose Labs service. Will utilize the custom HTML & JavaScript and API connectors to integrate with the Arkose service.
• Azure Functions - API endpoint hosted by you that works in conjunction with the API connectors feature. This API is responsible for doing the server-side validation of the Arkose session token.

This same pattern can be used with other API hosting and automated fraud protection services.

Get an API key pair for Arkose Labs

• Engage with Arkose Labs to acquire an account and public and private keys.
• You will receive a public key and a private key. The values of these are referred to as ARKOSE_PUBLIC_KEY and ARKOSE_PRIVATE_KEY in the sample code and this documentation. They correspond to keys used in client-side and server-side components.

Create a "ArkoseSessionToken" Custom Attribute

1. From the Azure Portal, go to Azure AD B2C
2. Select User Attributes
3. Select Add
4. Enter ArkoseSessionToken as the attribute Name
5. Create

Learn more about custom attributes.

Create a user flow

This can be either be a sign up and sign in or a just sign up or user flow. Either way, the Arkose will only be shown during sign up.

1. Follow these instructions. If using an existing user flow, note that user flows must be of the "Recommended (next-generation preview)" version type.
2. In the user flow settings, navigate to User attributes and select the ArkoseSessionToken claim.

Configure custom HTML, JavaScript, and Page Layouts

The Assets > selfAsserted.html file contains an HTML template with JavaScript (<script> tags) that will do three things:

• Load the Arkose Labs script, which renders the Arkose Labs widget and performs client-side Arkose validation.
• Hide the extension_ArkoseSessionToken input element and label, corresponding to the ArkoseSessionToken custom attribute, from the UI shown to the user.
• When a user completes the Arkose challenge, Arkose Labs verifies the user's response and generates a token. When this happens, the callback arkoseCallback in the custom JavaScript sets the value of extension_ArkoseSessionToken to the generated token value. This value will be submitted to the API endpoint as described in the "Create and deploy your API" section.

Read more about Arkose Labs client-side validation here.

Follow the instructions below to use this custom HTML and JS for your user flow.

Modify the selfAsserted.html page

Modify the Assets > selfAsserted.html file so that <ARKOSE_PUBLIC_KEY> matches the value you generated in the first step, which is used to load the Arkose Labs script for your account.

Host the HTML page

Host the html page on a CORS enabled web endpoint. For example, follow steps 2 and 3 of these instructions ("Create an Azure Blob storage account" and "Configure CORS").

If you have your own custom HTML, just copy and paste the <script> elements onto your HTML page.

Configure page layouts

1. From the Azure Portal, go to Azure AD B2C
2. Navigate to User flows and select your user flow
3. Select Page layouts
4. Select Local account sign up page layout
5. Toggle Use custom page content to "YES"
6. Paste the URI where your custom HTML lives in Use custom page content
7. Do the previous two steps for Social account sign up page layout if using social identity providers.

Enable JavaScript

1. From your user flow, go to Properties and select Enable JavaScript enforcing page layout (preview)

Learn more here.

Create and deploy your API

These steps assume you use Visual Studio Code, but deploying the Azure Function via the Azure Portal, terminal or command prompt, or any other code editor will also work.

Prerequisite: Install the Azure Functions extension for Visual Studio Code.

Run the API locally

1. Navigate to the Azure extension in Visual Studio code on the left navigation bar. You should see a 'Local Project' folder representing your local Azure Function.
2. Press F5 (or use the Debug > Start Debugging menu command) to launch the debugger and attach to the Azure Functions host. (This command automatically uses the single debug configuration that Azure Functions created.)
3. The Azure Function extension will automatically generate a few files for local development, install dependencies, and install the Function Core tools if not already present. These tools help with the debugging experience.
4. Output from the Functions Core tools appears in the VS Code Terminal panel. Once the host has started, Alt+click the local URL shown in the output to open the browser and run the function. You can also see the url of the locally-hosted function by right clicking on the function on the Azure Functions explorer.
5. To redeploy the local instance during testing, just repeat these steps.

Add environment variables

This sample protects the web API endpoint using HTTP Basic authentication.

Here, username and password are stored as environment variables so they're not stored as part of the repository. Read more about the local.settings.json file.

1. Create a local.settings.json file in your root folder
2. Copy and paste the below code onto the file:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "BASIC_AUTH_USERNAME": "<USERNAME>",
    "BASIC_AUTH_PASSWORD": "<PASSWORD>",
    "ARKOSE_PRIVATE_KEY": "<ARKOSE_PRIVATE_KEY>",
    "B2C_EXTENSIONS_APP_ID": "<B2C_EXTENSIONS_APP_ID>"
  }
}

The BASIC_AUTH_USERNAME and BASIC_AUTH_PASSWORD values are going to be the credentials used to authenticate the API call to your Azure Function. Choose your desired values.

The <ARKOSE_PRIVATE_KEY> is the server-side secret you generated in the Arkose Labs service. It's used to call the Arkose Labs server-side validation API to validate the value of the ArkoseSessionToken generated by the front-end.

THE <B2C_EXTENSIONS_APP_ID> is the application ID of the app used by Azure AD B2C to store custom attributes in the directory. You can find this application ID by navigating to App registrations, searching for b2c-extensions-app and copying the Application (client) ID from the Overview pane. Remove the - characters.

Deploy the application to the web

1. Follow steps of this guide #1-7 to deploy your Azure Function to the cloud. Copy the endpoint web URL of your Azure Function.
2. Once deployed, you'll see an 'Upload settings' option. Select this. It will upload your environment variables onto the Application settings of the App service. These application settings can also be configured or managed via the Azure portal.

To learn more about Visual Studio Code development for Azure Functions, see this.

Configure and enable the API connector

Follow the steps outlined in "Add an API connector" to create an API connector and enable it your user flow. The configuration should look like the below.

API connector configuration

Your API connector configuration should look like the following:

• Endpoint URL is the Function URL you copied earlier if the deployed Azure Function.
• Username and Password are the Username and Passwords you defined as environment variables earlier.

Enable the API connector

In the API connector settings for your user flow, select the API connector to be invoked at the Before creating the user step. This will invoke the API when a user hits 'Create' in the sign-up flow. The API will do a server-side validation of the ArkoseSessionToken value, which was is set by the callback of the Arkose widget arkoseCallback.