Guidelines for registering apps for SharePoint 2013

apps for SharePoint

Learn when you must register apps for SharePoint, the various ways to do it, when to use them, and how to look up information about registered apps.

Note Note

This article assumes that you are familiar with the basic concepts and principles behind the OAuth 2.0 Framework. For more information about OAuth, see OAuth.net and Web Authorization Protocol (oauth).

For the remote components of a provider-hosted app for SharePoint to interact with SharePoint using OAuth, the app must first have an app identity that is registered with Microsoft Azure Access Control Service (ACS) and the SharePoint App Management Service of the tenancy or farm. (This is not required for SharePoint-hosted apps, so they are not registered.)

An app identity includes the following basic information:

  • A GUID for the app, called a client ID in OAuth terminology

  • A password for the app, called a client secret

  • A display name of the app that is used on the consent page where the user is prompted to trust the app

  • A URL for the domain where the remote app is hosted

  • In some cases, the identity also includes a redirect URL (explained later in this article)

Developers can get an app identity for their app by registering their app with Azure ACS. When you register your app, you specify the preceding items of information.

After you've registered your app, your app has an app identity and is a security principal, referred to as an app principal, just as users and groups are security principals. Later, after you've installed your app, SharePoint administrators are able to retrieve information about that particular app principal.

When a user first grants an app permissions to access SharePoint resources (which can happen either at app installation or at app runtime, depending on the design of the app), SharePoint obtains information about the app from Azure ACS. SharePoint then stores the basic information about the app in the App Management Service database of the SharePoint tenancy or farm, with the exception of the client secret which is stored only with Azure ACS. SharePoint never knows the app's secret. The content database service and other components, such as the user profile service, can get the display name of an app and other basic information about the app directly from the app management shared service. For more information about how to retrieve app information, see the Retrieve app registration and app principal information section in this article.

This article describes the ways that developers can register their apps to get this app identity. Which method you choose depends on where you are in the app development life cycle and on the architecture of your app and how you plan to market it.

Important note Important

Regardless of how you register your app for SharePoint, you must carry out the procedure described below in Enter the registration values into the web.config and AppManifest.xml files.

To register your app, you can:

  • Rely on Visual Studio and Microsoft Office Developer Tools for Visual Studio to create a temporary app identity for use during the app development phase.

  • Register the app through the Seller Dashboard.

  • Register the app by using the AppRegNew.aspx page of any SharePoint website in the Microsoft SharePoint Online tenancy or on-premise SharePoint farm where the app is to be installed.

Note Note

If you are creating an app that requests permission to access SharePoint resources on the fly (that is, an app that requests permission to access SharePoint resources dynamically at run time, instead of at app installation time), you cannot use Visual Studio to create app identities.

If you're using Visual Studio and Office Developer Tools for Visual Studio to create app for SharePoint projects, the Office Developer Tools for 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. When you run the app from Visual Studio (F5), this identity is used. (The tools also insert the client ID and secret where they belong in the web.config and AppManifest.xml files.)

When you're ready to publish your app, you can use the Visual Studio publish wizard to take you to the Seller Dashboard, where you can register your app. If you are not marketing your app for SharePoint in the Office Store and you will be publishing it in only one SharePoint tenancy or farm, 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, regardless of whether you intend to market the app in the Office Store or ask users of your app to deploy it via the app catalog. Registering in the dashboard enables you to design your app with a multitenant architecture without requiring administrators at every tenancy or farm where it is installed to separately register it. Also, if you intend to publish your app in the Office Store, you have to use the Seller Dashboard to register your app, but you don’t have to use the store to publish an app that is registered with the Seller Dashboard.

Note Note

For more information about registering apps via the Seller Dashboard see How to: Create or update client IDs and secrets in the Microsoft Seller Dashboard.

You should use AppRegNew.aspx to register your app for SharePoint if you are going to use the app only in one tenant or farm. For example, if you're creating apps for a single organization and you're going to distribute the app with the organization app catalog, you can use AppRegNew.aspx of any website in a tenancy or farm to register the app. An app that is registered with AppRegNew.aspx cannot be published in the Office Store.

To create the app identity, navigate to http://<SharePointWebsite>/_layouts/15/AppRegNew.aspx on the tenancy or farm.

Note Note

Apps that are submitted to the Office Store must use an identity that is obtained from the Seller Dashboard.

