diff --git a/docs/docs/quickstart.md b/docs/docs/quickstart.md index 27922979f..239a097d4 100644 --- a/docs/docs/quickstart.md +++ b/docs/docs/quickstart.md @@ -26,8 +26,8 @@ Obtaining credentials from Microsoft 365 to allow Corso to run is a one-time ope ```bash - export AZURE_TENANT_ID= export AZURE_CLIENT_ID= + export AZURE_TENANT_ID= export AZURE_CLIENT_SECRET= ``` @@ -35,8 +35,8 @@ Obtaining credentials from Microsoft 365 to allow Corso to run is a one-time ope ```bash - export AZURE_TENANT_ID= export AZURE_CLIENT_ID= + export AZURE_TENANT_ID= export AZURE_CLIENT_SECRET= ``` diff --git a/docs/docs/setup/configuration.md b/docs/docs/setup/configuration.md index 12220411d..5092a92fd 100644 --- a/docs/docs/setup/configuration.md +++ b/docs/docs/setup/configuration.md @@ -23,8 +23,8 @@ alternate ways to pass AWS credentials. * Microsoft 365 Configuration * `AZURE_CLIENT_ID`: Client ID for your Azure AD application used to access your M365 tenant - * `AZURE_CLIENT_SECRET`: Azure secret for your Azure AD application used to access your M365 tenant * `AZURE_TENANT_ID`: ID for the M365 tenant where the Azure AD application is registered + * `AZURE_CLIENT_SECRET`: Azure secret for your Azure AD application used to access your M365 tenant * Corso Security Passphrase * `CORSO_PASSPHRASE`: Passphrase to protect encrypted repository contents @@ -51,8 +51,8 @@ To create the environment variables file, you can run the following command: mkdir -p $HOME/.corso cat < $HOME/.corso/corso.env CORSO_PASSPHRASE - AZURE_TENANT_ID AZURE_CLIENT_ID + AZURE_TENANT_ID AZURE_CLIENT_SECRET AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY diff --git a/docs/docs/setup/m365_access.md b/docs/docs/setup/m365_access.md index 98606a4ce..58b8b0a8a 100644 --- a/docs/docs/setup/m365_access.md +++ b/docs/docs/setup/m365_access.md @@ -8,49 +8,62 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; To perform backup and restore operations, Corso requires access to your [M365 tenant](concepts#m365-concepts) -through an [Azure AD application](concepts#m365-concepts) with appropriate permissions. +by creating an [Azure AD application](concepts#m365-concepts) with appropriate permissions. + +The following steps outline a simplified procedure for creating an Azure Ad application suitable for use with Corso. +For more details, please refer to the +[official documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal) +for adding an Azure AD Application and Service Principal using the Azure Portal. ## Create an Azure AD application -For the official documentation for adding an Azure AD Application and Service Principal using the Azure Portal see -[here](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal). +Sign in into the [Azure Portal](https://portal.azure.com/) with a user that has sufficient permissions to create an +AD application. -The following steps outline a simplified procedure for creating an Azure Ad application suitable for use with Corso. +### Register a new application -1. **Create a new application** +From the list of [Azure services](https://portal.azure.com/#allservices), select +**Azure Active Directory → App Registrations → New Registration** - Select **Azure Active Directory → App Registrations → New Registration** - +![Registering a new application](/img/m365app_create_new.png) -1. **Configure basic settings** +### Configure basic settings - * Give the application a name - * Select **Accounts in this organizational directory only** - * Skip the **Redirect URI** option +Next, configure the following: -
+* Give the application a name +* Select **Accounts in this organizational directory only** +* Skip the **Redirect URI** option +* Click **Register** at the bottom of the screen -1. **Configure required permissions** +![Configuring the application](/img/m365app_configure.png) - Select **API Permissions** from the app management panel. +### Configure required permissions - +Within the new application (`CorsoApp` in the below diagram), select **API Permissions → Add a permission** from +the management panel. - Select the following permissions from **Microsoft API → Microsoft Graph → Application Permissions**: +![Adding application permissions](/img/m365app_permissions.png) - - | API / Permissions Name | Type | Description - |:--|:--|:--| - | Calendars.ReadWrite | Application | Read and write calendars in all mailboxes | - | Contacts.ReadWrite | Application | Read and write contacts in all mailboxes | - | Files.ReadWrite.All | Application | Read and write files in all site collections | - | Mail.ReadWrite | Application | Read and write mail in all mailboxes | - | User.Read.All | Application | Read all users' full profiles | - +Select the following permissions from **Microsoft API → Microsoft Graph → Application Permissions** and +then click **Add permissions**. -1. **Grant admin consent** + +| API / Permissions Name | Type | Description +|:--|:--|:--| +| Calendars.ReadWrite | Application | Read and write calendars in all mailboxes | +| Contacts.ReadWrite | Application | Read and write contacts in all mailboxes | +| Files.ReadWrite.All | Application | Read and write files in all site collections | +| Mail.ReadWrite | Application | Read and write mail in all mailboxes | +| User.Read.All | Application | Read all users' full profiles | + - +### Grant admin consent + +Finally, grant admin consent to this application. This step is required even if the user that created the application +is an Microsoft 365 admin. + +![Granting administrator consent](/img/m365app_consent.png) ## Export application credentials @@ -59,8 +72,11 @@ as environment variables. ### Tenant ID and client ID -To extract the tenant and client ID, select Overview from the app management panel and export the corresponding -environment variables. +To view the tenant and client ID, select Overview from the app management panel. + +![Obtaining Tenant and Client IDs](/img/m365app_ids.png) + +Copy the client and tenant IDs and export them into the following environment variables. @@ -89,15 +105,17 @@ environment variables. - - ### Azure client secret -Lastly, you need to configure a client secret associated with the app using **Certificates & Secrets** from the app +Finally, you need to obtain a client secret associated with the app using **Certificates & Secrets** from the app management panel. -Click **New Client Secret** and follow the instructions to create a secret. After creating the secret, copy the secret -value right away because it won't be available later and export it as an environment variable. +Click **New Client Secret** under **Client secrets** and follow the instructions to create a secret. + +![Obtaining the Azure client secrete](/img/m365app_secret.png) + +After creating the secret, immediately copy the secret **Value** because it won't be available later. Export it as an +environment variable. @@ -122,5 +140,3 @@ value right away because it won't be available later and export it as an environ - - diff --git a/docs/src/css/custom.scss b/docs/src/css/custom.scss index 80a807cf6..761d022cc 100644 --- a/docs/src/css/custom.scss +++ b/docs/src/css/custom.scss @@ -45,10 +45,13 @@ html[data-theme='dark'] { .guideImages { max-width: 650px; width: 100%; - border: 1px solid #80808029 } .markdown { + img { + border: 1px solid #80808029; + } + code { border-color: transparent; vertical-align: initial; diff --git a/docs/static/img/m365app_configure.png b/docs/static/img/m365app_configure.png index 1e2998712..26a6e4f3c 100644 Binary files a/docs/static/img/m365app_configure.png and b/docs/static/img/m365app_configure.png differ diff --git a/docs/static/img/m365app_create_new.png b/docs/static/img/m365app_create_new.png index 805725a53..eca22f5d9 100644 Binary files a/docs/static/img/m365app_create_new.png and b/docs/static/img/m365app_create_new.png differ