npm package: @meetingmaker/office-js-helpers
Description: A collection of helpers to simplify development of Office Add-ins & Microsoft Teams Tabs
Author: Microsoft
Latest version: 1.0.2

> # ❗️ Deprecation Notice ❗️ [![No Maintenance Intended](badge.svg)](https://www.npmjs.com/package/@microsoft/office-js-helpers)
>**Thank you** for all your efforts and contributions!
> ``` office-js-helpers ``` is a community-driven package of sample code that encapsulates a set of convenience functions. The package was initially developed as an example abstraction to common patterns found by developers.
> The community has been great at submitting ideas, issues, and fixes. As part of our latest campaign to ensure developers can quickly discover content and code, we are consolidating the many locations we post patterns and practices. To ensure we can focus our attention on the quality of content, we have deprecated the ```office-js-helpers``` package and archived this repository.

> ## Can I still use this code?
> **Security vulnerabilities may exist in the project, or its dependencies.** If you plan to reuse or run any code from this repo, be sure to perform appropriate security checks on the code or dependencies first.
> If you find these samples, patterns, and convenience functions useful, we encourage you to take the code under your wing, improve them, and use it on your own. Even though Microsoft will no longer be supporting this content going forward, you may use the code at your convenience, external to the package.

> ## What will happen next?
> 
> To ensure that the community has some content and solutions for the common patterns and practices for Office Add-in, we have consolidated the content and will be providing additional material here soon.

