Use Single-Tenant server-to-server authentication

The single-tenant server-to-server scenario typically applies for enterprise organizations who have multiple Common Data Service environments using Active Directory Federation Services (AD FS) for authentication. However, it can also be applied by environments when the application won't be distributed to other environments.

An enterprise can create a web application or service to connect to any Common Data Service environments associated with a single Azure Active Directory (AD) tenant.

Differences from multi-tenant scenario

Creating a web application or service for a single-tenant server-to-server authentication is similar to that used for a multi-tenant organization but there are some important differences.

  • Because all the organizations are in the same tenant, there is no need for a tenant admin to grant consent for each organization. The application is simply registered once for the tenant.

  • You have the opportunity to use certificates rather than keys if you prefer.

In the See also section at the end of this article, there are links to information on upgrading a single-tenant application to multi-tenancy.

Requirements

To create and test a single-tenant application that uses server-to-server (S2S) authentication you will need:

  • An Azure AD tenant to use when registering the provided sample application.
  • A Common Data Service subscription that is associated with the Azure AD tenant.
  • Administrator privileges in the Azure AD tenant and D365 organization.

Azure application registration

To create an application registration in Azure AD, follow these steps.

  1. Navigate to https://admin.microsoft.com and sign in, or from your D365 organization web page select the application launcher in the top left corner.
  2. Choose Admin > Admin centers > Azure Active Directory
  3. From the left panel, choose Azure Active Directory > App registrations (Preview)
  4. Choose + New registration [image]
  5. In the Register an application form provide a name for your app, select Accounts in this organizational directory only, and choose Register. A redirect URI is not needed for this walkthrough and the provided sample code.
  6. On the Overview page, select API permissions [image]
  7. Choose + Add a permission
  8. In the Microsoft APIs tab, choose Dynamics CRM
  9. In the Request API permission form, select Delegated permissions, check user_impersonation, and select Add permissions [image]
  10. On the API permissions page below Grant consent, select Grant admin consent for "org-name" and when prompted choose Yes [image]
  11. Select Overview in the navigation panel, record the Display name, Application ID, and Directory ID values of the app registration. You will provide these later in the code sample.
  12. In the navigation panel, select Certificates & secrets
  13. Below Client secrets, choose + New client secret to create a secret
  14. In the form, enter a description and select Add. Record the secret string. You will not be able to view the secret again once you leave the current screen.

Application User creation

To create an unlicensed "application user" in your Dynamics 365 organization, follow these steps. This application user will be given access to your organization's data on behalf of the end user who is using your application.

  1. Navigate to the Azure Active Directory admin center
  2. In the left navigation panel, choose Users
  3. Select + New user
  4. In the User form, enter a name and username for the new user and select Create. Make sure the username contains the organization domain URL of your D365 tenant (i.e., someuser@myorg.onmicrosoft.com). You can exit Azure AD now.
  5. Navigate to your D365 organization
  6. Navigate to Settings > Security > Users
  7. Choose Application Users in the view filter
  8. Select + New
  9. In the New User form, enter the required information. These values must be identical to those values for the new user you created in the Azure tenant. [image]
  10. If all goes well, after selecting SAVE, the Application ID URI and Azure AD Object Id fields will auto-populate with their correct values
  11. Before exiting the user form, choose MANAGE ROLES and assign a security role to this application user so that the application user can access the desired organization data.

Important

When developing a real-world application using S2S, you should use a custom security role which can be stored in a solution and distributed along with your application.

Application coding and execution

Follow these steps to download, build, and execute the sample application. The sample calls the WebAPI to return a list of the top 3 accounts (by name) in the organization.

  1. Download the Visual Studio 2017 SingleTenantS2S sample.
  2. Update the App.config file with your app registration and server key values.
  3. Build and run the application.

Expected results

An OData response listing the names of the top 3 accounts in your D365 organization.

Example console output

Shown below is example console output obtained from a D365 organization that only had two accounts named "Test Account 1", and "Test Account 2".

{
"@odata.context":"https://crmue2.api.crm.dynamics.com/api/data/v9.1/$metadata#accounts(name)",
"@Microsoft.Dynamics.CRM.totalrecordcount":-1,
"@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded":false,

"value":[
{"@odata.etag":"W/\"4648334\"","name":"Test Account 1","accountid":"28630624-cac9-e811-a964-000d3a3ac063"},
{"@odata.etag":"W/\"4648337\"","name":"Test Account 2","accountid":"543fd72a-cac9-e811-a964-000d3a3ac063"}]
}

See also

Use Multi-Tenant Server-to-server authentication
Build web applications using Server-to-Server (S2S) authentication
How to: Sign in any Azure Active Directory user using the multi-tenant application pattern

List of figures

Figure: Azure AD app registration


[go back]

Figure: Azure AD app registration overview


[go back]

Figure: Setting app permissions


[go back]


[go back]

Figure: Adding a new application user in D365


[go back]