OAuth 2.0 in SharePoint 2013
What is OAuth?
It is Open standard for Authorization.
It provides resource owners to authorize third party users to their server
resources without sharing their credentials.
OAuth is an internet security protocol. It is popular in
Facebook, twitter etc.
Example, you have an Asp.NET application and you would like
to display google drive from your application. When user tries to open the
Asp.NET application which holds the contents of google drive, system will
prompt for login from google account, once the google authenticates, OAuth will
authorize the user to access the google drive resource.
Why OAuth?
OAuth provides client applications a 'secure delegated
access to server resources on behalf of a resource owner.
OAuth integrates the commonalities and adopts the best
practices of these other Web authorization protocols into a single open
standard.
Other reasons for using OAuth authorization:
Compatible with existing authorization methods
Flexibility to adjust to security needs of different sites
Extensible through different signing algorithms
Designed to work with mobile devices and desktop
applications
What is ACS (Windows
Azure Access Control Service)?
ACS is an Azure service that provides an easy way for you to
authenticate users to access your web applications and services without having
to add complex authentication logic to your code.
The following features are available in ACS:
·
Integration with Windows Identity Foundation
(WIF).
·
Support for popular web identity providers (IPs)
including Microsoft accounts (formerly known as Windows Live ID), Google,
Yahoo, and Facebook.
·
Support for Active Directory Federation Services
(AD FS) 2.0.
·
An Open Data Protocol (OData)-based management
service that provides programmatic access to ACS settings.
·
A Management Portal that allows administrative
access to the ACS settings.
For more information about ACS, see Access Control Service
2.0.
SharePoint must first be registered with Azure ACS and with
the App Management Service of the SharePoint farm. OAuth security token service (STS) is
Microsoft Azure Access Control Service (ACS). In contrast, the WS-Federation
STS and the Security Assertion Markup Language (SAML) passive sign-in STS are
primarily intended to issue sign-in tokens.
When we have to use
OAuth?
OAuth will be used only in low trust system. When the remote web app is off premise, then
we could use ACS authorization system in which ACS is the token issuer.
OAuth token is passes the flow to Authorize the request by
an app to access SharePoint resource also does the Authentication of apps in office
store.
How OAuth 2.0 Works
in SharePoint 2013:
1.
User logs in to SharePoint page from the page
where app is installed.
2.
SharePoint detects and finds that there is a
request from other URL. SharePoint requests context token from ACS.
SharePoint requests ACS to create context
token.
3.
ACS returns signed Context token to SharePoint.
The context token signed with client
secret.
4.
Developer receives context token from SharePoint
in the form of hidden iFrame.
5.
Browser posts Context token to app server.
6.
Client app then passes refresh token to get
access token.
7.
ACS returns OAuth access token to client.
8.
Client app makes CSOM/REST calls to SharePoint
site passing OAuth token
9.
SharePoint returns content to app
1.
Client app returns HTML to user device.
OAuth terminologies
What is a context
token?
A context token is specific to a configuration that uses
Microsoft Azure Access Control Service (ACS). The trusted ACS server signs and
issues the Context Token, when it receives request from App. Context token are
in JWT (JSON Web Token) format
Cache value will be
unique with following combination
UserNameId + "," + UserNameIdIssuer + "," + ApplicationId + "," + Realm
To retrieve
context token use below command in C#
SharePointContextToken contextToken =
TokenHelper.ReadAndValidateContextToken(contextTokenString,
Request.Url.Authority);
What is returned is
the following JSON object, which is a JWT token that contains a set of claims.
{
"aud":
"4c2df2aa-3d14-4d84-8a79-5a75135e98d0/localhost:44346@d341a536-1d82-4267-87e6-e2dfff4fa325",
"iss":
"00000001-0000-0000-c000-000000000000@d341a536-1d82-4267-87e6-e2dfff4fa325",
"nbf":
1365177964,
"exp":
1365221164,
"appctxsender":
"00000003-0000-0ff1-ce00-000000000000@d341a536-1d82-4267-87e6-e2dfff4fa325",
"appctx": "{\"CacheKey\":\"em1/saZohTOS4nOUZHXMb8QJgyNbkEO86TSe5j9WYmo=\",
\"SecurityTokenServiceUri\":\"https://accounts.accesscontrol.windows.net/tokens/OAuth/2\"}",
"refreshtoken":
"IAAAANc8bAVMWZceOsdfgsdfggbfm7oU_aM7D2qofUpQstMsdfgsdfgfYS0OtbZ-
eY9UQGvlYSl5kpPi913G1AwIVBMxoCux8-bhcCCiaGVo-vuFzrXetdhRGPftQdHh-
1rS5cvDuuQ_bw_mjySIyuHNGSavEs8HUgHY9BOVc3pTGZtZ_nS-
1NbDLYObjnznasdfasdfasdfQreLAeeOpVRY1PGsdfgsdfgOITA3BKhjJFz_40YJMubdHmY2OTS
nqwNnUe-rBBCtfvKt4xFWvdRzTzwfW",
"isbrowserhostedapp": "true"
}
You can now see that the context token contains the refresh
token as a base64 encoded value.
What are the claims
in the context token?
The following shows the properties for the context token.
aud Short for “audience”, means the
principal the token is intended for. The format is <client ID>/<target
URL authority>@<target realm>. Based on this information, you can
determine the client ID for your app and the realm. In an on-premise environment, there is
typically just one realm, and its identifier matches your farm ID. For Office 365, this is your tenant ID.
iss Short for “issuer”, this is the
principal that issued the token, in the form of <principal
ID>@<realm>. The principal ID
value 00000001-0000-0000-c000-000000000000 is ACS.
nbf Short for “not before”, this is the
number of seconds after January 1, 1970 (part of the JWT specification) that
the token starts being valid.
exp Short for “expires”, represents the
number of seconds after January 1, 1970 that the token stops being valid.
appctxsender The sender of the token in the form
<sender ID>@<realm>. The
value 00000003-0000-0ff1-ce00-000000000000 is the identifier for
SharePoint. For trivia:
ACS 00000001-0000-0000-c000-000000000000
Exchange 00000002-0000-0ff1-ce00-000000000000
SharePoint 00000003-0000-0ff1-ce00-000000000000
Lync 00000004-0000-0ff1-ce00-000000000000
Workflow 00000005-0000-0000-c000-000000000000
The realm will be the tenant ID for Office 365, or the farm
ID for your on-premise deployment.
appctx Contains two properties, CacheKey and SecurityTokenServiceUri.
CacheKey:
UserNameId + "," + UserNameIdIssuer +
"," + ApplicationId + "," + Realm
This is provided so that you can cache the value in a cookie
or in session to identify that the user has already authenticated.
SecurityTokenServiceUri:
The URL for Azure ACS where the token is to be
validated. The URL is
https://accounts.accesscontrol.windows.net/tokens/OAuth/2.
refreshtoken The contents of the refresh token that are
sent to Azure ACS.
isbrowserhostedapp Indicates if the request initiated from a
user interacting with the browser and not an app event receiver
What is an access
token?
If app want to talk to SharePoint /make a web service call
then app need Access token. App uses context token to request the access token.
ACS returns the access token to app which can be cached by the app that way App
doesn’t need to ask for the access token every time it talks back to
SharePoint. By default access tokens are good for few hours at a time. Each
access token is specific to the users account.
It is not recommended to store access token cookies, new
access token will be requested based on stored refresh token.
What is a refresh
token?
If app want to talk back to SharePoint there is a Refresh
token is inside the Context token which can be used to request an access by the
app. By default refresh tokens are good for one year. So the same refresh token
can be redeemed for new access token from ACS for about a year.
OAuth has content
owners- Who grants permission to content of site.
Client App- is
the remote app that need permission to one of the content in site.
Content server-
is the web server that runs the site with the content to be accessed.
Authentication
Server- that authenticates access to the server.
Windows Access
Control Service (ACS) - It acts as authentication server
ACS server must be trusted by content server.
Also ACS server must be trusted by client server.
There are 5 information’s to be register an app principle
How it works in
SharePoint Provider hosted App from Visual Studio?
Below code gives more details on how the oAuth request
process throw ACS.
TokenHelper class holds the code to access and passing the
tokens through SharePoint.
protected void Page_Load(object sender, EventArgs e)
{
// The following code gets the client context and Title property by using TokenHelper.
// To access other properties, you may need to request permissions on the host web.
var contextToken = TokenHelper.GetContextTokenFromRequest(Page.Request);
Response.Write(contextToken + "<br/>");
var hostWeb = Page.Request["SPHostUrl"];
using (var clientContext = TokenHelper.GetClientContextWithContextToken(hostWeb, contextToken, Request.Url.Authority))
{
clientContext.Load(clientContext.Web, web => web.Title);
clientContext.ExecuteQuery();
Response.Write(clientContext.Web.Title);
}
}
Note: Visual Studio wizard will create a temporary app
identity for your app automatically and register it with ACS and the App
Management Service of your SharePoint test website.
Storing the context token string in a
cookie is fine. But, a context token expires after 12 hours or so. You must be
ready to use the appredirect.aspx to get a new context token if you get an
expired token from a user's cookie.
Below are the process
of registering the App for accessing SharePoint remotely.
How to register a new App from SharePoint Site?
If you are not
marketing your app for SharePoint through the Office Store, you register the
app with AppRegNew.aspx. See below for both methods.
If you're going to use
your app in more than one SharePoint tenant or farm, you should use the Seller
Dashboard to register your app. There is separate process for registering app
through Office store.
Below is the URL for
registering a new App.
http://<SharePointWebsite>/_layouts/15/AppRegNew.aspx
How do I retrieve a
list of app principals?
You can retrieve a list of app principals from the following
page:
http://yourServerName/_layouts/15/appprincipals.aspx
In below mentioned path:
App Id (Client Id):
App Secret: passing client secret passed to ACS during
registration
Title: It is a title of your app.
App URI: is the SharePoint site URL
Redirect URI: to redirect back to the landing page when user
denies from SharePoint page.
In App Manifest,
<AppPrincipal>
<RemoteWebApplication ClientId=”5334343-334434h43-434344yu-43434343u433”
/>
</AppPrincipal>
Client Web of App web project will holds Client id and
client secret.
How do I retrieve app
registration information?
You can look up app registration information for an app that
you have registered. The lookup is at http://yourServerName/_layouts/15/appinv.aspx.
How do I use the
appredirect page in the URL?
You can use the app redirect page by URL-encoding, as
follows:
https://SharePointServerName/_layouts/15/appredirect.aspx?client_id=<the
app client Id>&redirect_uri=URL you want to redirect to.
Author,
Rakesh
