Build web applications using Server-to-Server (S2S) authentication

Applies to Dynamics 365 (online), version 9.x

This feature was introduced in December 2016 Update for Dynamics 365 (online).

Use server-to-server (S2S) authentication to securely and seamlessly communicate with December 2016 update for Dynamics 365 (online) with your web applications and services. S2S authentication is the common way that apps registered on Microsoft AppSource use to access the Dynamics 365 data of their subscribers.

S2S authentication means you don’t need to use a paid Dynamics 365 user license when you connect to Dynamics 365 tenants. There is no license fee for the special application user account you will use with S2S authentication. With S2S authentication a special Dynamics 365 unlicensed application user account is created and includes information about your application registered with Azure Active Directory (Azure AD). Rather than user credentials, the application is authenticated based on a service principal identified by an Azure AD Object ID value which is stored in the Dynamics 365 application user record. The Dynamics 365 application user is associated with a custom security role which controls the kinds of data and operations the application is allowed to perform.

All operations performed by your application or service using S2S will be performed as the application user you provide rather than as the user who is accessing your application. If you want your application to perform data operations on behalf of a specific user, such as the one who is interacting with your application, you can apply impersonation when the custom security role applied to your application service principal has the privileges required. More information: Impersonate another user

A web application or service which uses S2S authentication is responsible for controlling access to the data that it has access to. This is typically done using an OpenID Connect provider. More information: http://openid.net/connect/.

Server-to-Server authentication scenarios

There are two scenarios where you can apply S2S authentication.

Scenario Description
Multi-Tenant This is the most common scenario and the one which is used for apps distributed using Microsoft AppSource.

Each Dynamics 365 tenant is associated with an Azure AD tenant. Your web application or service is registered with your Azure AD tenant.

In this scenario any Dynamics 365 tenant can potentially use your multi-tenant application after they grant consent for the application to access data in their tenant.
Single-Tenant This scenario typically applies to December 2016 update for Dynamics 365 (online) organizations who want to develop apps for their own tenant and who don’t intend to distribute them to other Dynamics 365 organizations.

An enterprise can create a web application or service to connect to all the Dynamics 365 organizations for their tenant.

In this scenario, your web application or service will only be able to connect to Dynamics 365 organizations using the same Azure AD tenant.

Both scenarios have common elements but there are some differences. Since multi-tenant is the most common scenario, the Use Multi-Tenant Server-to-server authentication content will describe how you can use S2S in this scenario and include notes where the options for single-tenant configuration is different. Use Single-Tenant Server-to-server authentication will provide an overview of this scenario and refer to the procedures described in the multi-tenant S2S authentication content.

See also

Walkthrough: Multi-tenant server-to-server authentication
Use Single-Tenant Server-to-server authentication
Build web applications using Server-to-Server (S2S) authentication
Connect to Dynamics 365