In this article, you have learned that SharePoint 2013
supports external app authentication by using both OAuth and S2S
trusts. Although OAuth is primarily intended for use in the Office 365
environment, the S2S trust infrastructure was specifically designed to
work in on-premises farms with provider-hosted apps.
Using an S2S trust for external app authentication is similar to
OAuth in the sense that code in the remote web passes an access token
when calling to the SharePoint host environment. However, the manner in
which the access token is created and the parties involved are very
different.
One significant difference from using OAuth is that an S2S trust
does not require any communications with Windows Azure ACS or any other
authentication server in the cloud. The only servers involved in an S2S
trust are the web server that hosts the remote web and the web servers
of an on-premises SharePoint 2013 farm. Therefore, all of the servers
required with an S2S trust can all run within the same LAN or private
network.
A second significant difference involves authenticating the current
user. When using OAuth, the SharePoint host environment authenticates
the current user and then passes this user’s identity to the remote web
by using the context token.
Things work very differently when using an S2S trust. The SharePoint
host environment doesn’t pass the identity of the current user to the
remote web. In fact, the SharePoint host environment doesn’t pass a
context token at all. The context token, which is a central figure in
OAuth, doesn’t even exist in the authentication flow of an S2S trust.
When a provider-hosted app is configured to authenticate by using an
S2S trust, its remote web takes on the responsibility of authenticating
the current user independently of any user authentication that has
taken place in the SharePoint host environment. Once the remote web has
authenticated the current user, it can then create an access token that
contains both the app identity and the identity of the current user.
When using OAuth, the remote web must call to Windows Azure ACS to
acquire an access token. However, a provider-hosted app using an S2S
trust can create an access code on its own by using the TokenHelper class.
After the remote web for a provider-hosted app has created an S2S
access token, it can then pass the access token to the SharePoint host
environment when executing CSOM command or REST API calls. The
programming aspects of passing the access token string using the
Authentication header in a provider-hosted app by using an S2S trust
works the same way as it does when using OAuth.
Architecture of an S2S trust
The architecture of an S2S trust is based on a X.509 certificate
which contains a public/private key pair. The public and private keys
are used to perform asymmetric
encryption. The critical underlying concept is that the provider-hosted
app uses the private key to sign the access token. The SharePoint host
environment uses the public key to verify that the access token has
been created and signed by a party that possesses the private key.
This, in turn, makes it possible for the SharePoint host environment to
authenticate calls from a provider-hosted app that is configured to use
an S2S trust.
Figure 1
shows the high-level architecture of an S2S trust. Unlike a scenario
involving OAuth, the remote web does not need to communicate with
Windows Azure ACS to acquire access tokens. Instead, it is able to
create access tokens on its own which must be signed with the private
key. One important observation is that the remote web requires access
to the private key at runtime whenever it needs to create an access
token.
A second requirement for an S2S trust is that the hosting SharePoint
farm must be configured with a special type of secure token service
known as a trusted security token issuer.
You will learn how to configure a trusted security token issuer by
using a public key file and a Windows PowerShell script later in the
chapter.
Let’s follow the stages of the S2S authentication flow that are shown in Figure 1.
In stage 1, the user navigates to a SharePoint site and is prompted to
log on. When the user supplies a valid set of credentials and logs on,
the SharePoint host environment creates a SAML token to track the user’s identity. However, the identity of the user is never passed to a provider-hosted app using an S2S trust.
In stage 2, the user navigates to the Site Settings page and sees
the tile for a provider-hosted app which has been configured to use an
S2S trust. When the user clicks this tile, the SharePoint host
environment uses an app launcher to redirect the user to the start page
in the remote web.
When the SharePoint host environment redirects the user to the start
page of a provider-hosted app with an S2S trust, it passes many of the
same query string parameters as in an OAuth scenario such as the SPHostUrl
parameter. However, the SharePoint host environment does not pass a
context token. This means that the SharePoint host environment passes
nothing to indicate who the user is. This puts the responsibility on
the remote web to authenticate the user.
Stage 3 occurs after the user has been authenticated and there is a
need to create an access token. When code in the remote web creates an
access token by using the TokenHelper
class, it adds information into the access token about the identity of
the app and the identity of the current user. Next, the remote web then
must acquire the value of the private key file to sign the access
token. After the remote web has created and signed the access token, it
can pass the access token by using the Authorization header each time it executes a CSOM command or a REST API call.
In stage 4, the SharePoint host environment uses external
authentication to authenticate a call from a provider-hosted app that
is using the S2S trust. For this to work, the hosting SharePoint farm
must first be configured with a trusted security token issuer that is
based on the public key. During the external authentication process,
the SharePoint host environment inspects the access token and uses the
trusted security token issuer to verify its authenticity.
Configuring S2S trusts for Microsoft products
The infrastructure for configuring
S2S trusts within a SharePoint 2013 farm wasn’t just created
exclusively for custom app development. When configuring a SharePoint
2013 farm, it is sometimes necessary to create S2S trusts for Microsoft products such as Exchange
2013 and Workflow Manager. Configuring an S2S trust makes it possible
for these Microsoft products to call into the SharePoint host
environment with a distinct app identity and with a set of
preconfigured permissions.
