Export (0) Print
Expand All

Guidelines for registering apps for SharePoint 2013

apps for SharePoint

Learn guidelines for when to use the Seller Dashboard, appregnew.aspx, Windows PowerShell cmdlets, and Visual Studio 2012 to register your apps.

Note Note

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

For a remote app to be able to interact with SharePoint 2013 using OAuth, an app must first have an app identity. An app identity includes the following basic information:

  • Client Id of the app

  • Display name of the app

  • App domain where the remote app is hosted

Developers can get an app identity for their app by registering their app. When you register your app, your app gets a client Id, client secret, display name, and app domain. In some cases, it also gets a redirect URI associated with it.

Note Note

For more information about redirect URIs and when it is necessary to use them, see OAuth authentication and authorization flow for apps that ask for access permissions on the fly in SharePoint 2013 (advanced topic).

After you've registered your app, your app has an app identity and is associated with a security principal, referred to as an app principal. Later, after you've installed your app, you will be able to retrieve information about that particular app principal.

Note Note

For more information about how to retrieve app information, see the Retrieving app registration and app principal information section in this article.

The identity of an app, and its client secret, are stored in the Microsoft Azure Access Control Service (ACS), and the ACS is the authorization authority. When a user first grants an app permissions to access SharePoint 2013 resources on the user's behalf, SharePoint 2013 obtains information about the app from ACS. SharePoint 2013 then stores the basic information about the app in the app management shared service. 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.

There are five ways that developers can register their apps to get this app identity. Which route you choose depends on your scenario and environment. You might even choose to use more than one way when your scenario or environment changes.

Note Note

For more information and details about each method, see the subsections for each method in this article.

To register your app, you can:

  • Rely on Visual Studio 2012 and Office Developer Tools for Visual Studio 2012 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 appregnew.aspx.

  • Use Office 365 Windows PowerShell cmdlets to create services principals. For more information, see Windows PowerShell cmdlets for Office 365.

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 during run time, instead of at app installation time), you cannot use Visual Studio to create app identities.

If you're using Visual Studio 2012 and Office Developer Tools for Visual Studio 2012 to create app for SharePoint projects, the Office Developer Tools for Visual Studio 2012 wizard will create a temporary app identity for your app automatically. You don't have to use the Seller Dashboard or the appregnew.aspx page to generate and register the app client Id, client secret, app domain, or app display name. You can use the temporary app identity that Visual Studio 2012 automatically generates for your app during development.

Later, when you're ready to deploy or publish your app, you can again use the Visual Studio deploy and publish wizard to take you to the Seller Dashboard, where you can register your app.

But, if you want to deploy your app for further testing outside of Visual Studio 2012, or for production purposes, you have to get a client Id elsewhere. You can do that by registering your app using the Seller Dashboard or appregnew.aspx.

Note Note

For more information about registering apps by using appregnew.aspx, see the Registering apps using appregnew.aspx section in this article.

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. It enables you to use the app in a multitenant scenario. Also, if you intend to publish your app in the Office Store, you have to use the Seller Dashboard to register your app.

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 can use appregnew.aspx to register your app if you are going to use the app only in one tenant. For example, if you're creating apps for a single organization and you're going to use an app only within your corporate catalog, you can use appregnew.aspx to get the client Id. You would not be able to use the app in a multitenant scenario. In particular, the client Id cannot be found when used in the context of tenants other than the one where it was created. You also would not be able to publish your app in the Office Store.

The URL to register app information using appregnew.aspx

Before you build your remote app, you have to generate an app Id, app secret, and so on. To generate and create these values, go to http://yourSharePointServerName/_layouts/15/appregnew.aspx.

Note Note

You can use the values that are generated by using the appregnew.aspx page during the development phase. Apps that are submitted to the Office Store must use client Ids and client secrets obtained from the Seller Dashboard.

The format of app registration fields

