isabella232 / active-directory-nodejs-external-identities-api-connector-azure-function-validate

Node.js Azure Function for use with API connector to validate user attributes on external user self service sign-up.

page_type	languages	products	description	urlFragment
sample	javascript nodejs	azure-active-directory	A sample to demonstrate how to validating a sign-up using a Node.js Azure Function and API connectors	active-directory-nodejs-external-identities-api-connector-azure-function-validateb

External Identities self-service sign-up validation using Node.js Azure Function and API connector.

This sample demonstrates how to use API connectors to customize self-service sign-up of External Identities.

In particular, the sample demonstrates how to:

1. Limit external user sign-ups to only a particular federated Azure Active Directory tenant. In this example, it's a fictitious fabrikam.com.
2. Validate a user-provided value ('Job Title') against a validation rule.

For the API, an Azure Function HTTP trigger using Node.js is implemented with Basic authentication.

Contents

File/folder	Description
SingUpValidation/index.js	Sample source code for HTTP trigger.
.gitignore	Define what to ignore at commit time.
CHANGELOG.md	List of changes to the sample.
CONTRIBUTING.md	Guidelines for contributing to the sample.
README.md	This README file.
LICENSE	The license for the sample.

Key concepts

External Identities self-service sign-up enables you way to create custom experiences for external users like collaborators, partners, and guests to sign-up to to applications in your tenant for easy collaboration.

API connectors provide you with a way to further modify and extend sign-up flows by leveraging web APIs. This examples uses an API connector to limit sign-ups to only a specific tenant: fabrikam.com. This is easily modifiable in index.js. Further, the API connector is used to perform input validation on 'Job Title' by ensuring a user provides a value of at least 4 characters.

Prerequisites

Before you get started, make sure you have the following requirements in place:

• An Azure account with an active subscription. Create an account for free.
• A self-service sign-up user flow in an Azure AD tenant. Only use Azure AD
• Node.js, required by Windows for npm. Only Active LTS and Maintenance LTS versions. A version of Node.js 10 or 12.* are recommended.. Use the node --version command to check your version.
• The Azure Functions extension for Visual Studio Code.

Setting up your Azure Function

Steps to run locally

1. Clone the repository

git clone https://github.com/Azure-Samples/active-directory-nodejs-external-identities-api-connector-azure-function-validate

2. 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.
3. 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.)
4. 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.
5. 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 Local Function by right clicking on the function on the Azure Functions explorer.
6. To redeploy the local instance during testing, just repeat these steps.

Add authentication

Authentication is stored in environment variables, so they're not stored as part of the repository and should never be stored in checked in code. Read more about the local.settings.json file.

1. Create a local.settings.json file
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>"
  }
}

Specify a Username and Password. This will be what your Azure Function uses to authenticate incoming requests from Azure AD.

Deploy the application

1. Follow steps of this guide #1-7 to deploy your Azure Function to the cloud and get a live API endpoint URL.
2. Once deployed, you'll see a 'Upload settings' option. Select this. It will upload your environment variables onto the Application settings of the cloud.

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 a user flow to configure and enable the API connector.

API connector configuration

Your API connector configuration should look like the following:

• Endpoint URL is the Function URL you copied earlier.
• Username and Password are the Username and Passwords you defined as environment variables earlier.
• Select Job Title as a claim to send in addition to the two preselected claims.

Enable the API connector

In the API connector settings for your user flow, you can select the API connector to be invoked at either step:

• After signing in with an identity provider - if enabled for this step, the API connector will only allow users with an email ending in @fabrikam.com.
• Before creating the user - if enabled for this step, the API connector will only allow users with an email ending in @fabrikam.com and check whether 'Job Title' is of at least length 4. Note that Job Title has to be selected in User attributes for the user flow.

Customizing the Azure Function

This sample provides a quick way to get started using API connectors. By modifying the source code and leveraging all the capabilities of a web API you're used to, you'll be able to accomplish many more complex scenarios.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.