Export (0) Print
Expand All

Create Client IDs and Secrets in the Microsoft Seller Dashboard

Published: December 12, 2013

noteNote
This topic applies to the following marketplaces: Office Store and Microsoft Azure Marketplace.

Open Authorization (OAuth) is an open standard for authorization. Apps that use OAuth enable users to securely share their private resources, such as documents, calendars, and contact lists, from one service to another without sharing their user credentials with a third party app. If your app is a service that requires server-to-server authorization, you can generate an OAuth Client ID and client secrets in the Microsoft Seller Dashboard, and then add the Client ID and client secrets to the code of your app.

When a user chooses an app that has an associated Client ID and client secret, the system displays a dialog box that requires the user’s consent to proceed. If the user provides consent, the app can do one of the following:

  • Authenticate the user based on trusted Microsoft credentials, without prompting the user for those credentials.

  • Access required data for the app on behalf of the user, with the permission of the user or the user’s admin.

For example, your app could be a trip calendar app that opens as an iFrame on a Microsoft Office 365 SharePoint site. In this case, 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.

In this topic

Add a Client ID and client secret

You can only associate 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.

noteNote
If you want to submit an app for SharePoint that uses OAuth and you want to distribute it in China, add a separate Client ID and secret for China. You will also need to add a separate app package specifically for China, and block access for all countries except China. For more information about adding the app and blocking access, see Add Apps in the Microsoft Seller Dashboard.

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 checkmark 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, deletion of that secret can prevent your app from accessing necessary data.

To add an OAuth Client ID and client secret, follow these steps:

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

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

  3. In the ADD A CLIENT ID wizard, on the provide details page, under create a new client id, provide the following information:

    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. This is a relatively easy time period to track in business processes. However, there is no security impact to choosing a longer time period. When the client secret is about to expire, you will need to update your app.

  4. Under Client ID and Secret Availability, select 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.

    noteNote
    If you want to submit an app for SharePoint that uses OAuth and you want to distribute it in China, you will use the Client ID and secret that you add specifically for China. You will also need to add a separate app package for China, and block access for all countries except China. For more information about adding the app and blocking access, see Add Apps in the Microsoft Seller Dashboard.

  5. Click GENERATE CLIENT ID.

  6. 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.

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

    • Copy the client secret to a secure location that will not allow anyone else to access it. You should also record the start and end dates, so that you will be aware of the client secret’s period of validity and its expiration date.

    • When your client secret is close to expiration, 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.

  7. Click DONE.

  8. In the have you copied your client secret? dialog box, click cancel, if you have not copied and stored your client secret. If you have copied your client secret to a secure location, click YES.

Associate your Client ID and secret with your app

After 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.

noteNote
  • 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 to the Seller Dashboard. In order to fully test your app, you should add the Client ID and client secret before testing. 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 software development kit (SDK) provided for the app type you are developing. For example, to develop an app for SharePoint to use with Microsoft Office 365, you would refer to the related SharePoint SDK documentation.

To associate the Client ID and client secret with your app in the Seller Dashboard, follow these steps:

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

    noteNote
    If you are submitting an app for SharePoint that uses OAuth and you want to distribute it in China, under OAuth Client ID, click the drop-down arrow. 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 Add a Client ID and client secret.

  2. Select the friendly name of the OAuth Client ID that you want your app to use. For more information, see Add Apps in the Microsoft Seller Dashboard.

Update the client secret associated with your Client ID

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

  • Your client secret is expiring: If your client secret is about to expire, you should 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.

  • The security of your client secret is compromised: If the security of your client secret is compromised, you should respond to the situation quickly. To do this, 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.

    ImportantImportant
    After the compromised client secret is deleted and before the new client secret is added, your app may experience some downtime. The reduced service level that this downtime causes may be acceptable, due to the possible business impact of a lost or stolen client secret.

Generate additional client secrets

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

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

  3. On your Client ID summary page, click ADD NEW CLIENT SECRET.

  4. Click GENERATE CLIENT SECRET.

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

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

    • Copy the client secret to a secure location that will not allow anyone else to access it. You should also record the start and end dates, so that you will be aware of the client secret’s period of validity and expiration date.

  6. Click DONE.

  7. In the have you copied your client secret? dialog box, click cancel, if you have not copied and stored your client secret. If you have copied your client secret to a secure location, click YES.

    noteNote
    The new client secret will become active within 15 minutes.

Delete a client secret

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

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

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

    ImportantImportant
    • Deleting a client secret can prevent your app from accessing required data, unless you have created additional valid secrets, associated them with your app, and configured the app to use them.

    • 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. The are you sure you want to delete this client secret? dialog box appears. Click NO, if you are not ready to delete this client secret. If you are ready to delete this client secret, click YES.

Delete a Client ID

WarningWarning
Deletion of 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.

You may want to delete a Client ID in certain situations, such as:

  • 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.

To delete a Client ID, follow these steps:

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

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

  3. On your Client ID summary page, under OAUTH CLIENT ID, click DELETE.

  4. The are you sure you want to delete <your Client ID’s name>? dialog box appears. Click NO, if you are not ready to delete this Client ID. If you are ready to delete this Client ID, click YES.

If you want to continue offering your app, follow these steps:

  1. Add another Client ID and at least one valid client secret. For more information, see the Add a Client ID and client secret section in this topic.

  2. Delete the old Client ID from your code.

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

  3. Delete the old 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 Add Apps in the Microsoft Seller Dashboard.

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

See Also

Show:
© 2014 Microsoft