Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Create or update client IDs and secrets

Create or update client IDs and secrets in the Seller Dashboard

Office and SharePoint Add-ins

Create or delete client IDs and secrets, update or replace expiring client secrets, and associate them with your add-ins in the Seller Dashboard to enable OAuth in your SharePoint Add-ins.

Last modified: August 07, 2015

Applies to: apps for Office | apps for Office Mix | apps for SharePoint | Office 365 | Office Add-ins | SharePoint Add-ins

Note Note

The names "apps for Office" and "apps for SharePoint" are changing to "Office Add-ins" and "SharePoint Add-ins". During the transition, the documentation and the UI of some Office and SharePoint products and Visual Studio tools might still use the terms "apps for Office" and "apps for SharePoint". For details, see New name for apps for Office and SharePoint.

In this article
Using OAuth to authenticate and authorize add-ins
Add a client ID and client secret
Update the client secret associated with your client ID
Delete a client ID
Additional resources

To update expiring client secrets in SharePoint Add-ins:

  1. Generate and add a new client secret in the Seller Dashboard to associate with that particular add-in client ID. For specific steps, see To generate additional client secrets in Update the client secret associated with your client ID later in this article.

  2. Update your remote web application to use the new client secret. For information about how to do this using Microsoft Office Developer Tools for Visual Studio, see Update the remote web application in Visual Studio to use the new secret in Replace an expiring client secret in a SharePoint Add-in.

  3. Republish your remote web application.

Important note Important

Microsoft Office Developer Tools for Visual Studio supports setting a secondary client secret that you can use to update your expiring client secret.

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 add-in requires this type of authorization, you have to associate OAuth client ID and client secrets with your add-in. You can generate OAuth client ID and client secrets in the Microsoft Seller Dashboard, and then add them to the code of your add-in.

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

For example, your add-in could be a trip calendar add-in that opens as an IFRAME on an Office 365 SharePoint site. OAuth would allow the add-in to identify the user to whom the trip calendar belongs, or if the trip calendar add-in 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 add-in, 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 a SharePoint Add-in 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 add-in package specifically for China.

  • block access for all countries except China.

  • create a separate add-in listing for China.

For more information about submitting add-ins and blocking access, see Submit Office and SharePoint Add-ins and Office 365 web apps to the Seller Dashboard. For more information about distributing add-ins for China, see Submit apps for Office 365 operated by 21Vianet in China.

Inbound data to your add-in 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 add-in uses, the next valid client secret will be used instead.

Your add-in 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 add-in from accessing the data it needs.

If your add-in 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 add-in will use this client ID, for example, "calendar app".

    Add-in Domain

    Provide the domain on which your add-in 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).

    Add-in Redirect URL

    Provide the redirect URL to send users to after they agree to your add-in'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 add-in.

    Client ID and Secret Availability

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

    Important note Important

    To submit a SharePoint Add-in 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 add-in package specifically for China.

    • block access for all countries except China.

    • create a separate add-in listing for China.

    For more information about submitting add-ins and blocking access, see Submit Office and SharePoint Add-ins and Office 365 web apps to the Seller Dashboard. For more information about distributing add-ins for China, see Submit apps for Office 365 operated by 21Vianet in 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 add-in. 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 add-in

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

Note Note

You can add the client ID and client secret to your code at any point in your add-in development process: during development, before testing your add-in, or before adding your add-in in the Seller Dashboard. However, to fully test your add-in, we recommend that you add them before you test your add-in. You can use the same client ID and secret throughout your add-in 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 add-in type you are developing.

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

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

    Important note Important

    If you are submitting a SharePoint Add-in 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 Add-ins 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 Create or update client IDs and secrets in the Seller Dashboard.

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

    For more information, see Submit Office and SharePoint Add-ins and Office 365 web apps to the 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 add-in 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 SharePoint Add-ins, 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 add-in 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 Replace an expiring client secret in a SharePoint Add-in.

    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 add-in with the new client secret.

Important note Important

After the compromised client secret is deleted and before the new client secret is added, your add-in 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 add-in from accessing the data it needs, unless you created additional secrets that are valid and that are associated with your add-in, and you configured your add-in 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 add-in.

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

Caution note Caution

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

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 add-in deletes all associated client secrets and prevents your add-in from accessing the data it needs. Any customer using your add-in will experience downtime after you delete a client ID that is associated with your add-in.

  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 add-in

  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 add-in will experience downtime after you delete a client ID that is associated with your add-in.

  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 add-in for approval in the Seller Dashboard. For more information, see Submit Office and SharePoint Add-ins and Office 365 web apps to the Seller Dashboard.

    Caution note Caution

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

Show:
© 2015 Microsoft