Export (0) Print
Expand All

How to: Create or update client IDs and secrets in the Microsoft Seller Dashboard

apps for Office and SharePoint

Learn how to create or delete client IDs and secrets, update or replace expiring client secrets, and associate them with your apps in the Seller Dashboard to enable OAuth in your apps for SharePoint.

Last modified: May 23, 2014

Applies to: Office 2013 | Office 365 | SharePoint Foundation 2013 | SharePoint Server 2013

Important note Important

To update expiring client secrets in apps for SharePoint, follow these steps. Note that Microsoft Office Developer Tools for Visual Studio supports setting a secondary client secret that you can use to update your expiring client secret.

  1. You would first generate and add a new client secret via Seller Dashboard to associate the new client secret with that particular app client ID. For steps on how to this, see the steps in the section entitled To generate additional client secrets under Update the client secret associated with your client ID in this article.

  2. Next, you update your remote web application to use the new client secret. For information on how to replace expiring client secret using Microsoft Office Developer Tools for Visual Studio, see Update the remote web application in Visual Studio to use the new secret section in How to: Replace an expiring client secret in an app for SharePoint.

  3. Republish your remote web application.

Open Authorization (OAuth) is an open protocol for authorization. OAuth enables secure authorization from desktop and web applications in a simple and standard way. It lets users approve an application to act on their behalf without sharing their user name and password. For example, users can share their private resources or data (contact list, documents, photos, videos, and so on) that are stored on one site with another site, without having to provide their credentials (typically user name and password).

With OAuth, users can authorize a service provider (for example, SharePoint 2013) to provide tokens instead of credentials (for example, user name and password) to their data that is hosted by a given service provider (for example, SharePoint 2013). Each token grants access to a specific site (for example, a SharePoint document repository), for specific resources (for example, documents from a folder), and for a defined duration. Users can then grant a third-party site access to information that is stored with another service provider (for example, SharePoint), without sharing their user name and password and without sharing all the data that they have on SharePoint.

If your app requires this type of authorization, you have to associate OAuth client ID and client secrets with your app. You can generate OAuth client ID and client secrets in the Microsoft Seller Dashboard, and then add them to the code of your app.

When a user installs an app that has an associated client ID and client secret, a consent dialog box appears. If the user gives consent, the app can act on behalf of the user to access the data that the app requires. Users can only grant the permissions that they have. Grants represent the permissions that a user has delegated to an app.

For example, your app could be a trip calendar app that opens as an IFRAME on an Office 365 SharePoint site. OAuth would allow the app to identify the user to whom the trip calendar belongs, or if the trip calendar app needed to access other aspects of Office 365, such as resources or calendar information, it could access those on behalf of the signed-in user.

You can associate only one client ID with your app, but you can associate multiple client secrets with a client ID. For security and administrative purposes, we recommend limiting the number of client secrets associated with a client ID.

Important note Important

To submit an app for SharePoint that uses OAuth, and distribute it to China, you must use a separate client ID and client secret for China. You also must:

  • add a separate app package specifically for China.

  • block access for all countries except China.

  • create a separate app listing for China.

For more information about submitting apps and blocking access, see How to: Submit apps for SharePoint to the Microsoft Seller Dashboard. For more information about distributing apps for China, see Submitting apps for SharePoint (China).

Inbound data to your app will be signed using only one signing client secret. In the Seller Dashboard, this is the client secret with a green check mark next to it. If you delete the signing client secret that your app uses, the next valid client secret will be used instead.

Your app can use any valid client secrets as passwords to communicate with Microsoft. When a client secret expires, it can no longer be used as a password. If there is only one client secret associated with your client ID, deleting that secret can prevent your app from accessing the data it needs.

If your app is a service and it will need OAuth client IDs and client secrets, follow these steps.

