A collection of helpers to simplify development of Office Add-ins & Microsoft Teams Tabs. These helpers address features as Storage Management, Authentication, Dialogs and other helpful utilities etc.
The current version includes the following helpers:
- Error Logging
- Storage Helpers
This assumes you are using npm as your package manager.
To install the stable version:
npm install --save @microsoft/office-js-helpers
You can access these files on unpkg, download them, or point your package manager to them.
You can also get the latest version from the releases tab
Reference the library inside of your
.html page using:
If you are just referencing the library using a script tag then make sure to set your
node in your tsconfig.json to pickup the intellisense automatically. You will need to install the package via
npm install @microsoft/office-js-helpers.
We will publish to DefinitelyTyped soon and then you can directly use
typingsto get access to the definitions.
The Authentication helper is built for standards compliant OAuth Implicit Flow. Out of the box it directly integrates with Microsoft, AzureAD, Google and Facebook authentication.
Microsoft integration uses the AzureAD AppModel v2 endpoints which uses Converged Authentication. It enables users to login using their Work, School or Personal accounts.
For Office Add-ins
You need to meet the following requirements before you are able to successfully to use the Authenticator inside of Office Add-ins.
- You need to use
https. This is important as we are using OAuth Implicit Flow and it is critical to secure the communication over the wire.
- Add the location of the provider in your
Inside of your
Office.initialize function add the following check:
if OfficeHelpersAuthenticator return;
This to inform the Authenticator to automatically close the authentication dialog once the authentication is complete.
Note: This code needs to be run in the page that is redirected to from the provider. By default we assume the root url of your website. The code ensures that if an access_token, code or error was received inside of the dialog, then it will parse it and close the dialog automatically. Also as an additional step it ensures that the
statesent to the provider is the same as what was returned, to prevent Cross Site Request Forgery (CSRF).
Note: If using in an AngularJS/Angular/React project - please take a look https://github.com/OfficeDev/office-js-helpers/issues/19 for information around bootstrapping your application correctly.
Create a new instance of
Authenticator and register the endpoints. An endpoint corresponds to a service that allows the user to authenticate with.
var authenticator = ;// register Microsoft (Azure AD 2.0 Converged auth) endpoint usingauthenticatorendpoints;// register Azure AD 1.0 endpoint usingauthenticatorendpoints;// register Google endpoint usingauthenticatorendpoints;// register Facebook endpoint usingauthenticatorendpoints;// register any 3rd-Party OAuth Implicit Provider usingauthenticatorendpoints// register Microsoft endpoint by overriding default valuesauthenticatorendpoints;
To authenticate against the registered endpoint, do the following:
authenticator;// for the default Microsoft endpointauthenticator;// for the default AzureAD endpointauthenticator;// for the default Google endpointauthenticator;// for the default Facebook endpointauthenticator;
If the user, rejects the grant to the application then you will receive an error in the
Getting a cached token
By default the tokens are cached to the LocalStorage and upon expiry the AuthDialog is invoked again. You can also pass the
force parameter as
true as the second input to
authenticator.authenticate() to re-authenticate the user.
authenticator;authenticator;// get the cached token if any. returns null otherwise.var token = authenticatortokens;
If a cached token expires, then the dialog is automatically launched to re-authenticate the user.
Please read Contributing for details on our code of conduct, and the process for submitting pull requests to us.
This project is licensed under the MIT License - see the License file for details