The formats of the values for the fields in the appregnew.aspx page are as follows:

  • App Id: App Id is also known as client Id. They are the same thing. It is a unique GUID that is generated by http://yourServerName/_layouts/15/appregnew.aspx, when you click Generate. The value must be unique for each app.

    For example, the following is a sample generated app Id: 2de23703-bbb9-4542-970d-84b6e5597f53

    Note Note

    Currently, all the letters in the client Id GUID must be lowercase. Ensure that all the letters in the GUID for the client Id in the web.config file and the AppManifest.xml file are lowercase.

    Remember this value because you use it in the following files in Visual Studio 2012:

    Note Note

    If you are letting Visual Studio 2012 automatically generate your client Id, you don't have to worry about placing the client Id and client secret value correctly in the AppManifest.xml file. Also, if you choose to publish your provider-hosted app from the Visual Studio 2012 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 place for you.

    • In the AppManifest.xml file in your Visual Studio project, enter the app Id value as the ClientId value.

      Note Note

      The app manifest is not applicable to apps that request permission to access SharePoint 2013 resources on the fly. For more information, see OAuth authentication and authorization flow for apps that ask for access permissions on the fly in SharePoint 2013 (advanced topic).

      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>
      
    • In the Web.config file in your Visual Studio project, enter the app Id value as the ClientId value.

      The following is an example:

      <appSettings>
          <add key="ClientId" value="a044e184-7de2-4d05-aacf-52118008c44e" />
          <add key="ClientSecret" value="w7om5dfhzr7k5rnnA551GGp6k6z6XHprjoN8VPm6xFw=" />
        </appSettings>
      
      
  • App Secret: The app secret is also known as the client secret. They are the same thing. It is a base-64 encoded string generated by http://yourServerName/_layouts/15/appregnew.aspx, when you click Generate.

    For example, the following is a sample generated app secret: xvVpG0AgVIJfch6ldu4dLUlcZyysmGqBRbpFDu6AfJw=

    Remember this value because you use it in the following file in Visual Studio 2012:

    • In Web.config, in your Visual Studio project, enter the app secret value as the ClientSecret value.

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

    
    <configuration>
      ...
      <appSettings>
        <add key="ClientId" value="a044e184-7de2-4d05-aacf-52118008c44e" />
        <add key="ClientSecret" value="l0z/8TzWN0yQBzMBSEZtYts2Vt3Eo/oE3rfCdPaogKQ=" />
      </appSettings>
      ...
     </configuration>
    
  • Title: Choose your own title.

    For example, the following is a sample title: Contoso photo printing app

    Note Note

    When users first install an app, they are prompted to grant or deny the app the permissions that the app is requesting. This title appears as the name of the app during this consent prompt. Consider using the same value as the Title element in the AppManifest.xml file. The Title element value is the name of the app that users see on the app after it is installed.

  • App Domain: The host name of the remote application. And, 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. If you choose to hardcode the app domain in the <StartPage> element in the AppManifest.xml file instead of using tokens, the app domain must match your app domain registration.

    For example, the following are sample app URIs:

    • www.contoso.com:122

    • www.contoso.com

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

    
      <Properties>
        <Title>Contoso Photo Printing App</Title>
        <StartPage>https://www.contoso.com/Default.aspx?SP.Url={HostUrl}</StartPage>
      </Properties>
    
    NoteNote

    You can also use tokens in the <StartPage> element. For example, <StartPage>~remoteAppUrl/Pages/Default.aspx?{StandardTokens}</StartPage>. For more information about the app manifest and using tokens, see URL strings and tokens in apps for SharePoint and Explore the app manifest and the package of an app for SharePoint.

  • Redirect URI: The redirect URI that your hosted application will use.

    For example, the following are sample redirect URIs:

    • https://yourRemoteAppServerName:port/RedirectAccept.aspx

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

    Note Note

    The redirect URI is an optional field for apps that are launched from SharePoint 2013. That is, if you are creating an app that is launched from SharePoint 2013, you can leave the field blank. You do not have to supply a redirect URI because the redirect URI is not used in this type of app. But, for apps that request permission to access SharePoint resources on the fly, the redirect URI field is a required field. If you are creating apps that request permission to access SharePoint resources on the fly, you must supply the redirect URI. The protocol must be HTTPS. For more information about the redirect URI and when to use it, see OAuth authentication and authorization flow for apps that ask for access permissions on the fly in SharePoint 2013 (advanced topic).

Note Note

You can use the values that are generated by using the appregnew.aspx page during the development phase. Apps that are submitted to the Office Store must use app Ids and app secrets obtained from the Seller Dashboard.

Retrieving app registration and app principal information

You can retrieve app registration information and app principal information for the apps you've installed or registered on SharePoint 2013. This section describes how to retrieve app registration and app principal information.

Retrieving app registration information after registering with appregnew.aspx

You can lookup app registration information for an app that you have registered. The lookup is at http://yourSharePointServerName/_layouts/15/appinv.aspx.

To do a lookup, you have to remember the client Id (also known as the app Id) that you used to register your app. The lookup returns the following corresponding 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.

Retrieving a list of app principals

You can retrieve a list of app principals from the following page:

http://yourSharePointServerName/_layouts/15/appprincipals.aspx

Administrators can register apps using the Microsoft Online Services Windows PowerShell cmdlets. For guidelines about when and how to use the cmdlets, see Windows PowerShell cmdlets for Office 365.

Show:
© 2014 Microsoft