Skip to content

Commit

Permalink
Updated instructions for trusting the certificate. (#268)
Browse files Browse the repository at this point in the history 
* Updated instructions for trusting the certificate.
  • Loading branch information
@MIchaelMainer
MIchaelMainer committed Dec 15, 2017
1 parent 0b726d2 commit 21a91b1
Show file tree
Hide file tree
Showing 2 changed files with 52 additions and 109 deletions.
98 changes: 41 additions & 57 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,14 @@
[![Downloads](http://img.shields.io/npm/dm/generator-office.svg)](https://npmjs.org/package/generator-office)
[![TravisCI Build Status](https://travis-ci.org/OfficeDev/generator-office.svg)](https://travis-ci.org/OfficeDev/generator-office)

[Yeoman](http://yeoman.io) generator for creating [Microsoft Office Add-in](https://dev.office.com/docs/add-ins/overview/office-add-ins) projects using any text editor. Microsoft includes fantastic & [rich development tools for creating Office related projects using Visual Studio 2013](http://aka.ms/OfficeDevToolsForVS2013) or [tools for Visual Studio 2015](http://aka.ms/OfficeDevToolsForVS2015). This generator is for those developers who:
[Yeoman](http://yeoman.io) generator for creating [Microsoft Office Add-in](https://docs.microsoft.com/en-us/office/dev/add-ins/) projects using any text editor. Microsoft includes fantastic & [rich development tools for creating Office related projects using Visual Studio 2013](http://aka.ms/OfficeDevToolsForVS2013) or [tools for Visual Studio 2015](http://aka.ms/OfficeDevToolsForVS2015). This generator is for those developers who:

- use an editor other than Visual Studio
- are interested in using a technology other than plain HTML, CSS & JavaScript

> If you are building an Angular or React add-in and would like to learn more about using Yo Office specifically for those frameworks, see [Build an Add-in with React](https://dev.office.com/docs/add-ins/excel/excel-add-ins-get-started-react) or [Build an Add-in with Angular](https://dev.office.com/docs/add-ins/excel/excel-add-ins-get-started-angular).
> If you are building an Angular or React add-in and would like to learn more about using Yo Office specifically for those frameworks, see [Build an Add-in with React](https://docs.microsoft.com/en-us/office/dev/add-ins/excel/excel-add-ins-get-started-react) or [Build an Add-in with Angular](https://docs.microsoft.com/en-us/office/dev/add-ins/excel/excel-add-ins-get-started-angular).
Like other Yeoman generators, this simply creates the scaffolding of files for your Office project. It allows you to create add-ins for:
Like other Yeoman generators, this simply creates the scaffolding of files for your Office Add-in project. It allows you to create add-ins for:

- Excel
- OneNote
Expand All @@ -20,7 +20,7 @@ Like other Yeoman generators, this simply creates the scaffolding of files for y
- Project
- Word

Choose to create the Office projects using plain HTML, CSS & JavaScript (*mirroring the same projects that Visual Studio creates*) or create Angular-based projects.
Choose to create Office Add-in projects using plain HTML, CSS & JavaScript (*mirroring the same projects that Visual Studio creates*) or create Angular-based projects.

If you are interested in contributing, read the [Contributing Guidelines](CONTRIBUTING.md).

Expand All @@ -45,82 +45,38 @@ $ yo office [arguments] [options]

The generator is intended to be run from within a folder where you want the project scaffolding created. This can be in the root of the current folder or within a subfolder.

## Running the Generated Site

Office Add-ins must be hosted, even in development, in a HTTPS site. Yo Office creates a `bsconfig.json`, which uses [Browsersync](https://browsersync.io/) to make your tweaking and testing faster by synchronizing file changes across multiple devices.

> **Important:** There is currently a bug in the code that generates and trusts the SSL certificate that is needed to run the add-in with HTTPS. Before you continue with this Readme, take the following workaround steps:
>
> 1. Go to {project root}\node_modules\browser-sync\lib\server\certs.
> 2. Rename or delete all the files there or move them to a subfolder.
> 3. Copy the file gen-cert.sh from the root of this repo into the folder.
> 4. Run gen-cert.sh.
> 5. Several files are generated.
> 6. Double-click ca.crt, and select **Install Certificate**.
> 7. Select **Local Machine** and select **Next** to continue.
> 8. Select **Place all certificates in the following store** and then select **Browse**.
> 9. Select **Trusted Root Certification Authorities** and then select **OK**.
> 10. Select **Next** and then **Finish**.

Launch the local HTTPS site on `https://localhost:3000` by simply typing the following command in your console:

```bash
$ npm start
```

Browsersync will start a HTTPS server, which includes a self-signed SSL cert that your development environment must trust. Refer to our doc, [Adding Self-Signed Certificates as Trusted Root Certificate](src/docs/ssl.md), for instructions on how to do this.

> **Important:** You may still face issue with the Browsersync self-signed SSL certificated since the certificate is signed for domain "Internet Widgits Pty Ltd" instead of localhost. See [this issue](https://github.com/OfficeDev/generator-office/issues/244) for more details and temporary workaround.
Browse to the 'External' IP address listed in your console to test your web app across multiple browsers and devices that are connected on your local network.

![](src/docs/assets/browsersync.gif)

## Validate manifest.xml

As you modify your `manifest.xml` file, use the included [Office Add-in Validator](https://github.com/OfficeDev/office-addin-validator) to ensure that your XML file is correct and complete. It will also give you information on against what platforms to test your add-ins before submitting to the store.

To run Office Add-in Validator, use the following command in your project directory:
```bash
$ npm run validate your_manifest.xml
```
![](src/docs/assets/validator.gif)

For more information on manifest validation, refer to our [add-in manifests documentation](https://dev.office.com/docs/add-ins/overview/add-in-manifests).
### Command Line Arguments
The following command line arguments are supported. The generator will prompt you accordingly based upon the arguments that you specify.

## Command Line Arguments:
List of supported arguments. The generator will prompt you accordingly based on the arguments you provided.

### `name`
#### `name`
Title of the project - this is the display name that is written the manifest.xml file.
- Type: String
- Optional

>**Note:** The Windows command prompt requires this argument to be in quotes (e.g. "My Office Add-in")
### `host`
#### `host`
The Microsoft Office client application that can host the add-in. The supported arguments include Excel (`excel`), OneNote (`onenote`), Outlook (`outlook`), PowerPoint (`powerpoint`), Project (`project`), and Word (`word`).
- Type: String
- Optional

### `framework`
#### `framework`
Framework to use for the project. The supported arguments include JQuery (`jquery`), Angular (`angular`), and React (`react`). You can also use Manifest Only (`manifest-only`) which will create only the `manifest.xml` for an Office Add-in.
- Type: String
- Optional

## Command Line Options:
List of supported options. If these are not provided, the generator will prompt you for the values before scaffolding the project.
### Command Line Options
The following command line options are supported. If these are not specified, the generator will prompt you for the values before scaffolding the project.

### `--skip-install`
#### `--skip-install`

After scaffolding the project, the generator (and all sub generators) run all package management install commands such as `npm install` & `typings install`. Specifying `--skip-install` tells the generator to skip this step.

- Type: Boolean
- Default: False
- Optional

### `--js`
#### `--js`

Specifying `--js` tells the generator to use JavaScript.

Expand All @@ -130,4 +86,32 @@ Specifying `--js` tells the generator to use JavaScript.

>**Note:** Do not use this flag when you pass `react` as framework argument.
## Running the Generated Site

Office Add-ins must be hosted in an HTTPS site. Yo Office generates a [Browsersync](https://browsersync.io/) configuration file (`bsconfig.json`) that references a self-signed certificate. Your computer will need to trust the certificate before you can use the generated add-in.

**Important:** Follow the instructions in [Adding Self-Signed Certificates as Trusted Root Certificate](src/docs/ssl.md) before you start your web application.

Launch the local HTTPS site on `https://localhost:3000` by simply typing the following command in your console:

```bash
$ npm start
```

Browse to the 'External' IP address listed in your console to test your web app across multiple browsers and devices that are connected on your local network.

![](src/docs/assets/browsersync.gif)

## Validate manifest.xml

As you modify your `manifest.xml` file, use the included [Office Add-in Validator](https://github.com/OfficeDev/office-addin-validator) to ensure that your XML file is correct and complete. It will also give you information on against what platforms to test your add-ins before submitting to the store.

To run Office Add-in Validator, use the following command in your project directory:
```bash
$ npm run validate your_manifest.xml
```
![](src/docs/assets/validator.gif)

For more information on manifest validation, refer to our [add-in manifests documentation](https://docs.microsoft.com/en-us/office/dev/add-ins/develop/add-in-manifests).

Copyright (c) 2017 Microsoft Corporation. All rights reserved.
63 changes: 11 additions & 52 deletions src/docs/ssl.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,16 +17,13 @@ To fix this, you need to configure your developer workstation to trust the self-
* [Get certificate file from project directory](#get-certificate-file-from-project-directory)
* [Add certification file to Key Chain Access](#add-certification-file-to-key-chain-access)
* [Windows](#windows)
* [Get certificate file from project directory](#get-certificate-file-from-project-directory-1)
* [Add certification file through IE](#add-certification-file-through-ie)
* [Add certification file through Management Console](#add-certification-file-through-management-console)

## [OS X](https://support.apple.com/kb/PH18677)

#### Get certificate in Chrome

1. Start Chrome and do the following:
1. Open Developer Tools window by using keybaord shortcuts: Cmd + Opt + I.
1. Open Developer Tools window by using keyboard shortcuts: Cmd + Opt + I.
1. Click to go to 'security' panel and 'overview' screen.
1. Click 'View certificate'.

Expand All @@ -37,7 +34,7 @@ To fix this, you need to configure your developer workstation to trust the self-

#### Get certificate file from project directory

You can locate the server.crt file at **~/your_yo_office_project/node_modules/browser-sync/lib/server/certs/server.crt**
You can locate the server.crt file at **~/your_yo_office_project/certs/server.crt**

#### Add certification file to Key Chain Access

Expand All @@ -59,58 +56,20 @@ At this point everything has been configured. Quit all browsers, then reopen and

## [Windows](https://technet.microsoft.com/en-us/library/cc754841.aspx)

#### Get certificate file from project directory

You can locate the server.crt file at **~/your_yo_office_project/node_modules/browser-sync/lib/server/certs/server.crt**

#### Add certification file through IE
Take the following steps to setup the certificate authority cert for localhost:

1. Start IE with your local host url.
1. Select **Continue to this website (not recommended).**
![](assets/ssl-ie-01.png)
1. Click **Certificate Error** at the end of the address bar.
![](assets/ssl-ie-02.png)
1. In the drop down window, click **View certificates** at the bottom.
![](assets/ssl-ie-03.png)
1. In the Certificate window, click **Install Certificate...** button then click **OK**.
1. Go to {project root}\certs.
2. Double-click ca.crt, and select **Install Certificate**.

![](assets/ssl-ie-04.png)
1. This will take you to Certificate Import Wizard. Select **Local Machine** for store location then click **Next**.
![](assets/ssl-ie-05.png)
1. System now will prompt you security information. Click **Yes** to allow changes.
![](assets/ssl-ie-06.png)
1. In the Wizard, select **Place all certificates in the following store** and then click **Browse...** button.
![](assets/ssl-ie-07.png)
1. Select **Trusted Root Certification Authorities** folder and click **OK**.
![](assets/ssl-ie-08.png)
1. Now make sure **Trusted Root Certification Authorities** is in place for **Certificate store** and click **Next**.
![](assets/ssl-ie-09.png)
1. Your cert is now ready to be imported. Click **Finish**.
![](assets/ssl-ie-10.png)

You now have a self-signed certificate installed on your machine.

#### Add certification file through Management Console

1. Click **Start**, go to **Search box**, type **run**, then type **mmc** in the input field, and then press **ENTER**.
2. On the **File** menu, click **Add/Remove Snap-in**.

![](assets/ssl-windows-01.png)
3. Select **Local Machine** and select **Next** to continue.

3. Under **Available snap-ins**, click **Certificates**, and then click **Add**.
![](assets/ssl-windows-02.png)

4. Under **This snap-in will always manage certificates for**, click **Computer account**, and then click **Next**.
![](assets/ssl-windows-03.png)
![](assets/ssl-ie-05.png)

5. Click **Local computer**, and click **Finish**.
![](assets/ssl-windows-04.png)
6. If you have no more snap-ins to add to the console, click **OK**.
7. In the console tree, double-click **Certificates**.
8. Right-click the **Trusted Root Certification Authorities** store.
9. Click **All Tasks** then **Import** to import the certificates and follow the steps in the Certificate Import Wizard.
![](assets/ssl-windows-05.png)
10. Find server.crt file and click **Open**.
11. Follow the rest of the steps to finish Certificate import.
4. Select **Place all certificates in the following store** and then select **Browse**.
5. Select **Trusted Root Certification Authorities** and then select **OK**.
6. Select **Next** and then **Finish**.

You now have a self-signed certificate installed on your machine.

Expand Down

0 comments on commit 21a91b1

Please sign in to comment.