How to: Create Client IDs and secrets in the Microsoft Seller Dashboard
Published: July 16, 2012
Learn how to create Client IDs and secrets, and associate them with your apps in the Seller Dashboard to enable Open Authorization (OAuth) authorization services in your apps for Office and SharePoint.
Applies to: apps for Office | apps for SharePoint | Office 2013 | Office 365 | SharePoint Foundation 2013 | SharePoint Server 2013
Open Authorization (OAuth) is a web-based protocol standard for authorization and data access. With an app that employs the OAuth protocol, users can 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 this 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, they will be presented with a dialog box to give their consent. If they give their consent, the app can do one of the following:
Authenticate the user based on trusted Microsoft credentials, without prompting the user for those credentials.
Act on behalf of the user, with their or their admin’s permission, to access the data that the app requires.
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 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.
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
Sign in to the Seller Dashboard with your Microsoft account.
On the client ids tab, choose add a new oauth client id.
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.
Choose GENERATE CLIENT ID.
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 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.
We recommend that you 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.
If your client secret is close to expiring, you will need to generate a new client secret and update your app.
Choose DONE.
In the have you copied your client secret? dialog box, choose cancel, if you have not copied your client secret. If you have 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 |
|---|
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, in order 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 software development kit (SDK) provided for the app type you are developing. For example, if you are developing an App for SharePointrefer to SharePoint SDK documentation. |
To associate the client ID and client secret with your app in the Seller Dashboard
When you’re adding or editing your app, choose the My app is a service and requires server to server authorization checkbox.
Select the friendly name of the OAuth client ID that you want your app to use.
For more information, see How to: Add apps in 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.
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 |
|---|
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
Sign in to the Seller Dashboard with your Microsoft account.
On the client ids tab, choose the client ID with which you want to associate additional client secrets.
On your client ID summary page, choose ADD NEW CLIENT SECRET.
Choose GENERATE CLIENT SECRET.
Copy your client secret to a secure location so that you can refer to it later.
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.
We recommend that you 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.
Choose DONE.
In the have you copied your client secret? dialog box, choose cancel, if you have not copied your client secret. If you have copied your client secret to a secure location, choose YES.
Note The new client secret will be active within 15 minutes.
To delete a client secret
Sign in to the Seller Dashboard with your Microsoft account.
On the client ids tab, choose the client ID that has the client secret you want to delete.
On your client ID summary page, under client secrets, choose the X next to the client secret you want to delete.
Important Deleting a client secret can prevent your app from accessing the data it needs, unless you have created additional secrets that are valid and that are associated with your app, and you have 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.
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 this 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 |
|---|
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
Sign in to the Seller Dashboard with your Microsoft account.
On the client ids tab, choose the client ID that you want to delete.
On your client ID summary page, under OAUTH CLIENT ID, choose DELETE.
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.
In the are you sure you want to delete <your client ID’s name>? dialog box, choose NO, if you are not ready to delete this client ID. If you are ready to delete this client ID, choose YES.
To delete a client ID, but continue offering your app
Add another client ID and at least one valid client secret.
For more information, see Add a client ID and client secret.
Delete the client ID from your code.
Note Customers using your app will experience downtime after you delete a client ID that is associated with your app.
Delete the client ID from the Seller Dashboard. For more information, see the previous procedure.
Add the new client ID and client secret to your code.
Submit your updated app for approval in the Seller Dashboard. For more information, see How to: Add apps in the Microsoft Seller Dashboard.
Caution Customers using your app will experience downtime during the update to your code and the Seller Dashboard approval process.
Date | Description |
|---|---|
July 16, 2012 | Initial publication |