To add a client ID

  1. Sign in to the Seller Dashboard with your Microsoft account.

  2. On the APPS tab, choose client ids, and then choose add a new oauth client id.

  3. In the ADD A CLIENT ID wizard, on the provide details page, provide the following information.

    Item

    Information to provide

    Friendly client ID Name

    Choose a name to help you recognize which app will use this client ID, for example, "calendar app".

    App Domain

    Provide the domain on which your app will run. For example:

    app.contoso.com

    This must be a valid domain name that you own; it must not include http:// or https://; and it must not be an international domain name (IDN).

    App Redirect URL

    Provide the redirect URL to send users to after they agree to your app's access requirements in the consent dialog box. This URL must start with https://.

    Client Secret Valid For

    Choose how long your client secret will be valid. The recommended time period is one year, because this may be easier to track within your business processes than longer periods. However, there is no security impact to choosing a longer period of time. When the client secret is expiring, you will need to update your app.

    Client ID and Secret Availability

    Choose This Client ID will be used for an app that is available worldwide, or This Client ID will be used for an app that is available in China only.

    Important note Important

    To submit an app for SharePoint that uses OAuth, and distribute it to China, you must use a separate client ID and client secret for China. You also must:

    • add a separate app package specifically for China.

    • block access for all countries except China.

    • create a separate app listing for China.

    For more information about submitting apps and blocking access, see How to: Submit apps for SharePoint to the Microsoft Seller Dashboard. For more information about distributing apps for China, see Submitting apps for SharePoint (China).

  4. Choose GENERATE CLIENT ID.

  5. On the obtain client secret page, copy your client ID and client secret to a secure location so that you can refer to it later.

    Important note Important
    • Copy the client secret to a secure location that will not allow anyone else to access it.

    • The client secret is associated with your client ID, but it will not be shown in the Seller Dashboard again.

    • You should also record the start and end dates, so that you will be aware of the client secret period of validity and its expiration date.

    • If your client secret is close to expiring, you will need to generate a new client secret and update your app. For more information, see the Update the client secret associated with your client ID section in this topic.

  6. Choose DONE.

  7. If you didn’t copy your client secret to a secret location, choose cancel in the have you copied your client secret? dialog box. If you copied your client secret to a secure location, choose YES.

To associate your client ID and secret with your app

Now that you have created your client ID and client secret, you can add them to the code of your app and then associate your client ID with your app in the Seller Dashboard.

Note Note

You can add the client ID and client secret to your code at any point in your app development process: during development, before testing your app, or before adding your app in the Seller Dashboard. However, to fully test your app, we recommend that you add them before you test your app. You can use the same client ID and secret throughout your app development process.

If you are unsure where to place the client ID and client secret in your code, refer to the documentation provided for the app type you are developing. For example, if you are developing an app for SharePoint, see Build apps for SharePoint.

To associate the client ID and client secret with your app in the Seller Dashboard

  1. When you’re adding or editing your app, select the My app is a service and requires server to server authorization check box.

    Important note Important

    If you are submitting an app for SharePoint that uses OAuth, and you wish to distribute it to China, you must use a separate client ID and client secret for China:

    1. Under Client ID, choose the dropdown.

    2. Under Client IDs for Apps in China, select a client ID. If you don’t see this option, you need to add a client ID for China only.

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

  2. Select the friendly name of the OAuth client ID that you want your app to use.

    For more information, see How to: Submit apps for SharePoint to the Microsoft Seller Dashboard.

You may want to update your client secret in the following situations:

  • Your client secret is expiring

    If your client secret is close to expiring, we recommend that you add a new client secret in the Seller Dashboard while your current client secret is still valid. Update your app with the new client secret, and then delete the client secret that is close to expiring from the Seller Dashboard.

    Note Note

    To update expiring client secrets in apps for SharePoint, follow these steps. Note that Microsoft Office Developer Tools for Visual Studio supports setting a secondary client secret that you can use to update your expiring client secret.

    1. You would first generate and add a new client secret via Seller Dashboard to associate the new client secret with that particular app client ID. For steps on how to this, see the next section in this article, entitled To generate additional client secrets.

    2. Next, you update your remote web application to use the new client secret. For information on how to replace expiring client secret using Microsoft Office Developer Tools for Visual Studio, see Update the remote web application in Visual Studio to use the new secret section in How to: Replace an expiring client secret in an app for SharePoint.

    3. Republish your remote web application.

  • The security of your client secret is compromised

    If the security of your client secret is compromised, to respond to the situation quickly, you can delete the compromised client secret from the Seller Dashboard first, add a new client secret, and then update your app with the new client secret.