# Office JavaScript API Helpers
[![No Maintenance Intended](badge.svg)](https://www.npmjs.com/package/@microsoft/office-js-helpers)

The current version includes the following helpers:
- [Authentication](#authentication)
- Dialogs
- Error Logging
- Storage Helpers
- Dictionary

## Getting Started

### Installation

#### Development
> This assumes you are using npm as your package manager.

To install the stable version:

`npm install --save @microsoft/office-js-helpers`

#### Production

You can access [these files on unpkg](https://unpkg.com/@microsoft/office-js-helpers@1.0.0/dist/office.helpers.min.js), download them, or point your package manager to them.

You can also get the latest version from the [releases](https://github.com/OfficeDev/office-js-helpers/releases) tab

## Usage

### JavaScript

Ensure that the Office.js file is loaded inside of your `.html` page using:
```html
<!-- Office.js -->
<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>

<!-- ES6 Shim of your choice -->
<script src="https://unpkg.com/core-js/client/core.min.js"></script>
```

Then reference the helpers library using one of the following:
```html
<!-- Office JavaScript API Helpers (via CDN) -->
<script src="https://unpkg.com/@microsoft/office-js-helpers@1.0.0/dist/office.helpers.min.js"></script>

<!-- Office JavaScript API Helpers (via npm) -->
<script src="node_modules/@microsoft/office-js-helpers/dist/office.helpers.min.js"></script>

<!-- Office JavaScript API Helpers (via local) -->
<script src="office.helpers.js"></script>
```

### TypeScript

**If you are just referencing the library using a script tag** then make sure to set your `moduleResolution` to `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 `typings` to get access to the definitions.

**If you are using any dependency loader** such as [RequireJS](http://requirejs.org/) or [SystemJS](https://github.com/systemjs/systemjs) or module bundler such as [browserify](http://browserify.org/), [webpack](https://webpack.github.io/), you can use TypeScript `import` syntax to import specific modules. For example, one of the following:

```typescript
import * as OfficeHelpers from '@microsoft/office-js-helpers';

import {Authenticator, DefaultEndpoints} from '@microsoft/office-js-helpers';

import {Authenticator, Storage} from '@microsoft/office-js-helpers';

import {Authenticator} from '@microsoft/office-js-helpers';
```

## Helpers

### Authentication

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.

> **Note on MSAL**: This helper isn't a replacement for MSAL. When MSAL for JavaScript is released publicly, the helper will use MSAL.

#### For Office Add-ins
You need to meet the following requirements before you are able to successfully use the Authenticator inside Office Add-ins.

1. 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.
2. Add the location of the provider in the [AppDomains](https://docs.microsoft.com/office/dev/add-ins/reference/manifest/appdomains) section of your add-in's manifest, as shown in the following example:

```xml
    <AppDomain>https://login.windows.net</AppDomain>
    <AppDomain>https://login.microsoftonline.com</AppDomain>
```

#### Setup the authenticator
Inside of your [Office.initialize](https://docs.microsoft.com/office/dev/add-ins/develop/understanding-the-javascript-api-for-office#initialize-with-officeinitialize) function add the following check:

```javascript
if (OfficeHelpers.Authenticator.isAuthDialog()) 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 `state` sent to the provider is the same as what was returned, to prevent [Cross Site Request Forgery (CSRF)](http://www.twobotechnologies.com/blog/2014/02/importance-of-state-in-oauth2.html).

> **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.

#### Initialize the authenticator
Create a new instance of `Authenticator` and register the endpoints. An endpoint corresponds to a service that allows the user to authenticate with.

```javascript
var authenticator = new OfficeHelpers.Authenticator();
```

Then use one of the following:

```javascript
// register Microsoft (Azure AD 2.0 Converged auth) endpoint using
authenticator.endpoints.registerMicrosoftAuth('client id here');

// register Azure AD 1.0 endpoint using
authenticator.endpoints.registerAzureADAuth('client id here', 'tenant here');

// register Google endpoint using
authenticator.endpoints.registerGoogleAuth('client id here');

// register Facebook endpoint using
authenticator.endpoints.registerFacebookAuth('client id here');

// register any 3rd-Party OAuth Implicit Provider using
authenticator.endpoints.add('Name of provider', { /* Endpoint Configuration - see office-js-helpers/src/authentication/endpoint.manager.ts */ })

// register Microsoft endpoint by overriding default values
authenticator.endpoints.registerMicrosoftAuth('client id here', {
    redirectUrl: 'redirect url here',
    scope: 'list of valid scopes here'
});
```

#### Authentication
To authenticate against the registered endpoint, do one of the following:

```javascript
authenticator
    .authenticate('name of endpoint')
    .then(function(token) { /* handle success here */ })
    .catch(OfficeHelpers.Utilities.log);

// for the default Microsoft endpoint
authenticator
    .authenticate(OfficeHelpers.DefaultEndpoints.Microsoft)
    .then(function (token) { /* Microsoft Token */ })
    .catch(OfficeHelpers.Utilities.log);

// for the default AzureAD endpoint
authenticator
    .authenticate(OfficeHelpers.DefaultEndpoints.AzureAD)
    .then(function (token) { /* Microsoft Token */ })
    .catch(OfficeHelpers.Utilities.log);

// for the default Google endpoint
authenticator
    .authenticate(OfficeHelpers.DefaultEndpoints.Google)
    .then(function (token) { /* Google Token */ })
    .catch(OfficeHelpers.Utilities.log);

// for the default Facebook endpoint
authenticator
    .authenticate(OfficeHelpers.DefaultEndpoints.Facebook)
    .then(function (token) { /* Facebook Token */ })
    .catch(OfficeHelpers.Utilities.log);
```
If the user rejects the grant to the application then you will receive an error in the `catch` function.

#### 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.

```javascript
authenticator
    .authenticate('name of endpoint')
    .then(function(token) {
    /*
        `token` is either cached or newly obtained upon expiry.
    */
    })
    .catch(OfficeHelpers.Utilities.log);

authenticator
    .authenticate('name of endpoint', true /* force re-authentication */)
    .then(function(token) {
    /*
        `token` is newly obtained.
    */
    })
    .catch(OfficeHelpers.Utilities.log);

// get the cached token if any. returns null otherwise.
var token = authenticator.tokens.get('name of endpoint');
```
If a cached token expires, then the dialog is automatically launched to re-authenticate the user.
> **Note on Refresh Tokens**: By default, Implicit OAuth does not support Token Refresh as a security measure. This is because Access Tokens cannot be securely stored inside a JavaScript client.

## Contributing

Please read [Contributing](contributing.md) for details on our code of conduct, and the process for submitting pull requests to us.

This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.

## Versioning

We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/officedev/office-js-helpers/tags).

## License

This project is licensed under the MIT License - see the [License](LICENSE) file for details.