Share via

Create or update client IDs and secrets in Partner Center

  • Article

Important

You need a Microsoft Azure AD/Entra tenant to continue to use the service without disruption after March 1 2023. Go to tenant settings in your Partner Center Account and create a new Microsoft Entra ID or associate your current ID.

Update an expiring client secret in SharePoint Add-ins

  1. Generate and add a new client secret in Partner Center to associate it with that particular add-in client ID. For specific steps, see Generate other client secrets.
  2. Update your remote web application to use the new client secret. For more information, see the 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.

Important

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

Use OAuth to authenticate and authorize add-ins

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) to provide tokens instead of credentials (for example, user name and password) to their data that hosts by a given service provider (for example, SharePoint). 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 non-Microsoft 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 secrets in Partner Center, and then add them to your add-in code.

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 delegates to an add-in.

For example, your add-in could be a trip calendar add-in that opens as an IFRAME on a Microsoft 365 SharePoint site. OAuth lets the add-in identify the user to whom the trip calendar belongs. Or if the trip calendar add-in needs to access other aspects of Microsoft 365, such as resources or calendar information, it could access them on behalf of the signed-in user.

Note

For more information about OAuth, client ID, and client secrets, see Authorization and authentication of SharePoint Add-ins, Context Token OAuth flow for SharePoint Add-ins, and Register SharePoint Add-ins 2013.

Add a client ID and client secret

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

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.
  • Add a separate add-in package specifically for China.
  • Block access for all countries/regions except China.
  • Create a separate add-in listing for China.

For more information about distributing add-ins to China, see Submit apps for Office 365 operated by 21Vianet in China.

Inbound data to your add-in is signed by using only one signing client secret. In Partner Center, it's the client secret with a green check mark next to Active in the Status column on the Client IDs page. If you delete the signing client secret that your add-in uses, the next valid client secret is 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's 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 needs OAuth client IDs and client secrets, follow these steps.

Add a new client ID

Important

The offer must be published on Microsoft stores before using the client IDs in production. Failing to do so can negatively affect the usability of your app by your customers. We recommend that you move unpublished apps to SharePoint Solutions as the SharePoint add-ins are being phased out.

  1. Sign in to Partner Center with your developer account and go to the Product overview page for your add-in.

  2. On the Client IDs tab, select Add new client ID.

  3. In the New client ID dialog box, provide the following information.

    Item Information to provide
    Friendly name Select a name to help you recognize which add-in uses the client ID; for example, "calendar app"
    App domain Provide the domain on which your add-in runs. For example: app.contoso.com.
    It 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
    App 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://, http://, or ms-app://

  4. Select Create secret now.

  5. Choose how long your client secret is valid for. The options are one, two, or three years. We recommend choosing one year, because it might be easier to track within your business processes than longer time periods. But there's no security implication to choosing two or three years. When the client secret is expiring, you need to update your add-in.

  6. Select which type of client secret availability:

    • This client ID will be used for an app that is available worldwide.
    • This client ID will be used for an app that is available in China only.

  7. Choose Create secret now.

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

    Important

    The client secret is associated with your client ID, but it isn't shown in Partner Center again so be sure to record it. Also, record the start and end dates, so that you're aware of the client secret period of validity and its expiration date. If your client secret is close to expiring, you need to generate a new client secret and update your add-in. For more information, see Update the client secret associated with your client ID.

  9. Select Done.

Update the client secret associated with your client ID

Update your client secret in the following situations:

  • Your client secret is expiring

    We recommend that you add a new client secret in Partner Center 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 by choose Delete next to that entry on the Client IDs page in Partner Center.

    Note

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

  • The security of your client secret is compromised

    To respond to a security compromise quickly, you can delete the compromised client secret from Partner Center first, add a new client secret, and then update your add-in with the new client secret.

    Important

    After you delete a compromised client secret and before you add the new client secret, your add-in might be temporarily unavailable. But that scenario might be better than the potentially severe business impacts resulting from a lost or stolen client secret.

Generate other client secrets

  1. Sign in to Partner Center with your developer account and go to the Product overview page for your add-in.

  2. On the Client IDs tab, select the client ID with which you want to associate other client secrets.

  3. On the client ID detail page, select New client secret.

  4. Choose how long you want the secret to be valid for. The options are one, two, or three years.

  5. Select Create.

  6. In the Get client secret dialog box, copy the client secret to a secure location so that you can refer to it later.

    Important

    The client secret is associated with your client ID, but it isn't shown in Partner Center again so be sure to record it. Also, record the start and end dates so that you're aware of the client secret period of validity and its expiration date.

  7. Select Done.

    Note

    The new client secret is active within 15 minutes.

Delete a client secret

  1. Sign in to Partner Center with your developer account and go to the Product overview page for your add-in.

  2. On the Client IDs tab, select Delete next to the client ID that has the client secret that you want to delete.

    Important

    Deleting a client secret can prevent your add-in from accessing the data it needs, unless you created extra secrets that you validate and associate with your add-in. You must also configure your add-in to use the extra client secrets. If you have only one client secret associated with the client ID, we recommend that you generate another client secret before you delete it.

  3. In the Confirmation dialog box, select Delete.

Delete a client ID

You might 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. In this situation, you might want to delete the client ID you associated with the previous version of your add-in.

Warning

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

  1. Sign in to Partner Center with your developer account and go to the Product overview page for your add-in.
  2. On the Client IDs tab, select Delete next to the client ID that has the client secret that you want to delete.
  3. In the Confirmation dialog box, select Delete.

To delete a client ID, but continue offering your add-in

  1. Add another client ID and at least one valid client secret. For details, see Add a client ID and client secret.

  2. Delete the client ID from your code.

  3. Delete the client ID from Partner Center, as described in the previous procedure.

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

  5. On the Product overview page, choose Publish.

    Note

    Customers using your add-in experience downtime during the update to your code and the Partner Center approval process.

Related content