From 491f03721ca5e2fbd542cc0817d547fa15908c0e Mon Sep 17 00:00:00 2001 From: RogerSelwyn Date: Fri, 5 Jan 2024 18:40:12 +0000 Subject: [PATCH] doc: Update docs for removal of legacy config format --- docs/authentication.md | 3 +- docs/calendar_configuration.md | 2 +- docs/installation_and_configuration.md | 45 ++------------------------ docs/legacy_migration.md | 18 ----------- docs/permissions.md | 4 +-- docs/prerequisites.md | 2 -- 6 files changed, 6 insertions(+), 68 deletions(-) delete mode 100644 docs/legacy_migration.md diff --git a/docs/authentication.md b/docs/authentication.md index 979351a..d492cbd 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -4,11 +4,10 @@ nav_order: 5 --- # Authentication - _**NOTE:** As of version 3.2.0, the primary (default) and alternate authentication methods have essentially reversed. The primary (default) method now DOES NOT require direct access to your HA instance from the internet while the alternate method DOES require direct access. If you previously did NOT set 'alt_auth_flow' or had it set to False, please set 'alt_auth_method' to True and remove 'alt_auth_flow' from your config. This will only be necessary upon re-authentication._ The Primary method of authentication is the simplest to configure and requires no access from the internet to your HA instance, therefore is the most secure method. It has slightly more steps to follow when authenticating. -The alternate method is more complex to set up, since the Azure App that is created in the prerequisites section must be configured to enable authentication from your HA instance whether located in your home network or utilising a cloud service such as Nabu Casa. The actual authentication is slightly simpler with fewer steps. +The alternate method is more complex to set up, since the Azure App that is created in the prerequisites' section must be configured to enable authentication from your HA instance whether located in your home network or utilising a cloud service such as Nabu Casa. The actual authentication is slightly simpler with fewer steps. During setup, the difference in configuration between each method is the value of the redirect URI on your Azure App. The authentication steps for each method are shown below. diff --git a/docs/calendar_configuration.md b/docs/calendar_configuration.md index 77862df..d2b6899 100644 --- a/docs/calendar_configuration.md +++ b/docs/calendar_configuration.md @@ -4,7 +4,7 @@ nav_order: 6 --- # Calendar configuration -The integration uses an external `o365_calendars_.yaml` file (or `o365_calendars.yaml` for the secondary (deprecated) configuration format) which is stored in the `o365_storage` directory. +The integration uses an external `o365_calendars_.yaml` file which is stored in the `o365_storage` directory. ## Example Calendar yaml: ```yaml - cal_id: xxxx diff --git a/docs/installation_and_configuration.md b/docs/installation_and_configuration.md index 47d3994..34ed57c 100644 --- a/docs/installation_and_configuration.md +++ b/docs/installation_and_configuration.md @@ -16,7 +16,7 @@ nav_order: 4 1. Restart your Home Assistant instance again to enable your configuration. 1. A notification will be shown in the Repairs dialogue of your HA instance. Follow the instructions on this notification (or see [Authentication](./authentication.md)) to establish the link between this integration and the Azure app * A persistent token will be created in the hidden directory config/o365_storage/.O365-token-cache - * The `o365_calendars_.yaml` (or `o365_calendars.yaml` for secondary (deprecated) configuration method) will be created under the config directory in the `o365_storage` directory. + * The `o365_calendars_.yaml` will be created under the config directory in the `o365_storage` directory. * If todo_sensors is enabled then `o365_tasks_.yaml` will be created under the config directory in the `o365_storage` directory. 1. [Configure Calendars](./calendar_configuration.md) 1. [Configure To-Dos](./todos_configuration.md) (if required) @@ -26,9 +26,8 @@ nav_order: 4 ## Configuration examples -### Primary configuration format (as of v3.x.x) - Preferred because it provides improved security and allows for multiple accounts. +### Configuration format ```yaml -# Example configuration.yaml entry for multiple accounts o365: accounts: - account_name: Account1 # Do not use email address or spaces @@ -60,37 +59,9 @@ o365: client_secret: "xx.xxxxxxxxxxxxxxxxxxxxxxxxxxxx" client_id: "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx" ``` -### Secondary (DEPRECATED) configuration format - Less preferred and can only use for a single account. -```yaml -# Example configuration.yaml entry for single account -o365: - client_id: "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx" - client_secret: "xx.xxxxxxxxxxxxxxxxxxxxxxxxxxxx" - alt_auth_method: False - enable_update: False - email_sensor: - - name: inbox - max_items: 2 - is_unread: True - download_attachments: False - query_sensors: - - name: "Example" - folder: "Inbox/Test_Inbox" #Default is Inbox - from: "mail@example.com" - subject_contains: "Example subject" - has_attachment: True - max_items: 2 - is_unread: True - status_sensors: # Cannot be used for personal accounts - - name: "User Teams Status" - chat_sensors: # Cannot be used for personal accounts - - name: "User Chat" -``` ### Configuration variables -#### Primary format - Key | Type | Required | Description -- | -- | -- | -- `account_name` | `string` | `True` | Uniquely identifying name for the account. Calendars entity names will be suffixed with this. `calendar.calendar_account1` @@ -109,18 +80,6 @@ Key | Type | Required | Description `auto_reply_sensors` | `object` | `False` | Auto-reply sensor options *Not for use on shared mailboxes* `shared_mailbox` | `string` | `False` | Email address or ID of shared mailbox *Only available for calendar and email sensors* -#### Secondary format - -Key | Type | Required | Description --- | -- | -- | -- -`client_id` | `string` | `True` | Client ID from your O365 application. -`client_secret` | `string` | `True` | Client Secret from your O365 application. -`alt_auth_method` | `boolean` | `False` | If False (default), authentication is not dependent on internet access to your HA instance. [See Authentication](./authentication.md) -`enable_update` | `boolean` | `False` | If True (**default is True**), this will enable the various services that allow the sending of emails and updates to calendars -`track_new_calendar` | `boolean` | `False` | If True (default), will automatically generate a calendar_entity when a new calendar is detected. The system scans for new calendars only on startup. -`email_sensors` | `list` | `False` | List of email_sensor config entries -`query_sensors` | `list` | `False` | List of query_sensor config entries -`status_sensors` | `list` | `False` | List of status_sensor config entries. *Not for use on personal accounts* #### email_sensors diff --git a/docs/legacy_migration.md b/docs/legacy_migration.md deleted file mode 100644 index e69da1e..0000000 --- a/docs/legacy_migration.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Legacy Migration -nav_order: 20 ---- - -# Legacy Migration -Historically the Office 365 Calendar o=integration supported a single account. Over the last year several features have been added including support for multiple accounts. This change to multiple accounts necessitated an alternate configuration schema. - -Having two schemas introduces extra complexity into the integration, so the secondary/legacy schema is now being marked as deprecated to encourage migration to the new schema (which has been the preferred one since May 2022). - -To assist in this migration, when you restart Home Assistant, the following things will happen: -1. A modified version of the configuration will be created on the `o365_storage` folder called `o365_converted_configuration.yaml`. You should be able to copy the contents of this file and replace your existing configuration. Your `client_id` and `client_secret` have been obfuscated with `xxxx` so, you will need to replace these. -2. Your token file has been copied as `o365_converted.token` -3. Your `o365_calendar.yaml` file has been copied as `o365_calendars_converted.yaml` - -After modifying your config as in (1) above and then restarting Home Assistant, you should no longer have the repair warning and your calendars (and other sensors) should be present as before. - -If you decide to change the account name from `converted`, then calendars will be created with `_account_name` on the end, and you will need to re-authenticate and reconfigure your o365_calendars.yaml file. Alternatively, you can perform steps (2) and (3) above using your new account name instead of `converted` in the name. diff --git a/docs/permissions.md b/docs/permissions.md index 693ce70..544ec21 100644 --- a/docs/permissions.md +++ b/docs/permissions.md @@ -36,8 +36,8 @@ Under "API Permissions" click Add a permission, then Microsoft Graph, then Deleg | Chat | Chat.ReadWrite | Y | *Read and write user chat messages* | Not for personal accounts/shared mailboxes | | ToDo | Tasks.Read | | *Read user's tasks and task lists* | Not for shared mailboxes | | ToDo | Tasks.ReadWrite | Y | *Create, read, update, and delete user’s tasks and task lists* | Not for shared mailboxes | - | Group Calendar | Group.Read.All | | *Read all groups* | Not supported in legacy installs or shared mailboxes | - | Group Calendar | Group.ReadWrite.All | Y | *Read and write all groups* | Not supported in legacy installs or shared mailboxes | + | Group Calendar | Group.Read.All | | *Read all groups* | Not supported in shared mailboxes | + | Group Calendar | Group.ReadWrite.All | Y | *Read and write all groups* | Not supported in shared mailboxes | | AutoReply | MailboxSettings.ReadWrite | | *Read and write user mailbox settings* | Not for shared mailboxes | **Note** It should be noted that these are the permissions that are requested at authentication time (as appropriate for each sensor configured). When `enable_update` is configured to `true` all the associated `ReadWrite` permissions are requested as well, however you do not need to add `ReadWrite` for any sensor type where you do not what update permissions, it will still act as a Read Only sensor. This excludes the AutoReply option which is only `ReadWrite`. diff --git a/docs/prerequisites.md b/docs/prerequisites.md index b38ec85..fab5dbe 100644 --- a/docs/prerequisites.md +++ b/docs/prerequisites.md @@ -22,8 +22,6 @@ To allow authentication, you first need to register your application at Azure Ap An alternate method of authentication is available which requires internet access to your HA instance if preferred. The alternate method is simpler to use when authenticating, but is more complex to set up correctly. See [Authentication](./authentication.md) section for more details. - _**NOTE:** As of version 3.2.0, the primary (default) and alternate authentication methods have essentially reversed. The primary (default) method now DOES NOT require direct access to your HA instance from the internet while the alternate method DOES require direct access. If you previously did NOT set 'alt_auth_flow' or had it set to False, please set 'alt_auth_method' to True and remove 'alt_auth_flow' from your config. This will only be necessary upon re-authentication._ - 4. From the Overview page, copy the Application (client) ID. 5. Under "Certificates & secrets", generate a new client secret. Set the expiration as desired. This appears to be limited to 2 years. Copy the **Value** of the client secret now (not the ID), it will be hidden later on. If you lose track of the secret, return here to generate a new one.