Enter values for the form fields as described below.

  • App ID: App ID, also known as client ID, is a GUID that can be generated (when you click Generate) or pasted into AppRegNew.aspx. The value must be unique for each app, and must be lower case.

  • App Secret: The app secret, also known as the client secret, is an opaque string. It is generated on the AppRegNew.aspx page by using the Generate button. The following is an example of an app secret: xvVpG0AgVIJfch6ldu4dLUlcZyysmGqBRbpFDu6AfJw=.

    Important note Important

    App secrets expire. If you register the app on the Seller Dashboard, you can set the expiration as long as 3 years. In the dashboard, you can also add new secrets when the old ones approach their expiration date. The new secret will be enabled in all instances of the app. If you register the app with AppRegNew.aspx, the secret expires in 1 year. For details about how you replace it, see How to: Replace an expiring client secret in an app for SharePoint.

  • Title: Choose your own user-friendly title; for example, Contoso photo printing app. Users are prompted to grant or deny the app the permissions that the app is requesting. This title appears as the name of the app on this consent prompt. (Users get the prompt either when the app is installed or at runtime, depending on the design of the app.)

  • App Domain: The host name of the remote component of the app for SharePoint. If the remote application isn't using port 443, the app domain must also include the port number. That is, the app domain must match the URL bindings you use for your web application. There should be no protocol ("https:") or "/" characters in this value. (If your web application host is using a DNS CNAME alias, use the alias.) Some examples:

    • www.contoso.com:3333

    • www.fabrikam.com

  • Redirect URI: The endpoint in your remote application or service to which ACS sends an authentication code. The redirect URI is required for apps that are launched outside of SharePoint (and which, thus, use the Authentication Code flow); but it is ignored and can be left blank for apps that are launched from SharePoint and, thus, use the Context Token flow. The value is usually the very same page, or controller method, or web service method whose code requested the authentication code, but it can be a different endpoint. The endpoint must have logic that gets the authorization code from the HTTP Response that is sent by ACS and then uses that code to request an access and refresh token. For more information, see Authentication Code OAuth flow for apps in SharePoint 2013.

    The value must be a complete endpoint URL including the protocol which must be HTTPS; for example:

    • https://www.contoso.com/Default.aspx

    • https://www.fabrikam.com/RedirectAccept.aspx

    • https://www.northwindtraders.com/home/index

    • https://adventureworks.com/vacationdata.svc

Click Create on the form. The page will reload and show a confirmation of the values you entered. MAKE A RECORD OF THESE VALUES IN A FORM THAT IS EASY TO COPY 'N' PASTE. You will need to enter the values in web.config and AppManifest.xml files or in the Visual Studio Publish wizard.

Before you package the app for SharePoint and before you deploy its remote components, you have to enter some of the registration values in the AppManifest.xml and the web.config file.

Tip Tip

If you publish your app for SharePoint from the Visual Studio UI by using the Visual Studio publish wizard, Visual Studio will prompt you for a client ID and client secret during the publishing process, and it will put the information in the correct places for you.

  1. In the Web.config file in your Visual Studio project, enter the app ID value as the ClientId value (replacing the temporary value that the tools entered).

    Important note Important

    All the letters in the client ID GUID must be lowercase.

    The following is an example:

    <appSettings>
      <add key="ClientId" value="a044e184-7de2-4d05-aacf-52118008c44e" />
       .  .  .
    </appSettings>
    
  2. Enter the app secret value as the ClientSecret value (replacing the temporary value that the tools entered).

    The following is an example of how the values are used in the Web.config file of a web application:

    <appSettings>
      <add key="ClientId" value="a044e184-7de2-4d05-aacf-52118008c44e" />
      <add key="ClientSecret" value="l0z/8TzWN0yQBzMBSEZtYts2Vt3Eo/oE3rfCdPaogKQ=" />
    </appSettings>
    
  3. In the AppManifest.xml file in your Visual Studio project, enter the app ID value as the ClientId value, with lower case letters.

    Note Note

    The app manifest is not applicable to applications that request permission to access SharePoint resources on the fly. These are "apps for SharePoint" only in an extended sense. They are not installed on SharePoint and do not have an app manifest. For more information, see Authentication Code OAuth flow for apps in SharePoint 2013.

    The following is an example of how the ClientId value is used in the AppManifest.xml file:

    <AppPrincipal>
      <RemoteWebApplication ClientId="a044e184-7de2-4d05-aacf-52118008c44e"/>
    </AppPrincipal>
    
  4. The Office Developer Tools for Visual Studio use the token ~remoteAppUrl in StartPage element. (For example, <StartPage>~remoteAppUrl/Pages/Default.aspx?{StandardTokens}</StartPage> This token resolves to the URL of the remote component if you are using the Publish wizard in Visual Studio. However, if you don't use the wizard (or even if you do use it but you are publishing the remote component to Azure), you have to manually replace the token with the App Domain value that you used when registering the app. It must be exactly the same value, including protocol, if any; except that you include the HTTPS protocol as well. The following is an example:

    <StartPage>https://www.contoso.com/Pages/Default.aspx?{StandardTokens}</StartPage>
    
  5. Consider using the same value for the Title element in the AppManifest.xml file as you used for the Title field in AppRegNew.aspx. The Title element value is the name of the app that users see on the app after it is installed. It may be confusing to users for the app to have a different name in the consent dialog than it has in the SharePoint UI.

    The following is example of how these values would look in the app manifest:

    <Properties>
      <Title>Contoso photo printing app</Title>
      <StartPage>https://www.contoso.com/Pages/Default.aspx?{StandardTokens}</StartPage>
    </Properties>
    

If your app is designed to ask for permissions from SharePoint on the fly, then it has code in it that uses the redirect URI, along with other information, to obtain an access token from ACS. Find the place where this URI is set and use the exact value that you used for the Redirect URI field on AppRegNew.aspx or in the Seller Dashboard. Depending on the design of the app and the language/platform on which it was built, it may be in a code file or a configuration file.

You can retrieve app registration information and app principal information for the apps you've installed or registered on SharePoint.

To look up registration information for an app that you have registered, navigate to http://<SharePointWebsite>/_layouts/15/AppInv.aspx.

To do a lookup, you have to remember the client ID (also known as the app ID) that was used to register the app. The lookup returns the following information for a particular client ID:

  • Title

  • App domain

  • Redirect URL (This is the same as the redirect URI.)

The lookup does not return the app secret value.

To see a list of registered app principals, navigate to:

http:// <SharePointWebsite> /_layouts/15/AppPrincipals.aspx

Show:
© 2014 Microsoft