We are excited to announce that the single sign-on (SSO) functionality for Office Add-ins is moving to General Availability with version 2008. This authentication service allows an add-in to automatically and securely sign in a user after being granted consent, providing a more convenient experience by reducing the number of times they are requested to sign in. SSO works with both work and school accounts as well as Microsoft accounts.
Updates from the preview offering
There are a few changes from the current preview offering. Specifically, validations occur when an add-in is submitted to AppSource to make sure that the manifest is correctly formatted. This validation verifies that:
- The Application ID is an appropriately formatted GUID.
- The Resource URI is appropriately formatted, as seen in this example:
where AppID_GUID matches the GUID from your App registration in Azure AD.
- The Resource URI does not contain Unicode characters.
- The minimum required scopes are listed in the Scopes section, openID, and profile.
An add-in will be rejected from AppSource if it does not meet this criteria, and AppSource will respond to the developer with the reasons why and given documentation how to fix it. Submission of an SSO enabled add-in to AppSource will be accepted beginning Monday August 24, 2020.
The requirement set for SSO, the IdentityAPI requirement set, will be version incremented for GA to version 1.3. Add-ins declaring a requirement set version of the IdentityAPI that is less than 1.3 will not be able to use SSO after version 2008 reaches the Current Channel. IdentityAPI 1.3 is the only supported version.
A new client ID has been added that services will be required to preauthorize. If you tried SSO during the preview phase, make sure to add it to your existing application registration in Azure AD. You can find all the client ID preauthorizations required in our documentation.
Single sign–on best practices
There are some additional best practices that developers should follow when enabling SSO in an add-in.
- Ensure the add-in has a fallback method to sign in a user in case an issue is encountered with SSO. You can find additional details in our documentation as it can vary by scenario and host.
- If the add-in accesses data with Microsoft Graph, be sure to use the ‘forMSGraph’ property in the AuthOptions. This allows Office to return immediately if you are on a host that doesn’t support SSO or if the add-in wasn’t deployed via centralized deployment and consent to Microsoft Graph hasn’t been granted yet. In these scenarios, the backup authentication method is used immediately instead of waiting for the initial SSO call to return with an error.
- Always ask for the least amount of privilege when requesting scopes.
- Make sure to preauthorize the required client IDs. Currently, there are 5, but additional IDs may be added in the future to enable new functionality. You can find the full list in our documentation.
Getting started using SSO in your add-ins
We can’t wait to see what add-ins take advantage of SSO with this new capability. There are multiple resources for getting started, including samples for creating SSO enabled add-ins with ASP.NET and Node.js, as well as a quick start that uses the Yeoman Office Add-in tooling and can automatically register your app in Azure. We look forward to seeing the SSO enabled add-ins you create!