Business Productivity

Importing Azure Active Directory users and groups into Alexa for Business Directory using AWS Lambda

Alexa for Business Directory enables customers to create contacts and address books that give their end users hands-free calling from Alexa devices in their office. Currently, Alexa for Business administrators enter contacts manually, create an address book, and then assign contacts to the address book. Using this method to create hundreds of contacts becomes impractical. In this blog, we demonstrate the ability to automate this functionality using several Alexa for Business and third party API calls to import user and groups from your Azure Active Directory.

Solution overview

This post describes the technical details on how to utilize AWS Lambda and the AWS SDK for JavaScript in Node.js to create a Lambda script to import users and groups as address books and contacts, from Azure Active Directory to the Alexa for Business Directory by using standard filter query parameters. Utilizing OAuth2 token authentication with AWS Secrets Manager, we can securely store the Azure application registration application id and client secret. OAuth2 allows for secure retrieval capability of data from Azure Active Directory to the Alexa for Business Directory. Finally with the use of AWS CloudWatch events, we can set the Lambda script to run on a schedule interval to run once a day or more.

The heavy lifting of creating the Lambda script has been done for you. You can access and download the script in the following GitHub repository. The total time to install this solution should be less than an hour.

Solution walkthrough

To automate import of Active Directory groups and contacts, you perform the following tasks.

  • Create a new registration in Azure Active Directory App registrations.
  • Create a new secret store in Secrets Manager to store the application (client) id and secret from the above step.
  • Create an IAM role for Lambda to have access to the Alexa for Business, Secret Manager and CloudWatch logs.
  • Import the Lambda script and configure the environment settings.
  • Create the CloudWatch event to run the Lambda function on an interval.
  • Perform verification to ensure the function is working properly.

NOTE: Please see the GitHub Repository for further information on the above steps as well as downloading the Lambda function.

Prerequisites

You should have the following prerequisites:

How it works

Figure 1 – The infrastructure for importing of Active Directory users and groups into Alexa for Business Directory.

The infrastructure for importing of Active Directory users and groups into Alexa for Business Directory.

The infrastructure for importing of Active Directory users and groups into Alexa for Business Directory.

Triggered by a CloudWatch event, the Lambda function will communicate with your Azure Active Directory service and port the data to Alexa for Business Directory. Specifically the Lambda function:

  • Authenticates with your Active Directory service using OAuth2.
    • If accessToken received, process request, otherwise fail.
      • applicationId and clientSecret can exist as environment variables in your lambda function or can be stored in AWS Secrets Manager. Recommend storing in AWS Secrets Manager.
  • Retrieves user and group information from your Active Directory service.
    • If search by User then search and get groups of each user.
    • If search by Group then search and get each user from group.
  • Searches if contact already exists in Alexa for Business.
    • If the contact exists, updates the contact.
    • If the contact does not exist, creates new contact.
  • Searches if address book exists in Alexa for Business.
    • If the address book exists, retrieves address book ARN.
    • If the address book does not exist, attempts to create it and retrieve the ARN.
    • If no address book name found, then uses default address book name.
  • Assigns contacts to an address book by group name or defined name.
  • Retrieves output errors, creates or updates contact and address books, and send it to CloudWatch logging.

NOTE: Always check your service quotas for Alexa for Business. Today you can have 25 address books, 100 contacts per address book, and a total of 10,000 contacts.

Here’s the detailed description of the Lambda function.

1. Authenticates with your Active Directory service using OAuth2.

Using the adal-node library along with an ApplicationId and ClientSecret retrieved from the Secrets Manager, the Lambda function authenticates via Oauth2 to an Active Directory Application returning an access token.

const context = new AuthenticationContext(authorityUrl);
context.acquireTokenWithClientCredentials(resource, appId, secret,
    function(err, data) {
        if (err) console.log(err, err.stack);     // an error occurred
        else  return data;			  // successful response
    });
);

2. Retrieves user and group information from your Azure Active Directory service.

Using the @microsoft/Microsoft-graph-client library along with a defined filter we first create a client connection, then we collect users and group information.

const client = Microsoft.Client.init({
	defaultVersion: '1.0',
	authProvider: (done) => {
		done(null, accessToken);
	}
});

Once we have the client connected using the access token, then we collect the user and group data.

client.api(path).filter(filter).get((err, result) => {
	if (err) console.log(err, err.stack);	//an error occurred
	else return result;			//successful response
});

3. Searches if contact already exists in Alexa for Business.

Searches contacts for the imported user.

alexaforbusiness.searchContacts(params, function(err, data) {
       if (err) console.log(err, err.stack); // an error occurred
       else     console.log(data);           // successful response
});

If the contact already exists, we then perform an update on the contact.

alexaforbusiness.updateContact(params, function(err, data) {
       if (err) console.log(err, err.stack); // an error occurred
       else     console.log(data);           // successful response
});

If the contact does not exist, we create the contact from the user.

alexaforbusiness.createContact(params, function(err, data) {
       if (err) console.log(err, err.stack); // an error occurred
       else     console.log(data);           // successful response
});

4. Searches if address book exists in Alexa for Business.

Searches address book names for the imported group name. If the address book name does exist, collect the data.

alexaforbusiness.searchAddressBooks(params, function(err, data) {
       if (err) console.log(err, err.stack); // an error occurred
       else     console.log(data);           // successful response
});

If the address book does not exist, create the address book.

alexaforbusiness.createAddressBook(params, function(err, data) {
       if (err) console.log(err, err.stack); // an error occurred
       else     console.log(data);           // successful response
});

If we did not have an address book name, use the defined default.

5. Assigns contacts to an address book by group name or defined name.

Assign our contact to the defined address book.

alexaforbusiness.associateContactWithAddressBook(params, function(err, data) {
       if (err) console.log(err, err.stack); // an error occurred
       else     console.log(data);           // successful response
});

6. Retrieves output errors, creates or updates contact and address books, and send it to CloudWatch logging.

An example output from CloudWatch logs

CloudWatch logging

The end result

Example of imported Address Books.

Alexa for Business Directory

Example of contacts associated within an Address Book.

Display of Alexa for Business Directory Contacts within an Address Book

Example of Contacts.

Display of Alexa for Business Contacts

Cleaning up

To avoid incurring future charges, delete the following resources.

  • Any Secrets Manager store entries
  • The CloudWatch Event entry
  • The Lambda function

Conclusion

In this post, we showed how you can use Lambda to import Azure Active Directory users by group into your Alexa for Business Directory automatically using CloudWatch Events. With this automation you can now manage contact and address book additions and updates in Alexa for Business Directory securely. IT administrators and anyone authorized to work with these resources can view the log output on the imports quickly and securely, through CloudWatch logging.

Additional Resources

You can navigate to the GitHub Repository that contains detailed instructions and the Lambda function that you need to automate Azure Active Directory user and group import into Alexa for Business Directory.

Community resources

Tutorials & Guides

Documentation