OAuth 2.0 in SharePoint 2013
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:
http://3.bp.blogspot.com/-RxgFIvWTfc0/VCuVR5QeVYI/AAAAAAAABCo/NWIWOWgYJ9k/s1600/OAuth.gif
http://3.bp.blogspot.com/-_f6t1mjjsis/VCuVfEKhKqI/AAAAAAAABC4/IHYMSVTVmmo/s1600/OAuth1.gif
http://4.bp.blogspot.com/-GV_BmktVRSM/VCuVaumcpsI/AAAAAAAABCw/EkYyXyuiHpU/s1600/OAuth2.gif
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:
https://SharePointServerurl/_Layout/15/appregnew.aspx
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.