Set up a Multi-Geo sample application

When developing for a Multi-Geo tenant, it's important to understand the security model. Fortunately, the model used for a Multi-Geo tenant is the same as the model used for a regular tenant.

This article shows you how to configure the following sample applications:

• An application that can read and update profiles for all users using the Graph API
• An application that can read and update profiles for all users using the CSOM User Profile API
• An application that can discover the Multi-Geo configuration
• An application that can create and delete site collections and set tenant site collection properties

Read and update profiles for all users using the Graph API

As explained in the article Work with user profiles in a Multi-Geo tenant, the preferred model to use to read and update user profile properties is the Graph API. This section explains the permissions you must grant to your application to realize tenant-wide user profile reads and updates.

There is a long list of possible permissions that you can grant to an application defined in Azure AD, but for manipulating profiles, you can limit the permissions to the following.

The Microsoft Graph-based Multi-Geo samples use the Microsoft Authentication Library (MSAL) to connect with the Microsoft Graph on the v2 endpoint. Compared to ADAL, which connects by using the v1 endpoint, MSAL allows connection to the Microsoft Graph by using Microsoft accounts, Azure AD, and Azure AD B2C. The following instructions will help you set up your application for the v2 endpoint, but you can also use the "older" approach based on the v1 endpoints.

Register your application

1. To use application permissions against the Microsoft Graph, register your application at https://apps.dev.microsoft.com.

2. After you're signed in, choose Add an app, and then choose Add a new converged application.

3. Give your application a name, and then choose Create application.

4. The application configuration screen appears.

5. Generate a new password and make a note of it together with the application ID.

6. Choose Add Platform, and then choose Native application as the platform target because the application does not have a landing page.

7. Add the necessary Application Permissions. In this sample app, we have added the Sites.ReadWrite.All and User.ReadWrite.All application permissions.

8. Clear the Live SDK support check box.

9. Save your changes.

Consent to the application

1. In this sample, the User.ReadWrite.All and Sites.ReadWrite.All application permissions require admin consent in a tenant before they can be used. Create a consent URL like the following:

https://login.microsoftonline.com/<tenant>/adminconsent?client_id=<clientid>&state=<something>

2. Use the client ID from the registered app, and consent to the app from my tenant contoso.onmicrosoft.com; the URL looks like this:

https://login.microsoftonline.com/contoso.onmicrosoft.com/adminconsent?client_id=6e4433ca-7011-4a11-85b6-1195b0114fea&state=12345

3. Browse to the created URL and sign in as a tenant admin, and consent to the application. You can see that the consent screen shows the name of your application as well as the permission scopes you configured.

Read and update profiles for all users using the CSOM User Profile API

When using the CSOM API to manipulate profile properties, you do this only for the custom created properties because out-of-the-box properties are better handled via the Microsoft Graph API. For more information, see the article Work with user profiles in a Multi-Geo tenant.

From a permission point of view there are two modes:

• Using user credentials

  This requires setting up a ClientContext object by using the tenant admin URL and SharePoint Online admin credentials. Because there's only one Azure AD instance holding users, this implies that a SharePoint Online admin is the admin for all the geo locations.

  string tenantAdminSiteForMyGeoLocation = "https://contoso-europe-admin.sharepoint.com";
  
  using (ClientContext cc = new ClientContext(tenantAdminSiteForMyGeoLocation))
  {
      SecureString securePassword = GetSecurePassword("password");
      cc.Credentials = new SharePointOnlineCredentials("[email protected]", securePassword);
  
      // user profile logic
  }
  
  static SecureString GetSecurePassword(string Password)
  {
      SecureString sPassword = new SecureString();
      foreach (char c in Password.ToCharArray()) sPassword.AppendChar(c);
      return sPassword;
  }
  

• Using an app-only principal

  When using app-only, you must grant the created app principal full control for the http://sharepoint/social/tenant permission scope.

The following instructions show you how to use appregnew.aspx and appinv.aspx to register an app principal and consent to it.

Create the principal

