Edit

Authorization considerations for tenants hosted in the Germany, China or US Government environments

  • Article

When your Office 365 tenant is hosted in an specific environment like the Germany, China or US Government environments then you'll need to take this in account when you're developing against your tenant.

Applies to: Office 365 hosted in the Germany, China or US Government environments

Important

Using Azure ACS (Access Control Services) for SharePoint Online has been retired as of November 27th 2023, checkout the full retirement announcement to learn more. Using Azure ACS outside of the context of SharePoint was already retired on November 7th, 2018 and is end-of-life now.

Retirement means that the feature will not get any new investments, but it's still supported. End-of-life means that the feature will be discontinued and is no longer available for use.

Introduction

Microsoft has specific Office 365 deployments in Germany, China and for US Government to fulfill the specific regulations for those areas. Below links provide more context:

If you are a developer targeting applications for SharePoint Online hosted in these environments then you'll need to take in account that these environments have their own dedicated Azure AD authentication endpoints that you as developer need to use. Below chapters explain how do use these dedicated endpoints for the typical SharePoint Online customization options.

Using Azure AD to authorize

Azure AD endpoints

When your Azure AD application needs to authorize it needs to use the correct endpoint. Below table describes the endpoints to use depending on where your Azure AD application has been defined:

Environment Endpoint
Production https://login.windows.net
Germany https://login.microsoftonline.de
China https://login.chinacloudapi.cn
US Government https://login.microsoftonline.us

Using PnP to authorize using Azure AD

The PnP AuthenticationManager offers an easy way to obtain an SharePoint ClientContext object when you're using an Azure AD application. The impacted methods have been extended with an optional AzureEnvironment enum

/// <summary>
/// Enum to identify the supported Office 365 hosting environments
/// </summary>
public enum AzureEnvironment
{
    Production=0,
    PPE=1,
    China=2,
    Germany=3,
    USGovernment=4
}

Below snippet shows an app-only authorization, notice the last parameter in the GetAzureADAppOnlyAuthenticatedContext method:

string siteUrl = "https://contoso.sharepoint.de/sites/test";
string aadAppId = "079d8797-cebc-4cda-a3e0-xxxx"; 
string pfxPassword = "my password";
ClientContext cc = new AuthenticationManager().GetAzureADAppOnlyAuthenticatedContext(siteUrl, 
			aadAppId, "contoso.onmicrosoft.de", @"C:\contoso.pfx", pfxPassword, AzureEnvironment.Germany);

Another snippet is showing an interactive user login using the GetAzureADNativeApplicationAuthenticatedContext method:

string siteUrl = "https://contoso.sharepoint.de/sites/test";
string aadAppId = "ff76a9f4-430b-4ee4-8602-xxxx"; 
ClientContext cc = new AuthenticationManager().GetAzureADNativeApplicationAuthenticatedContext(siteUrl, 
			aadAppId, "https://contoso.com/test", environment: AzureEnvironment.Germany);

Using Azure ACS to authorize your SharePoint add-in

When you create SharePoint add-ins they'll typically low-trust authorization which depends on Azure ACS as descrived in Creating SharePoint Add-ins that use low-trust authorization.

Azure ACS endpoints

Environment Endpoint prefix Endpoint
Production accounts accesscontrol.windows.net
Germany login microsoftonline.de
China accounts accesscontrol.chinacloudapi.cn
US Government accounts accesscontrol.windows.net

Using this model the ACS endpoint url to use is formatted like https:// + endpoint prefix + / + endpoint. So the URL for production will be https://accounts.accesscontrol.windows.net, the one for Germany will be https://login.microsoftonline.de.

Updating tokenhelper.cs in your applications

When you want to do SharePoint add-in authorization using Azure ACS then you're using tokenhelper.cs (or tokenhelper.vb). The default tokenhelper class will have hardcoded references to the Azure ACS endpoints and methods to acquire the ACS endpoint as shown below:

...

private static string GlobalEndPointPrefix = "accounts";
private static string AcsHostUrl = "accesscontrol.windows.net";

...

Tokenhelper.cs updates for Germany

Update the static variables GlobalEndPointPrefix and AcsHostUrl to the Germany Azure ACS values.

...

private static string GlobalEndPointPrefix = "login";
private static string AcsHostUrl = "microsoftonline.de";

...

Tokenhelper.cs updates for China

Update the static variables GlobalEndPointPrefix and AcsHostUrl to the China Azure ACS values:

...

private static string GlobalEndPointPrefix = "accounts";
private static string AcsHostUrl = "accesscontrol.chinacloudapi.cn";

...

Using PnP to authorize your add-in using Azure ACS

The PnP AuthenticationManager offers an easy way to obtain an SharePoint ClientContext object when you're using Azure ACS to authorize. The impacted methods have been extended with an optional AzureEnvironment enum

/// <summary>
/// Enum to identify the supported Office 365 hosting environments
/// </summary>
public enum AzureEnvironment
{
    Production=0,
    PPE=1,
    China=2,
    Germany=3,
    USGovernment=4
}

Below snippet shows an app-only authorization, notice the last parameter in the GetAppOnlyAuthenticatedContext method:

string siteUrl = "https://contoso.sharepoint.de/sites/test";
string acsAppId = "955c10f2-7072-47f8-8bc1-xxxxx"; 
string acsAppSecret = "jgTolmGXU9DW8hUKgletoxxxxx"; 
ClientContext cc = new AuthenticationManager().GetAppOnlyAuthenticatedContext(siteUrl, acsAppId, 
				acsAppSecret, AzureEnvironment.Germany);

See also