App Authentication
Note that some of the public documentation on TechNet and MSDN uses the terminology app authentication to include both authentication of the app by a trusted STS and
authorization of both the app and the associated user when the app
requests access to a secured SharePoint resource. Administrators should
be aware that the first part of the process is very similar to the
claims authentication of a user, while the latter part is the OAuth
portion of the process. In other words, OAuth is an authorization
protocol, but in some ways it is very similar to user authentication.
Once users are authenticated, the next step is to authorize them, as
the goal is to provide users with access to resources. Likewise with
the app, app authentication should be followed by app authorization, as
the goal is to provide the app with access to SharePoint content.
App authentication is required when an external
component of an app needs access to SharePoint resources — for example,
a SharePoint Store app or an app catalog app, such as a web server that
is located on the intranet or the Internet, attempts to access a
secured SharePoint resource. For instance, an app that includes a
component that runs in Windows Azure is an external app. App
authentication enables a new set of functionality and scenarios that
can be achieved by allowing an app to include data from SharePoint
resources in the results that the app processes and displays for users.
To provide the app access to SharePoint
resources, SharePoint must perform app authentication. SharePoint 2013
must be explicitly configured to allow external app functionality
access to resources. Specifically, this includes the following:
1. SharePoint
needs to verify the identity of the app, and the user on whose behalf
the app is acting. SharePoint needs to trust the app, which is
accomplished by establishing a trust with the app’s STS. This trust is
established using the PowerShell cmdlet New-SPTrustedSecurityTokenIssuer.
2. SharePoint
needs to verify that the app has the appropriate permissions for the
type of access being requested. The app developer requests the
permissions it requires, and those permissions are granted at
installation. By default, you must be a site owner or tenant
administrator to install an app. An app can also be granted permissions
explicitly by a site owner or tenant administrator. Once the trust is
established, the next step is to register the app with the Application
Management service, and then configure app permissions. This is
accomplished using the Register-SPAppPrincipal cmdlet, and then the Set-AppPrincipalPermission
cmdlet to assign the permission. Therefore, the app requests access
using the following permissions: the permissions granted at
installation, the permissions associated with the user on whose behalf
the app is acting, and those explicitly granted using the Set-AppPrincipalPermission cmdlet.
To summarize, app authentication requires the
SharePoint farm to be configured with an app authentication trust, the
app to be registered with the Application Management service, and app
permissions to be configured. Now let’s look at an example of app
authentication.
NOTE In
order for the SharePoint Store App Authentication example discussed in
the next section to work, your SharePoint farm must be configured to
host apps, and you must have an Office 365
account. The latter is necessary to access the ACS service and
establish an ACS trust. In general, there are two ways to configure
SharePoint 2013 for app authentication:
- Use an Office 365 subscription, which is
illustrated in the following SharePoint Store App Authentication
example, and configure SharePoint to trust ACS, as the app is using ACS
as its identity provider.
- Use the server-to-server (S2S)
authentication process, which is illustrated in the App Catalog App
Authentication example. This approach doesn’t require an Office 365
subscription or the use of ACS. It instead relies on a direct trust
relationship between the SharePoint farm and the app. S2S is discussed
in more detail in the Server-to-Server Authentication section.
SharePoint Store App Authentication
This example demonstrates installing an
app from the SharePoint Store, and using ACS as the STS. Your
on-premises SharePoint farm can use an external STS, such as ACS, and
in general SharePoint can be configured to trust many different token
providers. SharePoint needs to be configured to trust ACS, and the
example also illustrates how to grant explicit permissions to the app.
The OAuth process for granting the app access to SharePoint resources
is shown in Figure 1.
In order for the OAuth process to proceed successfully, you must
configure SharePoint 2013 to trust ACS. First, however, there are a few
PowerShell cmdlets that need to be run to establish the ACS trust and
register the app as discussed earlier in the previous section.
Step 1 is necessary whenever you want to
configure SharePoint to trust an external STS. In this example,
SharePoint is being configured to trust the ACS instance that
corresponds to your Office 365 account. You may be wondering why you
need an Office 365 subscription. Recall that app authentication
requires verifying the authenticity of both the app and the user. If
you already have an Office 365 tenant, then your identity is already
being verified using ACS as part of your subscription. App identity
verification is accomplished using ACS because the app has chosen to
use ACS as its identity provider STS. Steps 2 and 3 complete the app
authentication process by registering the app with the Application
Management service and explicitly assigning permissions to the app.
1. This step configures SharePoint to trust ACS. From the SharePoint 2013 Management Shell, execute the
New-SPTrustedSecurityTokenIssuer cmdlet:
New-SPTrustedSecurityTokenIssuer
–MetadataEndpoint "<Metadata endpoint URL of ACS>"
–IsTrustBroker –Name "ACS"
The value for "<metadata endpoint URL of ACS>" is https://accounts.accesscontrol.windows.net/metadata/json/1/?realm=<contextID property of your Office 365 subscription>. This metadata endpoint URL value and the value of your "<contextID property of your Office 365 subscription>" are discussed in the document “sps-2013-config-one-way-hybrid-environment.docx,” which you can download from http://www.microsoft.com/en-us/download/details.aspx?id=35593.
2. Now you register the app. From the SharePoint 2013 Management Shell, execute the
Register-SPAppPrincipal
cmdlet. The <app principal name> is based on your Office 365
tenant, and the value is based on two different IDs: the context ID and
the app principal ID. This information is determined using Microsoft
Online Services PowerShell, and it is fully documented in
“sps-2013-config-one-way-hybrid-environment.docx.”
$spsite = Get-SPSite "https://<url_of_site>"
$appPrincipal = Register-SPAppPrincipal
-NameIdentifier <app principal name> -Site $spsite
-DisplayName "My Office 365 App"
3. Finally, you assign permissions using the
Set-AppPrincipalPermission
cmdlet. This cmdlet can be used to both add and change app permissions,
and it can be repeated multiple times to configure the app with the
necessary permissions:
$spsite = Get-SPSite "https://<url_of_site>"
Set-AppPrincipalPermission -appPrincipal $appPrincipal
-site $spsite
-right <Level> -scope <Scope>
The <Level> parameter options include Read, Write, Manage, or FullControl. The <Scope> parameter values include Farm, Site collection, SharePoint Online, Web, Documents, List, or Library.
Now that the app authentication has been configured, the following steps walk through the OAuth process for this example:
1. An app has
been installed to the SharePoint farm from the SharePoint Store. The
user opens a SharePoint page in the browser that renders content from
the app that was previously installed. The app is hosted on the
Internet and uses ACS as its trust broker (IdP STS). Because the app is
requesting SharePoint resources, SharePoint needs to perform app
authentication. SharePoint must obtain a context token that it can send
to the app. The context token provides “context” about the app’s
request, including current user, SharePoint website, etc. SharePoint
requests ACS to create and sign a context token, as it is the app’s
IdP, and SharePoint has been configured to trust ACS. The context token
is used later in the process to request an access token.
2. ACS
authenticates the user via the Office 365 subscription information,
verifies the app identity, and issues a signed context token to the
SharePoint STS. The context token is digitally signed with a client
secret that is known only by ACS and the app (the app owner receives
the client secret value when the app is registered in the store). The
SharePoint STS receives the context token, which contains information
about the app and the user.
3. Once
received by the SharePoint STS, SharePoint attempts to render the web
page in the browser, which includes an iframe that references the app
server URL. As part of rendering the page, it passes the context token
to the iframe.
4. Because the
iframe references the URL of the app server, the iframe causes the
browser to request a page from the app server, and the context token is
included as part of the request sent to SharePoint Store app server.
5. The app
server receives the signed context token. It validates the token’s
signature using the client secret. Because the client secret is known
only by the app and ACS, the app knows it is a valid SharePoint
request. The client secret and the client ID (assigned when the app is
registered) values represent the app credentials. The app passes its
credentials to ACS as part of the request for an access token, and it
subsequently receives an access token from ACS. The access token
authorizes the app access to specific SharePoint resources for a
specific duration. This token can be cached, which alleviates multiple
ACS requests each time it needs SharePoint resources, or it can be
configured to make a new request each time.
6. The
SharePoint Store app server sends the OAuth access token and the
resource request to the SharePoint 2013 server. This request, sent via
the HTTP authorization header, can be for a web service call or a
client-side object model (CSOM) request.
7. The
SharePoint server authorizes access to the content and returns the
requested information to the app server. Depending on the app security
model, the appropriate combination of app permissions and user
permissions are used to determine whether the app has the necessary
permissions to access the SharePoint resources being requested.
8. The app
server renders the iframe contents, which satisfies the user’s request
for the SharePoint page. This completes the process.
You might need to review the process a couple of times because it is quite involved, but it will be worth the effort.
