Adding a guest user to an Office 365 SharePoint site with JavaScript and Azure Functions

We recently had a project where we needed to invite external users to an Office 365 SharePoint Site automatically when a Microsoft Flow was triggered. So, how can you do that programmatically? Well, one solution is to use Microsoft Graph API which in our case was consumed from a node.js script. In this article, I will show you a few things to take into consideration in this scenario using as start point my previous story where I described the base structure (how to call the Microsoft Graph API from an Azure Function using node.js, resolving the authentication, Azure Function structure, dependencies, etc.).

Inviting the users

As mentioned above, the idea was to invite external users to an Office 365 SharePoint Site. This can be easily achieved by navigating to the site itself and share it manually with the users you want. However, in our scenario this needed to happen without human interaction. Here is where Microsoft Graph shows its magic.

One of the actions that can be performed using this service is inviting users. To do this, you have the Create Invitation API, grouped under Azure Active Directory. Basically, with this API you can create invitations for external users to your organization.

The Create Invitation API is a simple endpoint that accepts POST requests if you have at least the User.Invite.All privilege (User.ReadWrite.All and Directory.ReadWrite.All are also accepted as they are most privileged). You will need to send in the body of the request the user’s email address and the redirect URL (where the user will be redirected once the invitation is accepted). The following is a sample request’s options object showing all the information required.

var options = {
    method: 'POST',
    url: 'https://graph.microsoft.com/v1.0/invitations',
    headers: {
        'Authorization': 'Bearer ' + token,
        'content-type': 'application/json'
    },
    body: JSON.stringify({
        "invitedUserEmailAddress": userEmail,
        "inviteRedirectUrl": invitationRedirectUrl
    })
};

The response of this request will provide you with a inviteRedeemUrl property that contains the url that the user will need to navigate to in order to accept the invitation. In addition to that, you will have the user’s id inside the invitedUser property which can be used, for example, to add the new user to a group. The following is a sample response.

{
  "id": "7b92124c-9fa9-406f-8b8e-225df8376ba9",
  "inviteRedeemUrl": "https://invitations.microsoft.com/redeem/?tenant=04dc56ab-388a-4659-b527-fbec654300ea&user=7b92324c-9fa9-406a-8b8e-225df8376ba9&ticket=VV9dmiExBsfRIVNFjb8ITj9VXAd06Ypv4gTg%2f8PiuJs%3d&lc=1033&ver=2.0",

  ....

  "status": "Completed",
  "invitedUser":  [ {  "id": "243b1de4-ad9f-421c-a933-d55305fb165d" } ]
}

If you want to avoid sending the email by yourself, you can use the sendInvitationMessage property set to true, and even further, you can update the message’s body with the customizedMessageBody property inside invitedUserMessageInfo. The following is the same example as before, but this time sending the invitation email automatically.

var options = {
    method: 'POST',
    url: 'https://graph.microsoft.com/v1.0/invitations',
    headers: {
        'Authorization': 'Bearer ' + token,
        'content-type': 'application/json'
    },
    body: JSON.stringify({
        "invitedUserDisplayName": userDisplayName,
        "invitedUserEmailAddress": userEmail,
        "inviteRedirectUrl": invitationRedirectUrl,
        "sendInvitationMessage": true,
        "invitedUserMessageInfo": {
            "customizedMessageBody": "This is a custom body message"
        }
    })
};

Inviting users using Azure Functions

Now that we saw the Invitation API, let’s see the code being called in an Azure Function. The following is a sample implementation that will invite the user whose email and name are passed by parameter and will automatically send the email. Additionally, it will return the redeemURL and the new user’s id.

Inviting users to an Office 365 tenant as guest using Microsoft Graph API from an Azure Function

As you can see using Graph API from an Azure Function is really simple and doesn’t add too much overhead giving us a great tool for complex scenarios.

Giving access to a SharePoint site

Even when we have everything ready and configured using the portal, after running the script the first time, the guest users will get the following message.

After researching the issue, we found out that we needed to execute some PowerShell cmdlets instead of using the portal to configure the sharing capability because it’s currently not working via web (more information about this issue here).

To solve this issue, we need to use the Microsoft Online SharePoint PowerShell module, connect to our tenant and then update the tenant (using Set-SPOTenant) and the site (using Set-SPOSite) sharing capabilities to ExternalUserAndGuestSharing or Disabled as needed.

In summary, run the following commands to change the sharing capabilities of the SharePoint site enabling external users on the “/sites/public” but not on the root SharePoint site.

Import-Module 'C:\Program Files\SharePoint Online Management Shell\Microsoft.Online.SharePoint.PowerShell'
Connect-SPOService -Url https://{your-tenant}-admin.sharepoint.com
Set-SPOTenant -sharingcapability ExternalUserAndGuestSharing
Set-SPOSite https://{your-tenant}.sharepoint.com/sites/public -sharingcapability ExternalUserAndGuestSharing
Set-SPOSite https://{your-tenant}.sharepoint.com/ -sharingcapability Disabled

Updating the permissions

Now that everything is working as expected, we might want to review the permissions that the guest users will have. The default permissions let the users edit the SharePoint site, this includes the external ones. In our scenario, that wasn’t what we wanted, so we update the permissions to set everybody as site visitors instead of site members to restrict them to edit the site.

After doing that, the external users can navigate to the SharePoint site without issues and without being able to edit the site.

Summing up

Microsoft Graph API can be really useful in a lot of different scenarios and it’s super easy to consume. In addition to that, using node.js from an Azure Function to perform these kinds of scenarios feels like magic. I hope that this helps you.