5. Understanding OAuth
So far, you’ve learned how the authentication engine of SharePoint
behaves when authenticating users and roles in a claims-based world.
What about SharePoint apps? Every app has a security principal of its own, called the app
principal, and whenever a SharePoint app needs to consume a SharePoint
site, an authentication and authorization process based on the OAuth
protocol takes place.
OAuth is the protocol that defines how to manage all the phases for
authenticating an app against a remote repository of data and a remote
API, as well as how to authorize that app to perform exactly a
well-defined set of operations. An open protocol, OAuth authenticates
apps and enables secure API authorization from desktop and web
applications through a standard, web-based technique.
Nowadays, every web application provides some content and features
to authenticated users. Think about SkyDrive, Flickr, Facebook,
LinkedIn, and similar sites. Each requires users to authenticate by
providing credentials and allows authenticated users to manage their
personal data. Take SkyDrive as an example. You can log into SkyDrive
using your Microsoft Account; you can upload content, share content
with others, and read content shared with you by someone else.
Moreover, you can use a Windows Store app, running within a Windows 8
tablet PC, to read or write files stored on your SkyDrive storage. The
same thing could happen using an iPhone, an iPad, or any other device
capable of consuming the APIs published by SkyDrive. Furthermore,
suppose you want to share your photos stored on SkyDrive with external
services, such as an external photo-printing service. Usually, when you
need to share your content with someone else or with an external app,
you should not share your user credentials with any of the apps or
users with whom you share your content. In fact, if you were to share
your credentials, those users or external apps would have exactly the
same rights and capabilities you would have for your own data,
including the capability to delete your files, change your permissions,
and even change your password. Of course, this would be too much. On
the contrary, you usually authorize external users or apps to do
something against your own data, keeping you as the only owner of that
data and providing to the third parties only those permissions that are
effectively required, usually for a limited period of time. For
example, think again about the photo-printing service. You would
probably allow an external photo-printing service to access your photos
on SkyDrive only for reading, and perhaps for only half an hour—just
enough time to download and print the photos. But how is it possible to
share this content with third-party apps without sharing you user
credentials, and with imposed time limits?
In SharePoint 2013, whenever a SharePoint app wants to access
content related to a site or a specific user, the authentication and
authorization engine works as illustrated in the schema in Figure 27.
When SharePoint 2013 begins to authenticate an incoming request, it
first looks to see if the incoming request contains a SAML token with a
user identity. If SharePoint finds a SAML token, it can then assume
that the incoming request was initiated by an end user, not by an app.
Once it finds a SAML token, SharePoint 2013 then inspects the target
URL of the incoming request to see whether it references a standard
SharePoint site or a child site associated with a specific app. If the
incoming request targets a standard site, SharePoint 2013 handles
authentication and authorization tasks as described in previous
sections. If the incoming request targets an app web, SharePoint 2013
initializes the call context with both a user identity and an app
identity.
When an incoming request does not contain a SAML token, SharePoint
2013 knows that a user did not initiate the request. In this scenario,
the SharePoint 2013 authentication pipeline inspects the incoming
request to see if it contains a security token identifying a developer
or a hosted app. Once SharePoint 2013 finds a security token
identifying an app, it sets up a call context with the app identity,
and optionally the user identity as well.
While invoking the CSOM or the new REST APIs, SharePoint will expect
and validate the security token, and will provide access to content and
APIs according to the permissions provided to the target app, and to
the user for which the app is acting.
Internally, the OAuth protocol uses an app ID, which uniquely
identifies every app, as well as an app shared secret, which allows
every app to communicate securely with the target service provider or
API, being able to secure communication and authenticate against the
target service provider or API as a specific app. When the service
provider, which could be SharePoint 2013, authorizes the app to do
something, or does not authorize the app to do something, it evaluates
the authorization rules both of the app and of the current end user. If
both of them have the rights for the APIs that are requested, then the
result is consent; otherwise; it will be a denial.
You can create an
app ID or client ID and a shared secret, using the Seller Dashboard for
the Office Store (if you are using Microsoft Office 365), or using some
dedicated administrative pages (if the app targets an on-premises
environment). In both cases, SharePoint 2013 uses OAuth in conjunction
with Windows Azure ACS.
Remember, however, that SharePoint 2013 uses OAuth only for
authentication and authorization of apps and for consuming the CSOM.
All the other authentication and authorization techniques ignore the
OAuth protocol and maintain their classic way of working.
6. Configuring server-to-server apps
Sometimes, while defining the security context of an app that will
be used on-premises, you may not want to define an app ID and an app
shared secret. Instead, you would prefer to trust an app, without
relying on Windows Azure ACS, OAuth, and so on. Luckily, there is a
suitable option that allows working in a high-trust, or
server-to-server (S2S), configuration. This configuration involves
sharing between the app and the target SharePoint farm of an X.509
certificate, which will be used to secure and authenticate the
communication between SharePoint and the target app. To configure the
S2S scenario, follow these steps:
-
Access the SharePoint 2013 management interface using a user account
that is a member of the administrators of the target machine, as well
as a user that has been configured as a shell admin for SharePoint,
using the Add-SPShellAdmin command.
-
Verify that the User Profile service is installed and at least started on one of the application servers in the farm.
-
Verify that the App Management service is installed and started in the current farm.
-
Create or obtain the .cer file corresponding to the X.509
certificate you want to use for the high-trust configuration between
SharePoint 2013 and the external app.
-
If you want to manually generate the certificate from scratch, you can use the following syntax:
makecert.exe -r -pe -n "CN={Name}" -b {StartDate} -e {EndData} -ss my
-sr localMachine -sky exchange
-sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12 file.cer
where the -r argument instructs the tool to create a self-signed certificate. The -pe argument marks the private key as exportable. The -b and -e arguments define the start and end dates of validity of the target certificate. The -ss and -sr arguments specify storing the certificate in the personal store of the local machine. The -sky argument with a value of exchange instructs the tool to create a certificate with message-exchange capabilities (signature and encryption). Last, the -sp and -sy
arguments declare the kind of CryptoAPI provider that will be used. If
you want, you can also use IIS for creating a self-signed certificate,
instead of using the makecert command-line tool.
-
Start the SharePoint management shell or the Windows PowerShell ISE, and import the SharePoint 2013 cmdlets.
-
Load the .cer file related to the X.509 certificate that you will
use for the high-trust scenario and invoke the following cmdlet:
$certificate = New-Object
System.Security.Cryptography.X509Certificates.X509Certificate2(
"{CERFilePath}")
{CERFilePath} is the path of the .cer file related to the X.509 certificate file to use.
-
Execute the following PowerShell commands:
$appId = "{AppID}"
$spweb = Get-SPWeb "{AppURL}"
$realm = Get-SPAuthenticationRealm -ServiceContext $spweb.Site
$fullAppIdentifier = $appId + '@' + $realm
New-SPTrustedSecurityTokenIssuer -Name "{FriendlyName}"
-Certificate $certificate -RegisteredIssuerName $fullAppIdentifier
The {AppID} argument is
the lowercase ID that identifies the app to trust, and it can be read
from the app creation wizard when you create a new provider-hosted app.
The {AppURL} argument is the URL of the app on the target server. {FriendlyName} is a friendly name that will be used to identify the high-trust relationship.
-
Register the app within the App Management service by using the following PowerShell command:
$appPrincipal = Register-SPAppPrincipal -NameIdentifier
$fullAppIdentifier -Site $spweb -DisplayName "{DisplayName}"
{DisplayName} will be the name representing the high-trust app in SPCA.
-
Configure explicit permission for the target app, using the following cmdlet:
Set-AppPrincipalPermission -appPrincipal $appPrincipal -site $web
-right {Level} -scope {Scope}
-
The arguments {Level} and {Scope} define the permissions .
After
completing these steps, you will be ready to execute you SharePoint
app, which will be a provider-hosted app running in an on-premises
environment. Every authentication and authorization request between
SharePoint 2013 and the app configured as high trust will be based on
the just-defined X.509 certificate.