1. Go to a site in your tenant (for example, https://contoso.sharepoint.com), and then call the appregnew.aspx page (for example, https://contoso.sharepoint.com/_layouts/15/appregnew.aspx).

2. On this page, choose the Generate button to generate a client ID and client secret.

3. Complete the remaining fields as follows:

• Title: Multi-Geo demo
• App Domain: www.localhost.com
• Redirect URI: https://www.localhost.com

Grant permissions to the created principal

The next step is granting permissions to the newly created principal. Because we're granting tenant-scoped permissions, this grant can only be done via the appinv.aspx page on the tenant administration site.

1. You can reach this site via https://contoso-admin.sharepoint.com/_layouts/15/appinv.aspx.

2. After the page is loaded, add your client ID, and then look up the created principal.

3. To grant permissions, you must provide the permission XML that describes the needed permissions. Because the UI experience scanner needs to be able to access all sites and uses search with app-only, it requires the following permissions:

<AppPermissionRequests AllowAppOnlyPolicy="true">
  <AppPermissionRequest Scope="http://sharepoint/social/tenant" Right="FullControl" />
</AppPermissionRequests>

4. When you choose Create, you are presented with a permission consent dialog. Choose Trust It to grant the permissions.

Use the principal in your code

After the principal is created and consented, you can use the principal's ID and secret to request access. The TokenHelper.cs class grabs the ID and secret from the application's configuration file.

string tenantAdminSiteForMyGeoLocation = "https://contoso-europe-admin.sharepoint.com";

//Get the realm for the URL.
string realm = TokenHelper.GetRealmFromTargetUrl(siteUri);

//Get the access token for the URL.  
string accessToken = TokenHelper.GetAppOnlyAccessToken(TokenHelper.SharePointPrincipal, siteUri.Authority, realm).AccessToken;

//Create a client context object based on the retrieved access token.
using (ClientContext cc = TokenHelper.GetClientContextWithAccessToken(tenantAdminSiteForMyGeoLocation, accessToken))
{
    // user profile logic
}

A sample app.config looks like this:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <!-- Use AppRegNew.aspx and AppInv.aspx to register client id with proper secret -->
    <add key="ClientId" value="[Your Client ID]" />
    <add key="ClientSecret" value="[Your Client Secret]" />
  </appSettings>
</configuration>

Discover the Multi-Geo configuration

The only supported API that you can use to discover the geo locations in a Multi-Geo tenant is the Graph API. This section explains the permissions you must grant to your application to discover Multi-Geo information.

There is a long list of possible permissions that you can grant to an application defined in Azure AD, but for reading Multi-Geo tenant configuration information, you can limit permissions to the following.

Use the Azure AD application creation steps as described in the Read/update profiles for all users section.

Create and delete site collections and set tenant site collection properties

Using the Microsoft Graph API

The Multi-Geo sites article provides more details about how to create group sites (also known as "modern" team sites) by using the Microsoft Graph API. In this section, we're only addressing the permissions. The following table lists the needed permissions.

The Microsoft Graph based Multi-Geo samples use the Microsoft Authentication Library (MSAL) to connect with the Microsoft Graph on the v2 endpoint. Compared to ADAL, which connects using the v1 endpoint, MSAL allows connection to the Microsoft Graph by using Microsoft accounts, Azure AD, and Azure AD B2C.

Use the Azure AD application creation steps as described in the Read/update profiles for all users section.

Using the CSOM Tenant API

Using the CSOM Tenant API is very similar to the previously described CSOM guidance; in fact, the guidance for using user credentials is identical. For using an app-only principal, the instructions are the same, but you must grant different permissions (tenant and full control).

<AppPermissionRequests AllowAppOnlyPolicy="true">
  <AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl" />
</AppPermissionRequests>

See also

• Microsoft Graph Developer Center
• Get access tokens to call Microsoft Graph
• Microsoft Graph documentation
• Graph Explorer
• App-only and elevated privileges in the SharePoint Add-in model
• OneDrive and SharePoint Online Multi-Geo