In the previous section you
saw how applications have an identity as well as users. When an app
takes an action in the context of a user, SharePoint records this
information. For example, when a SharePoint list item is created or
modified and you later view that list item, you will see the Last
Modified and Created information listed as “by My Simple App on behalf of Joe Bloggs,” where My Simple App is the name of the application (application principle) and Joe Bloggs
is the name of the user for whom the app made the request. The
following activity shows how this works in practice and helps you get
started working with application identities by creating a simple
application and an associated application identity.
TRY IT OUT: Application Identities (ApplicationIdentity.js)
In this exercise you create a simple
SharePoint-hosted application that uses the JavaScript CSOM to talk to
SharePoint using the Napa tools in Office 365. You need the Napa
application installed from the Office 365 marketplace prior to starting
this exercise.
1. In your
SharePoint site create a new Custom list called Gadgets. Do this by
clicking in Site Contents, and click Add App. Select Custom List from
the list and call it Gadgets. Click Create.
2. Ensure you have Napa Office 365 Development Tools installed in your development site in Office 365.
3. Click Site Contents in your site navigation to see a list of all apps installed in your site.
4. Locate Napa Office 365 Development Tools in the list and click it.
5. Click Add New Project.
6. Select App for SharePoint and enter MyNewApp
in the Project name box. Click Create to continue. Napa creates a set
of template files and folders for you. Explore the structure and get
familiar with the layout of the application.
7. Open the Scripts folder and then open the App.js file. This default file contains the JavaScript for your application.
8. Replace the contents of the file with the following code:
var context;
var web;
var user;
// This code runs when the DOM is ready. It ensures the SharePoint
// script file sp.js is loaded and then executes sharePointReady()
$(document).ready(function () {
SP.SOD.executeFunc('sp.js', 'SP.ClientContext', sharePointReady);
});
var hostUrl;
function sharePointReady() {
context = new SP.ClientContext.get_current();
web = context.get_web();
hostUrl = getParameterByName('SPHostUrl');
createItems();
}
function createItems()
{
var listContext = new SP.AppContextSite(context, hostUrl);
var list = listContext.get_web().get_lists().getByTitle('Gadgets');
var itemCreateInfo = new SP.ListItemCreationInformation();
var newListItem = list.addItem(itemCreateInfo);
newListItem.set_item('Title', 'Microsoft Surface 32GB with Touch Cover');
newListItem.update();
context.load(newListItem);
context.executeQueryAsync(onCreateListItemsSuccess,onFailed);
}
function onCreateListItemsSuccess() {
alert('List Item created');
}
// This function is executed if the preceding call fails
function onFailed(sender, args) {
alert('Failed. Error:' + args.get_message());
}
function getParameterByName(name)
{
name = name.replace(/[[]/, "\[").replace(/[]]/, "\]");
var regexS = "[\?&]" + name + "=([^&#]*)";
var regex = new RegExp(regexS);
var results = regex.exec(window.location.search);
if(results == null)
return "";
else
return decodeURIComponent(results[1].replace(/+/g, " "));
}
9. In the lower left area of the window click the wrench icon to open the Property panel for your application.
10. Click the Permissions tab and set the permissions for Web under Content to Full Control.
11. Run the
project using the Run Project button in the bottom left of the window;
a permissions request window appears, asking you to grant the
application full control of the site. Click Trust It.
12. An alert window appears showing, “List Item created.” Click OK.
13. Check that
your list was created by clicking the link in the top left of the page
to get to your developer site. Click Site Content and find the Gadgets
list. You should see the new list item that was created.
14. View the list item by clicking the “...” beside the list item and selecting View Item.
15. Review the Created At information at the bottom of the page. It will say “by MyNewApp on behalf of.”
How It Works
In this exercise you created a
SharePoint-hosted application using the Napa tools that created a new
list item in a SharePoint list. The app created the list item on behalf
of the user, and you can see this information in the Created By and
Modified By fields on the newly created list item. This is because when
the app makes the CSOM call, the application identity is passed and
SharePoint understands that the call is being made on behalf of a user
via an application.
An application identity consists of an ID, name,
and a domain where the app is hosted. The type of application and
environment will dictate a particular method for creating new
application identities/registrations.
The manual options for creating new registrations include the following:
- Manually register a new identity in SharePoint.
- Obtain a new identity for the app market from the Seller Dashboard.
- Register a new identity using PowerShell.
In some scenarios, creation of an app identity is automated for you. Those are as follows:
- Deploying and debugging via Visual Studio during development
- Using the Autohosted app type
During development Visual Studio takes care of
temporarily creating an app identity for you during the deployment and
configuration of your application so that you don’t have to. A new one
is created each time you deploy, but you can’t rely on these identities
for long periods of time. SharePoint Online will also take care of the
creation of an app identity for you upon deployment and installation of
an Autohosted app, however you must create an app identity when you are
not building an Autohosted app and when one or more of the following apply:
- You have completed development and are ready to deploy your app.
- You are building a Provider-hosted app for either SharePoint Online or SharePoint on premises.
- You are building an app for the marketplace in SharePoint Online.
NOTE
If you are packaging your application and will be distributing it via
the marketplace in SharePoint Online you must obtain an application
identity via the Seller Dashboard. To read more about this process
refer to Chapter 8, “Distributing SharePoint 2013 Apps.”
If you want to deploy the app locally on a
SharePoint on-premises deployment or privately (not via the
marketplace) in SharePoint Online then you must manually register a new
application identity. You can do it via the AppRegNew.aspx page, which is located at: http://yourservername/_layouts/15/appregnew.aspx. AppRegNew.aspx
and allows you to either specify or generate a client ID (another name
for app ID) and a client secret. Additionally, it requires you to
specify a friendly name for the app and the domain that hosts the app.
After you complete a new registration, a page appears listing the
details. You should make a note of these somewhere safe. You need them
to update the manifest files in Visual Studio.
After you have a static client ID and client secret you then must update the values in the following locations:
- In the app project AppManifest.xml file, change the AppPrincipal, RemoteWebApplication client ID node as follows:
<AppPrincipal>
<RemoteWebApplication ClientId="<Client ID Here>"/>
</AppPrincipal>
- In the Web.config file in the app code project, change the AppSettings, client ID, and client secret nodes as follows:
<appSettings>
<add key="ClientId" value="<Client ID Here>" />
<add key="ClientSecret" value="<Client Secret Here>" />
</appSettings>
- The app domain is the host name of where your application remote
Website and code is hosted. This could be a Website in Azure; for
example, www.contoso.com.
- The redirect URI is used for when apps request permissions on the
fly versus explicitly in the app manifest file. This should be the URL
of the page that accepts the authorization code postback from
SharePoint after the authorization has been processed. This field can
be left blank if you are not requesting permissions on the fly from
SharePoint.
The following exercise walks you through creating an application identity in SharePoint Online.
TRY IT OUT: Creating an App Identity
In this exercise you create a new
application identity registration in SharePoint Online. You need a
SharePoint Online site and need to be a site collection administrator.
1. In your SharePoint site navigate to /_layouts/15/appregnew.aspx.
2. Click Generate beside App ID and App Secret.
3. In the Title field type My First App.
4. In the App Domain, type the domain name of the location you will deploy your Provider-hosted app to; for example, www.contoso.com.
5. Leave the Redirect URI blank.
6. Click Create.
7. A set of
information appears about your application identity. Copy this
information to a safe location. It will look similar to the following:
The app identifier has been successfully created.
App Id: b5759c4d-9572-4154-a569-8ad254c2c7ca
App Secret: U6xxmVq1txVitMiqTffVt/G9c+JjXbMwNFijziv2YxU=
Title: My First App
App Domain: www.contoso.com
Redirect URI:
How It Works
In this exercise you created a new
application identity. Behind the scenes SharePoint creates the
registration and then saves it by way of the application management
shared service. It is persisted to the services database and can be
read from any of the SharePoint Servers in the farm.
You can also look up some of the details about a registered app using the AppInv.aspx page, which is located at: http://yourservername/_layouts/15/appinv.aspx.
You must supply the client ID for the app. Note that the page doesn’t
provide the client secret of your app, just the display name and host
domain information.