Important note Important

After the compromised client secret is deleted and before the new client secret is added, your app may experience some downtime. This may be acceptable depending on the severity of the business impact of a lost or stolen client secret.

To generate additional client secrets

  1. Sign in to the Seller Dashboard with your Microsoft account.

  2. On the APPS tab, choose client ids, and then choose the client ID with which you want to associate additional client secrets.

  3. On your client ID summary page, choose ADD NEW CLIENT SECRET.

  4. Choose GENERATE CLIENT SECRET.

  5. Copy your client secret to a secure location so that you can refer to it later.

    Important note Important
    • Copy the client secret to a secure location that will not allow anyone else to access it.

    • The client secret is associated with your client ID, but it will not be shown in the Seller Dashboard again.

    • Record the start and end dates so that you will be aware of the client secret period of validity and its expiration date.

  6. Choose DONE.

  7. If you didn’t copy your client secret to a secure location, choose cancel in the have you copied your client secret? dialog box. If you copied your client secret to a secure location, choose YES.

    Note Note

    The new client secret will be active within 15 minutes.

To delete a client secret

  1. Sign in to the Seller Dashboard with your Microsoft account.

  2. On the APPS tab, choose client ids, and then choose the client ID that has the client secret you want to delete.

  3. On your client ID summary page, under client secrets, choose the X next to the client secret you want to delete.

    Important note Important
    • Deleting a client secret can prevent your app from accessing the data it needs, unless you created additional secrets that are valid and that are associated with your app, and you configured your app to use these additional client secrets.

    • If you have only one client secret associated with this client ID, you may want to generate an additional client secret before deleting this one. For more information, see the previous section.

  4. In the are you sure you want to delete this client secret? dialog box, choose NO, if you are not ready to delete this client secret. If you are ready to delete the client secret, choose YES.

You may want to delete a client ID in certain situations, for example:

  • You no longer want to offer your app.

  • You want to offer a new version of your app and no longer want to offer the previous version of your app. In this situation, you may want to delete the client ID you associated with the previous version of your app.

Caution note Caution

Deleting a client ID that is associated with your app deletes all associated client secrets and prevents your app from accessing the data it needs. Any customer using your app will experience downtime after you delete a client ID that is associated with your app.

To delete a client ID

  1. Sign in to the Seller Dashboard with your Microsoft account.

  2. On the APPS tab, choose client ids, and then choose the client ID that you want to delete.

  3. On your client ID summary page, under OAUTH CLIENT ID, choose DELETE.

    Caution note Caution

    Deleting a client ID that is associated with your app deletes all associated client secrets and prevents your app from accessing the data it needs. Any customer using your app will experience downtime after you delete a client ID that is associated with your app.

  4. If you are not ready to delete this client ID, in the are you sure you want to delete <your client ID’s name>? dialog box, choose NO. If you are ready to delete this client ID, choose YES.

To delete a client ID, but continue offering your app

  1. Add another client ID and at least one valid client secret.

    For more information, see Add a client ID and client secret.

  2. Delete the client ID from your code.

    Note Note

    Customers using your app will experience downtime after you delete a client ID that is associated with your app.

  3. Delete the client ID from the Seller Dashboard. For more information, see the previous procedure.

  4. Add the new client ID and client secret to your code.

  5. Submit your updated app for approval in the Seller Dashboard. For more information, see How to: Submit apps for SharePoint to the Microsoft Seller Dashboard.

    Caution note Caution

    Customers using your app will experience downtime during the update to your code and the Seller Dashboard approval process.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft