# Connecting SharePoint (Online) to Amazon Q Business Microsoft SharePoint is a collaborative website building service that lets you customize web content and create web pages, web sites, document libraries, and lists. You can connect SharePoint (Online) instance to Amazon Q Business—using either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience. **Topics** + [Known limitations for the SharePoint (Online) connector](sharepoint-cloud-limitations.md) + [SharePoint (Online) connector overview](sharepoint-cloud-overview.md) + [Prerequisites for connecting Amazon Q Business to SharePoint (Online)](sharepoint-cloud-prereqs.md) + [Connecting Amazon Q Business to SharePoint (Online) using the console](sharepoint-cloud-console.md) + [Connecting Amazon Q Business to SharePoint (Online) using APIs](sharepoint-cloud-api.md) + [Connecting Amazon Q Business to SharePoint (Online) using AWS CloudFormation](sharepoint-cloud-cfn.md) + [How Amazon Q Business connector crawls SharePoint (Online) ACLs](sharepoint-cloud-user-management.md) + [SharePoint (Online) data source connector field mappings](sharepoint-cloud-field-mappings.md) + [IAM role for SharePoint (Online) connector](sharepoint-cloud-iam-role.md) + [Understand error codes in the SharePoint (Online) connector](sharepoint-cloud-error-codes.md) **Learn more** + For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html). + For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html). + For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html). + For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html). # Known limitations for the SharePoint (Online) connector The SharePoint (Online) connector has the following known limitations: + The Amazon Q SharePoint (Online) connector supports custom field mappings only for the [https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-field-mappings.html#sharepoint-field-mappings-files](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-field-mappings.html#sharepoint-field-mappings-files) entity. + If an entity name has a `%` character in its name, the connector will skip these files due to API limitations. + OneNote can only be crawled by the connector using a Tenant ID, and with OAuth 2.0, OAuth 2.0 refresh token, or SharePoint (Online) App Only authentication activated for SharePoint (Online) Online. + The connector crawls the first section of a OneNote document using its default name only, even if the document is renamed. + The connector crawls event attachments only when **Events** is also selected as an entity to be crawled. + The User Principal Name in your Azure Portal is a combination of upper case and lower case, the SharePoint (Online) API internally converts it to lower case. Because of this, the Amazon Q SharePoint (Online) connector sets ACL in lower case. For example, if **User principal name** is *MaryMajor@domain.com* in Azure portal, the ACL token in the SharePoint Connector will be *marymajor@domain.com*. + When Access Control Lists (ACLs) are enabled, the "Sync only new or modified content" option is not available due to SharePoint (Online) API limitations. We recommend using "Full sync" or "New, modified, or deleted content sync" modes instead, or disable ACLs if you need to use this sync mode. + If you want to crawl nested groups using **Identity crawler**, you have to activate Local as well as AD Group Crawling. + To use **Identity Crawler** with SharePoint (Online) to crawl nested groups, you have to enable both Local and AD Group Crawling. + Query responses based on AD Group ACLs are not supported for SharePoint (Online). You need to add users and groups directly to your document permissions list. + Microsoft requires granting the "Sites.FullControl.All" permission to the application in order to ingest the source ACLs from SharePoint # SharePoint (Online) connector overview The following table gives an overview of the Amazon Q Business SharePoint (Online) connector and its supported features. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-overview.html) # Prerequisites for connecting Amazon Q Business to SharePoint (Online) The following page outlines the prerequisites you need to complete before connecting SharePoint (Online) to Amazon Q, based on the authentication mode of your choice. **Note** For more information on connecting SharePoint (Online) to Amazon Q Business, see [Connect Amazon Q Business to Microsoft SharePoint Online using least privilege access controls](https://aws.amazon.com/blogs/machine-learning/connect-amazon-q-business-to-microsoft-sharepoint-online-using-least-privilege-access-controls/) and [Find answers accurately and quickly using Amazon Q Business with the SharePoint Online connector ](https://aws.amazon.com/blogs/machine-learning/find-answers-accurately-and-quickly-using-amazon-q-business-with-the-sharepoint-online-connector/) in the *AWS Machine Learning Blog*. **Topics** + [Prerequisites for using Microsoft Entra ID (formerly Azure AD) App-Only authentication](#sharepoint-cloud-prereqs-azure-app-only) + [Prerequisites for using OAuth 2.0 authentication](#sharepoint-cloud-prereqs-oauth) + [Prerequisites for using SharePoint App-Only authentication](#sharepoint-cloud-prereqs-sharepoint-app-only) + [Prerequisites for using basic authentication](#sharepoint-cloud-prereqs-basic) ## Prerequisites for using Microsoft Entra ID (formerly Azure AD) App-Only authentication **If you're using Microsoft Entra ID (formerly Azure AD) App-Only authentication, make sure you've completed the following steps in SharePoint (Online):** + Copied your SharePoint (Online) instance URLs. The format for the host URL you enter is *https://yourdomain.sharepoint.com/sites/mysite* or *https://yourcompany.sharepoint.com*. Your URL must start with `https` and contain `sharepoint.com`. + Copied the domain name of your SharePoint (Online) instance URL. + Copied the tenant ID of your Microsoft SharePoint (Online) instance. For details on how to find your tenant ID, see [Find your Microsoft 365 tenant ID](https://learn.microsoft.com/en-us/sharepoint/find-your-office-365-tenant-id) on the Microsoft website. + Generated an X.509 certificate. For more information on how to create and configure an X.509 certificate, see [Granting access via Microsoft Entra ID (formerly Azure AD) App-Only](https://learn.microsoft.com/en-us/sharepoint/dev/solution-guidance/security-apponly-azuread) and [New-PnPAzureCertificate](https://pnp.github.io/powershell/cmdlets/New-PnPAzureCertificate.html) in *Microsoft developer documentation*. + After generating the X.509 certificate, upload your .CRT file (the public certificate) to an Amazon S3 bucket. Note the file path to a X.509 certificate you have created and stored in an Amazon S3 bucket. (Ex. `s3://bucket-name/path/to/certificate.crt`). Ensure that your Amazon Q Business IAM role has permissions to read from this Amazon S3 bucket. + Noted the private key and the Client ID you generated after SharePoint (Online) Azure App registration. + Configured a Sharepoint (Online) Azure App using one of the two options below and noted its Client ID and Client secret. **Note** If you want to crawl specific sites, you can choose to restrict permissions to specific sites rather than all sites available in the domain. To do this, use the Sites.Selected (Application) permission. With this API permission, you need to set access permission on every site explicitly through the Microsoft Graph API. For more information, see [Microsoft's blog on Sites.Selected permissions](https://techcommunity.microsoft.com/t5/microsoft-sharepoint-blog/develop-applications-that-use-sites-selected-permissions-for-spo/ba-p/3790476). **In your AWS account, make sure you have:** + Created a Amazon Q Business application. + Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html). + Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role. + Stored your SharePoint (Online) authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret. **Note** If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console. For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html). *Microsoft Entra ID (formerly Azure AD) App-Only Option 1: Global Read Access* If you anticipate that you will be indexing several Sharepoint sites and would like to simplify your setup process, you can take the following steps to provide the Q Business Sharepoint connector global access. Otherwise, skip to section 2 below. 1. Create a Sharepoint client app to which we will assign the permissions needed by your Q Business connector. To register the app: 1. Log in to the Azure Portal with your Microsoft account. 1. 1. Provide the name for your application. In the example we are using the name TargetApp. The Amazon Q Business application uses TargetApp to connect to the SharePoint Online site to crawl and index the data. 1. Choose "Accounts" in the organizational directory. (Tenant name only - Single tenant). 1. Choose "Register". 1. Note down the application (client ID and the directory (tenant) on the Overview page, as you'll need them when prompted for "TargetApp-ClientId" and "TenantId". 1. Navigate to "Manage > API Permissions" in the navigation pane 1. Navigate to "Add a permission > Sharepoint > Application permissions" to allow the application to read data in your organization's directory regarding the signed-in user. 1. Search "AllSites.Read". 1. Choose "Add permissions". 1. Navigate to "Add a permission > Microsoft Graph > Application permissions" 1. Search and add the following permissions: + "Notes.Read.All" + "Sites.Read.All" + "Sites.FullControl.All (Application)" (required only if you intend to enable ACLs) + "Sites.Read.All (Application)"(required only if you intend to enable ACLs) + "Sites.FullControl.All" (required only if you intend to enable ACLs) + "GroupMember.Read.All" (required only if you intend to enable ACLs) + "User.Read.All" (required only if you intend to enable ACLs) 1. Navigate to "Remove permission" 1. Remove the original "User.Read - Delegated" permission 1. Choose "Grant admin consent" for the default directory 1. Save the client ID generated from this app for when you configure the Sharepoint connector in the Q Business console or API The following tables summarize all the permissions your application should have. + If you're not using ACL, your application should have the permission: **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-prereqs.html) **Note** Read.All and Sites.Read.All are required only if you want to crawl OneNote Documents. + If you're using ACL, your application should have the following permissions: **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-prereqs.html) 1. Create a client secret for your Sharepoint App: 1. Within your client App navigate to "Clients and secrets > Client secrets" 1. Click on create a new secret. 1. Generate a new Certificate to be shared between Q Business SharePoint Connector and Microsoft Entra ID (formerly Azure AD) App: 1. Use the example command below to generate your own x509 certificate. 1. Run the following command:`openssl req -x509 -newkey rsa:2048 -noenc -sha1 -keyout /tmp/private.key -out /tmp/sharepoint.crt -nodes -set_serial 1 -days 365 -subj "/CN=amazon/emailAddress=example@aws.com/C=US/ST=Texas/L=Dallas/O=amazon/OU=amazon` 1. Save the generated private key located in /tmp/private.key for later when you configure the Q Business Sharepoint connector via the Q Business console or API. *Microsoft Entra ID (formerly Azure AD) App-Only Option 2: Read Access for only Selected Sites* If you anticipate that you will be indexing a manageable number of Sharepoint sites and would prefer to limit the permissions of the Q Business connector to just the Sharepoint sites you intend to index, you can take the following steps: 1. Create a Sharepoint client app: Create a Sharepoint client app to which we will assign the permissions needed by your Q Business connector. To register the app: 1. Log in to the Azure Portal with your Microsoft account. 1. Choose "New Registration": 1. Provide the name for your application. In the example we are using the name TargetApp. The Amazon Q Business application uses TargetApp to connect to the SharePoint Online site to crawl and index the data. 1. Choose "Accounts" in the organizational directory. (Tenant name only - Single tenant). 1. Choose "Register". 1. Note down the application (client ID and the directory (tenant) on the Overview page, as you'll need them when prompted for "TargetApp-ClientId" and "TenantId". 1. Navigate to "Manage > API Permissions" in the navigation pane 1. Navigate to "Add a permission > Sharepoint > Application permissions" to allow the application to read data in your organization's directory regarding the signed-in user. 1. Search "Sites.Selected". 1. Choose "Add permissions". 1. Navigate to "Add a permission > Microsoft Graph > Application permissions" 1. Search and add the following permissions: + "Notes.Read.All" + "Sites.Selected" + "GroupMember.Read.All" (required only if you intend to enable ACLs) + "User.Read.All" (required only if you intend to enable ACLs) 1. Navigate to "Remove permission" 1. Remove the original "User.Read - Delegated" permission 1. Choose "Grant admin consent" for the default directory 1. Save the client ID generated from this app for when you configure the Sharepoint connector in the Q Business console or API The following tables summarize all the permissions your application should have. + If you're not using ACL, your application should have the permissions: **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-prereqs.html) **Note** Read.All and Sites.Read.All are required only if you want to crawl OneNote Documents. + If you're using ACL, your application should have the following permissions: **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-prereqs.html) 1. Create a client secret for your Sharepoint App: 1. Within your client App navigate to "Clients and secrets > Client secrets" 1. Click on create a new secret. 1. Generate a new Certificate to be shared between Q Business SharePoint Connector and Microsoft Entra ID (formerly Azure AD) App: 1. Run the following command: `openssl req -x509 -newkey rsa:2048 -noenc -sha1 -keyout /tmp/private.key -out /tmp/sharepoint.crt -nodes -set_serial 1 -days 365 -subj "/CN=amazon/emailAddress=example@aws.com/C=US/ST=Texas/L=Dallas/O=amazon/OU=amazon"` 1. Save the generated private key located in /tmp/private.key for later when you configure the Q Business Sharepoint connector via the Q Business console or API. 1. Upload the generated certificate located in /tmp/sharepoint.crt to an S3 bucket so you can use it later when you configure the Q Business Sharepoint connector via the Q Business console or API. You will also need this certificate for the next step. 1. Update your Sharepoint Client App’s Certificate: 1. Navigate to the Sharepoint client app you created in step 1. 1. Navigate to “Certificates and secrets > Certificates > Upload certificate” and upload the certificate (.crt file) you generated in step 4. 1. Create a Sharepoint admin app: This app will be used to provide the necessary site read permissions for the client OAuth App you created in the previous step. You can delete this admin app after you have completed all the steps. To register the app: 1. Log in to the Azure Portal with your Microsoft account. 1. Choose “New Registration”: 1. Provide the name for your application. 1. Choose "Accounts" in the organizational directory. (Tenant name only - Single tenant). 1. Choose "Register". 1. Locate your app ID, app secret, and tenant ID for your admin app and save them for the next step. 1. Navigate to "Manage > API Permissions" in the navigation pane 1. Navigate to "Add a permission > Sharepoint > Application permissions" to allow the application to read data in your organization's directory regarding the signed-in user. 1. Search "Sites.FullControl.All". 1. Choose "Add permissions". 1. Navigate to "Add a permission > Microsoft Graph > Application permissions" 1. Search "Sites.Read.All". 1. Choose "Add permissions". 1. Generate an access token for your Sharepoint admin app: Now use the following code snippet to generate an access token for your app, but replace adminAppID, adminAppSecret, and tenantID with the values you saved from step 2. 1. ``` adminAppId=$1 adminAppSecret=$2 tenantId=$3 tokenResponse=$(curl -s --location \ "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode "grant_type=client_credentials" \ --data-urlencode "client_id=$adminAppId" \ --data-urlencode "client_secret=$adminAppSecret" \ --data-urlencode "scope=offline_access https://graph.microsoft.com/.default") adminAppToken=$(echo $tokenResponse | jq -r '.access_token') echo $adminAppToken ``` 1. Obtain a Site ID for each of your Sharepoint sites: Repeat the following steps for each of the Sharepoint sites you want your Q Business connector to crawl: 1. Visit `https://{yourcompany}.sharepoint.com/sites/{SiteName}`in a browser. Enter the appropriate login credentials if needed. Validate that you are able to see your SharePoint site 1. Now append /\$1api/site/id at the end of \$1SiteName\$1. You should see a response something similar to below containing your site id (96a47524-4b21-446f-bf96-96d2f6fe4aa7) ``` 96a47524-4b21-446f-bf96-96d2f6fe4aa7 ``` 1. Grant your Sharepoint client app permissions to your selected sites: Now that you have created your Sharepoint admin app, Sharepoint client app, and have a list of site ids, you are ready to grant your client app the necessary permissions to access these sites. Repeat the following steps for each of the site ids you obtained from step 4. 1. Modify the code snippet below to provide the following: 1. clientAppId: The Application (client) ID from step 1. 1. clientAppName: The display name of your Sharepoint client app from step 1. 1. adminToken: The access token you generated in step 6. 1. siteId: One of the site ids you obtained from step 7. 1. Run the following command: ``` clientAppId=$1 clientAppName=$2 clientAppId=$1 clientAppName=$2 adminToken=$3 siteToGivePermissionTo=$4 grantPermissionResponse=$(curl -s --location "https://graph.microsoft.com/v1.0/sites/$siteToGivePermissionTo/permissions" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer $adminToken" \ --data '{ "roles": ["fullcontrol"], "grantedToIdentities": [{ "application": { "id": "'${clientAppId}'", "displayName": "'${clientAppName}'" } }] }') echo $grantPermissionResponse ``` 1. If the command was successful, you'll see a response as follows: ``` { "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites('awsplatodemo.sharepoint.com%2C96a47524-4b21-446f-bf96-96d2f6fe4aa7')/permissions/$entity", "id": "aTowaS50fG1zLnNwLmV4dHxjMDY5YjhlMi03NGFhLTQzZTQtODljYi1kNmZkMzU4ZmVjZThAZjIwNDQ2OTItZGMwOS00MjZlLWFlMGQtNGFlZDljMTI3ODA2", "roles": [ "fullcontrol" ], "grantedToIdentitiesV2": [ { "application": { "displayName": "demo-client-app", "id": "c069b8e2-74aa-43e4-89cb-d6fd358fece8" } } ], "grantedToIdentities": [ { "application": { "displayName": "demo-client-app", "id": "c069b8e2-74aa-43e4-89cb-d6fd358fece8" } } ] } ``` ## Prerequisites for using OAuth 2.0 authentication **If you're using OAuth 2.0 authentication, make sure you've completed the following steps in SharePoint (Online):** + Copied your SharePoint (Online) instance URLs. The format for the host URL you enter is *https://yourdomain.sharepoint.com/sites/mysite* or *https://yourcompany.sharepoint.com*. Your URL must start with `https` and contain `sharepoint.com`. + Copied the domain name of your SharePoint (Online) instance URL. + Copied the tenant ID of your Microsoft SharePoint (Online) instance. For details on how to find your tenant ID, see [Find your Microsoft 365 tenant ID](https://learn.microsoft.com/en-us/sharepoint/find-your-office-365-tenant-id) on the Microsoft website. + Noted the username and password that you use to connect to SharePoint (Online). + Noted the Client ID and Client secret generated after SharePoint (Online) Azure App registration. + Deactivate multi-factor authentication (MFA) in your SharePoint account, so that Amazon Q is not blocked from crawling your SharePoint content. + Configured a Sharepoint (Online) Azure App using one of the two options below and noted its Client ID and Client secret. *OAuth2.0 Option 1: Global Read Access* If you anticipate that you will be indexing several Sharepoint sites and would like to simplify your setup process, you can take the following steps to provide the Q Business Sharepoint connector global access. Otherwise, skip to section 2 below. To register the app: 1. Log in to the Azure Portal with your Microsoft account. 1. Choose "New Registration": 1. Provide the name for your application. In the example we are using the name TargetApp. The Amazon Q Business application uses TargetApp to connect to the SharePoint Online site to crawl and index the data. 1. Choose "Accounts" in the organizational directory. (Tenant name only - Single tenant). 1. Choose "Register". 1. Note down the application (client ID and the directory (tenant) on the Overview page, as you'll need them when prompted for "TargetApp-ClientId" and "TenantId". 1. Navigate to "Manage > API Permissions" in the navigation pane 1. Navigate to "Add a permission > Sharepoint > Application permissions" to allow the application to read data in your organization's directory regarding the signed-in user. 1. Search "AllSites.Read". 1. Choose "Add permissions". 1. Navigate to "Add a permission > Microsoft Graph > Application permissions" 1. Search and add the following permissions: + "Notes.Read.All" + "Sites.Read.All" + "Sites.FullControl.All" (required only if you intend to enable ACLs) + "GroupMember.Read.All" (required only if you intend to enable ACLs) + "User.Read.All" (required only if you intend to enable ACLs) 1. Navigate to "Remove permission". 1. Remove the original "User.Read - Delegated" permission. 1. Choose "Grant admin consent" for the default directory. 1. Save the client ID generated from this app for when you configure the Sharepoint connector in the Q Business console or API. The following tables summarize all the permissions your application should have. + If you're not using ACL, your application should have the permissions: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-prereqs.html) **Note** Note.Read.All and Sites.Read.All are required only if you want to crawl OneNote Documents. + If you're using ACL, your application should have the following permissions: **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-prereqs.html) **Note** GroupMember.Read.All and User.Read.All are required only if Identity crawler is activated. 1. Create a client secret for your Sharepoint App: 1. Within your client App navigate to "Clients and secrets > Client secrets" 1. Click on create a new secret. *OAuth2.0 Option 2: Read Access Only for Selected Sites* For organizations planning to index a manageable number of Sharepoint sites with limited permissions, the following steps provide the necessary setup: 1. Create a Sharepoint client app for OAuth: Now create a Sharepoint client OAuth app to which we will assign the permissions needed by your Q Business connector. To register the app: 1. Log in to the Azure Portal with your Microsoft account. 1. Choose "New Registration": 1. Provide the name for your application. In the example we are using the name TargetApp. The Amazon Q Business application uses TargetApp to connect to the SharePoint Online site to crawl and index the data. 1. Choose "Accounts" in the organizational directory. (Tenant name only - Single tenant). 1. Choose "Register". 1. Note down the application (client ID and the directory (tenant) on the Overview page, as you'll need them when prompted for "TargetApp-ClientId" and "TenantId". 1. Navigate to "Manage > API Permissions" in the navigation pane 1. Navigate to "Add a permission > Sharepoint > Application permissions" to allow the application to read data in your organization's directory regarding the signed-in user. 1. Search "Sites.Selected". 1. Choose "Add permissions". 1. Navigate to "Add a permission > Microsoft Graph > Application permissions" 1. Search and add the following permissions: + "Notes.Read.All" + "Sites.Selected" + "GroupMember.Read.All" (required only if you intend to enable ACLs) + "User.Read.All" (required only if you intend to enable ACLs) 1. Navigate to "Remove permission" 1. Remove the original "User.Read - Delegated" permission 1. Choose "Grant admin consent" for the default directory 1. Save the client ID generated from this app for when you configure the Sharepoint connector in the Q Business console or API The following tables summarize all the permissions your application should have. + If you're not using ACL, your application should have the permissions: **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-prereqs.html) **Note** Note.Read.All and Sites.Read.All are required only if you want to crawl OneNote Documents. + If you're using ACL, your application should have the following permissions: **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-prereqs.html) **Note** Note. GroupMember.Read.All and User.Read.All are required only if Identity crawler is activated. 1. Create a client secret for your Sharepoint App: 1. Within your client App navigate to "Clients and secrets > Client secrets" 1. Click on create a new secret. 1. Create a Sharepoint admin app: This app will be used to provide the necessary site read permissions for the client OAuth App you created in the previous step. You can delete this admin app after you have completed all the steps. To register the app: 1. Log in to the Azure Portal with your Microsoft account. 1. Choose "New Registration": 1. Provide the name for your application. 1. Choose "Accounts" in the organizational directory. (Tenant name only - Single tenant). 1. Choose "Register". 1. Locate your app ID, app secret, and tenant ID for your admin app and save them for the next step. 1. Navigate to "Manage > API Permissions" in the navigation pane 1. Navigate to "Add a permission > Sharepoint > Application permissions" to allow the application to read data in your organization's directory regarding the signed-in user. 1. Search "Sites.FullControl.All". 1. Choose "Add permissions". 1. Navigate to "Add a permission > Microsoft Graph > Application permissions" 1. Search "Sites.Read.All". 1. Choose "Add permissions". 1. Generate an access token for your Sharepoint admin app: Now use the following code snippet to generate an access token for your app, but replace adminAppID, adminAppSecret, and tenantID with the values you saved from step 2. 1. ``` adminAppId=$1 adminAppSecret=$2 tenantId=$3 tokenResponse=$(curl -s --location \ "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode "grant_type=client_credentials" \ --data-urlencode "client_id=$adminAppId" \ --data-urlencode "client_secret=$adminAppSecret" \ --data-urlencode "scope=offline_access https://graph.microsoft.com/.default") adminAppToken=$(echo $tokenResponse | jq -r '.access_token') echo $adminAppToken ``` 1. Obtain a Site ID for each of your Sharepoint sites: Repeat the following steps for each of the Sharepoint sites you want your Q Business connector to crawl: 1. Visit https://\$1yourcompany\$1.sharepoint.com/sites/\$1SiteName\$1 in a browser. Enter the appropriate login credentials if needed. Validate that you are able to see your SharePoint site 1. Now append /\$1api/site/id at the end of \$1SiteName\$1. You should see a response something similar to below containing your site id ([IP\$1ADDRESS]a7) ``` [IP_ADDRESS]a7 ``` 1. Grant your Sharepoint client app permissions to your selected sites: Now that you have created your Sharepoint admin app, Sharepoint client app, and have a list of site ids, you are ready to grant your client app the necessary permissions to access these sites. Repeat the following steps for each of the site ids you obtained from step 4. 1. Modify the code snippet below to provide the following: 1. clientAppId: The Application (client) ID from step 1 1. clientAppName: The display name of your Sharepoint client app from step 1 1. adminToken: The adminAppToken you generated in step 3 1. siteId: One of the site ids you obtained from step 4. 1. ``` clientAppId=$1 clientAppName=$2 adminToken=$3 siteToGivePermissionTo=$4 grantPermissionResponse=$(curl -s --location "https://graph.microsoft.com/v1.0/sites/$siteToGivePermissionTo/permissions" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer $adminToken" \ --data '{ "roles": ["fullcontrol"], "grantedToIdentities": [{ "application": { "id": "'${clientAppId}'", "displayName": "'${clientAppName}'" } }] }') echo $grantPermissionResponse ``` 1. If the command was successful, you'll see a response as follows: ``` { "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites('awsplatodemo.sharepoint.com%2C[IP_ADDRESS]a7')/permissions/$entity", "id": "aTowaS50fG1zLnNwLmV4dHxjMDY5YjhlMi03NGFhLTQzZTQtODljYi1kNmZkMzU4ZmVjZThAZjIwNDQ2OTItZGMwOS00MjZlLWFlMGQtNGFlZDljMTI3ODA2", "roles": [ "fullcontrol" ], "grantedToIdentitiesV2": [ { "application": { "displayName": "demo-client-app", "id": "c069b8e2-74aa-43e4-89cb-d6fd358fece8" } } ], "grantedToIdentities": [ { "application": { "displayName": "demo-client-app", "id": "c069b8e2-74aa-43e4-89cb-d6fd358fece8" } } ] } ``` ## Prerequisites for using SharePoint App-Only authentication **If you're using SharePoint App-Only authentication, make sure you've completed the following steps in SharePoint (Online):** + Copied your SharePoint (Online) instance URLs. The format for the host URL you enter is *https://yourdomain.sharepoint.com/sites/mysite* or *https://yourcompany.sharepoint.com*. Your URL must start with `https` and contain `sharepoint.com`. + Copied the domain name of your SharePoint (Online) instance URL. + Copied the tenant ID of your Microsoft SharePoint (Online) instance. For details on how to find your tenant ID, see [Find your Microsoft 365 tenant ID](https://learn.microsoft.com/en-us/sharepoint/find-your-office-365-tenant-id) on the Microsoft website. + Noted your SharePoint (Online) client ID and client secret generated while granting permission to SharePoint App-Only, and your Client ID and Client secret generated after SharePoint (Online) Azure App registration. + **If you're crawling OneNote documents and using **Identity crawler****, added the following permissions: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-prereqs.html) **Note** No API permissions are required for crawling entities using SharePoint (Online) **App-Only authentication**. **In your AWS account, make sure you have:** + Created a Amazon Q Business application. + Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html). + Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role. + Stored your SharePoint (Online) authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret. **Note** If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console. For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html). **Note** If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console. For a list of things to consider while configuring your data source, see [Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html). ## Prerequisites for using basic authentication **If you're using basic authentication, make sure you've completed the following steps in SharePoint (Online):** + Copied your SharePoint (Online) instance URLs. The format for the host URL you enter is *https://yourdomain.sharepoint.com/sites/mysite* or *https://yourcompany.sharepoint.com*. Your URL must start with `https` and contain `sharepoint.com`. + Copied the domain name of your SharePoint (Online) instance URL. + Noted your basic authentication credentials containing the username and password that you use to connect to SharePoint (Online) Online. + Deactivated **Security Defaults** in your Azure portal using an administrative user. For more information on managing security default settings in the Azure portal, see [Microsoft documentation on how to enable/disable security defaults](https://learn.microsoft.com/en-us/answers/questions/101179/how-to-disable-the-two-factor-authentication-from). + Deactivated multi-factor authentication (MFA) in your SharePoint account, so that Amazon Q is not blocked from crawling your SharePoint content. **Note** No API permissions are required for crawling entities using **Basic authentication**. **In your AWS account, make sure you have:** + Created a Amazon Q Business application. + Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html). + Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role. + Stored your SharePoint (Online) authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret. **Note** If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console. For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html). # Connecting Amazon Q Business to SharePoint (Online) using the console The following procedure outlines how to connect Amazon Q Business to SharePoint (Online) using the AWS Management Console. **Connecting Amazon Q to SharePoint (Online)** 1. Sign in to the AWS Management Console and open the Amazon Q Business console. 1. From the left navigation menu, choose **Data sources**. 1. From the **Data sources** page, choose **Add data source**. 1. Then, on the **Add data sources** page, from **Data sources**, add the **SharePoint** data source to your Amazon Q application. 1. Then, on the **SharePoint (Online)** data source page, enter the following information: 1. **Name and description**, do the following: + For **Data source name** – Name your data source for easy tracking. **Note** You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters. + **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later. 1. In **Source**, enter the following information: 1. In **Source**, for **Hosting Method** – Choose **SharePoint Online**. 1. **Site URLs specific to your SharePoint repository** – Enter the SharePoint host URLs. The format for the host URLs you enter is *https://yourcompany.sharepoint.com/sites/mysite* or *https://yourcompany.sharepoint.com*. The URL must start with `https` protocol. Separate URLs with a new line. You can add up to 100 URLs. 1. **Domain** – Enter the SharePoint domain. For example, the domain in the URL *https://yourdomain.sharepoint.com/sites/mysite* is *yourdomain*. Note that the domain name in the URL and the domain name you're expected to enter in the domain field can be different. 1. **Authorization** – Choose whether Amazon Q will crawl user and group access control list (ACL) information from your data source. Amazon Q can use this information to only generate responses from documents your end users have access to. You can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. **Note** Using ACL data to filter responses is not a replacement for user authentication and authorization for your application. For information on setting up identity management for Amazon Q, see [Integrating with an Identity Provider (IdP)](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/idp-integration.html). **Important** If you don't specify a value, **Email** is considered as the default value. 1. For **Authentication**, choose between **Basic**, **Oauth 2.0**, **Azure AD App-Only authentication**, and **SharePoint App-Only authentication** based on your use case. **Note** OneNote can only be crawled by the connector using a Tenant ID, and with OAuth 2.0, or SharePoint (Online) App Only authentication activated. 1. If using **Microsoft Entra ID (formerly Azure AD) App-Only authentication**, enter the following information: + **Tenant ID** – Tenant ID of your SharePoint account. To learn how to find your Tenant ID, see [Get subscription and tenant IDs in the Azure portal](https://learn.microsoft.com/en-us/azure/azure-portal/get-subscription-tenant-id) in Azure portal documentation. + **Microsoft Entra ID (formerly Azure AD) self-signed X.509 certificate** – Certificate to authenticate the connector for Microsoft Entra ID (formerly Azure AD). For more information on how to do this, see [Granting access via Microsoft Entra ID (formerly Azure AD) App-Only](https://learn.microsoft.com/en-us/sharepoint/dev/solution-guidance/security-apponly-azuread) and New-PnPAzureCertificate in *Microsoft developer documentation*. + **Generate a certificate using OpenSSL ** – As an example: ``` openssl req -x509 -newkey rsa:2048 -nodes -keyout /path/to/folder/private.key -out /path/to/folder/sharepoint.crt -days 365 -subj "/CN=ExampleCorp/emailAddress=example@domain.com /C=US/ST=Texas/L=Dallas/O=ExampleCorp/OU=IT" -set_serial 1 ``` **Note** Avoid using the -sha1 flag when generating certificates. SHA-1 is considered insecure and deprecated. Most modern browsers and systems reject certificates signed with SHA-1. By default, OpenSSL uses a secure algorithm such as SHA-256 when the -sha1 flag is omitted. + For **AWS Secrets Manager secret** – Choose an existing secret or create a Secrets Manager secret to store your SharePoint authentication credentials. If you choose to create a secret, an AWS Secrets Manager secret window opens. Enter the following information in the window: + **Secret name** – A name for your secret. + **Client ID** – The Client ID generated when you complete Azure App registration for SharePoint (Online) in Entra ID. + **Private key** – A private key to authenticate the connector for Microsoft Entra ID (formerly Azure AD). + **Register a new app in the Microsoft Azure portal**: 1. Log in to the Azure Portal with your Microsoft account. 1. Choose New Registration: 1. Provide the name for your application. In the example we are using the name `TargetApp`. The Amazon Q Business application uses TargetApp to connect to the SharePoint Online site to crawl and index the data. 1. Choose "Accounts" in the organizational directory. (`Tenant name` only - Single tenant). 1. Choose "Register". 1. Note down the application (client ID and the directory (tenant) on the Overview page, as you'll need them when prompted for "TargetApp-ClientId" and "TenantId". 1. Choose API permissions under "Manage" in the navigation pane. 1. Choose "Add a permission" to allow the application to read data in your organization's directory regarding the signed-in user. 1. Choose "Sharepoint". 1. Choose "Application permissions". 1. Choose "Sites.FullControl.All" from the User section. 1. Choose "Add permissions". 1. On the options menu, choose to "Remove" a permssion. 1. Remove the original `User.Read - Delegated` permission. 1. Choose "Grant admin content" for the Default Directory. 1. If using **SharePoint App-Only authentication**, enter the following information: + **Tenant ID**–Tenant ID of your SharePoint account. To learn how to find your Tenant ID, see [Get subscription and tenant IDs in the Azure portal](https://learn.microsoft.com/en-us/azure/azure-portal/get-subscription-tenant-id) in Azure portal documentation. + For **AWS Secrets Manager secret** — Choose an existing secret or create a Secrets Manager secret to store your SharePoint authentication credentials. If you choose to create a secret, an AWS Secrets Manager secret window opens. Enter the following information in the window: + **Secret name** – A name for your secret. + **SharePoint client ID** – The SharePoint client ID you generated when you registered App-Only at Tenant Level. ClientID format is *ClientID@TenantId*. For example, *ffa956f3-8f89-44e7-b0e4-49670756342c@888d0b57-69f1-4fb8-957f-e1f0bedf82fe.* + **SharePoint client secret** – The SharePoint client secret generated when your register for App-Only at Tenant Level. + **Client ID** – The Microsoft Entra ID (formerly Azure AD) client ID generated when you register SharePoint in Microsoft Entra ID (formerly Azure AD). + **Client secret** – The Microsoft Entra ID (formerly Azure AD) client secret generated when you register SharePoint to Microsoft Entra ID (formerly Azure AD). 1. If using **OAuth 2.0 authentication**, you must disable MFA in SharePoint. This is not recommended, but if you choose to use OAuth 2.0 authentication anyway, enter the following information: + **Tenant ID** – Tenant ID of your SharePoint account. To learn how to find your Tenant ID, see [Get subscription and tenant IDs in the Azure portal](https://learn.microsoft.com/en-us/azure/azure-portal/get-subscription-tenant-id) in Azure portal documentation. + For **AWS Secrets Manager secret** – Choose an existing secret or create a Secrets Manager secret to store your SharePoint authentication credentials. If you choose to create a secret, an AWS Secrets Manager secret window opens. Enter the following information in the window: + **Secret name** – A name for your secret. + **Username** – Username for your SharePoint account. + **Password** – Password for your SharePoint account. + **Client ID** – The Client ID generated when you complete Azure App registration for SharePoint (Online) in Entra ID. + **Client secret** – The Client secret generated when you complete Azure App registration for SharePoint (Online) in Entra ID. 1. If using **Basic Authentication**, you must disable MFA in SharePoint. This is not recommended, but if you choose to use Basic Auth anyway, enter the following information: + For **AWS Secrets Manager secret** – Choose an existing secret or create a Secrets Manager secret to store your SharePoint authentication credentials. If you choose to create a secret, an AWS Secrets Manager secret window opens. Enter the following information in the window: + **Secret name** – A name for your secret. + **Username** – Username for your SharePoint account. + **Password** – Password for your SharePoint account. 1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information: 1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC. 1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required. For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc). The SharePoint connector supports Microsoft Entra ID (formerly Azure AD) groups associated with documents. In order for Microsoft Entra ID (formerly Azure AD) group members to search the data, you have to integrate Microsoft Entra ID (formerly Azure AD) with IAM Identity Center. 1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content. **Note** Creating a new service IAM role is recommended. For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-connector.html#sharepoint-cloud-iam). 1. In **Sync scope**, choose from the following options : 1. **Select entities** – Choose the entities that you want to crawl. You can select to crawl **All** entities or any combination of **Files**, **Attachments**, **Links**, **Pages**, **Events**, **Comments**, and **List Data**. 1. For **Maximum file size** – Specify the file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. 1. In **Additional configuration – *optional***, for **Entity regex patterns** – Add regular expression patterns for **Links**, **Pages**, and **Events** to include specific entities instead of syncing all your documents. 1. In **Additional configuration**, for **Regex patterns** – Add regular expression patterns to include or exclude files by **File path**, **File name**, **File type**, **OneNote section name**, and **OneNote page name** instead of syncing all your documents. You can add up to 100 patterns. **Note** Any valid regex pattern is supported. For example, if you use the regex `^QBusiness*`, any content starting with the word `QBusiness` followed by any number of characters will be filtered (`QBusiness_doc1` or `QBusiness`, but not `doc1_QBusiness`). **Note** OneNote crawling is available only for OAuth 2.0 and SharePoint App Only authentication. 1. **Multi-media content configuration – optional** – To enable content extraction from embedded images and visuals in documents, choose **Visual content in documents**. To extract audio transcriptions and video content, enable processing for the following file types: 1. **Advanced settings** **Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard). 1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default. + **Full sync** – Sync all content regardless of the previous sync status. + **New or modified content sync** – Sync only new and modified documents. + **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents. For more details, see [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode). 1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs). 1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details. 1. **Field mappings** – A list of data source document attributes to map to your index fields. **Note** Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields: 1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these. 1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields. **Note** Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields. For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings). 1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use. **Note** View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately. You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process. For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed). # Connecting Amazon Q Business to SharePoint (Online) using APIs You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration. Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema. For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference. **Topics** + [SharePoint (Online) configuration properties](#sharepoint-cloud-configuration-keys) + [SharePoint (Online) JSON schema](#sharepoint-cloud-json) + [SharePoint (Online) JSON schema example](#sharepoint-cloud-api-json-example) ## SharePoint (Online) configuration properties The following provides information about important configuration properties required in the schema. | Configuration | Description | Type | Required | | --- | --- | --- | --- | | `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has a sub-property called `repositoryEndpointMetadata`. | Yes | | `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-api.html) | Yes | | `tenantId` | The tenant id of your SharePoint (Online) account. | `string` OAuth2 series required | Yes | | `domain` | The domain of your SharePoint (Online) account. | `string` | Yes | | `siteUrls` | The host URLs of your SharePoint (Online) account. | `array (string)` Specify the URL in the pattern `https://*` | Yes | | `repositoryAdditionalProperties` | Additional properties to connect with your repository endpoint. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-api.html) | Yes | | `s3bucketName` | The name of the Amazon S3 bucket that stores your Azure AD self-signed X.509 certificate. | `string` Azure AD App-Only auth required | No | | `s3certificateName` | The name of the SSL certificate stored in your Amazon S3 bucket. | `string` Azure AD App-Only auth required | No | | `authType` | The type of authentication you are using: OAuth2, OAuth2Certificate, OAuth2App, or Basic. | `string` | Yes | | `version` | The SharePoint version you are using: Online. | `string (Online)` Azure AD App-Only auth required | Yes | | `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-api.html) | Yes | | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-api.html) | A list of objects that map the attributes or field names of your SharePoint (Online) pages and assets to Amazon Q index field names. | `object` These properties have the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-api.html) | No | | `indexFieldName` | The field name of your SharePoint (Online) events, pages, files, links, attachments, or comments. | `string` | Yes | | `indexFieldType` | The field type of your SharePoint (Online) events, pages, files, links, attachments, or comments. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes | | `dataSourceFieldName` | The data source field name of your SharePoint (Online) events, pages, files, links, attachments, or comments. | `string` | Yes | | `dateFieldFormat` | The date format of your SharePoint (Online) events, pages, files, links, attachments, or comments. | `string` Specify the date format in the form `yyyy-MM-dd'T'HH:mm:ss'Z'` | No | | `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-api.html) | Yes | | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-api.html) | A list of regular expression patterns to include/exclude specific files in your SharePoint (Online) data source. Files that match the patterns are included in the index. File that don't match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the file isn't included in the index. | `array (string)` | No | | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-api.html) | Input TRUE to index. | `boolean` | No | | `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` | No | | `type` | We recommend that you use SHAREPOINTV2 as your data source type | `string` Valid values are `SHAREPOINTV2` and `SHAREPOINT`. | Yes | | `enableIdentityCrawler` | `true` to activate identity crawler. Identity crawler is activated by default. Crawling identity information on users and groups with access to specific documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). | `boolean` | Yes | | `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-api.html) | Yes | | `secretARN` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your SharePoint. If you use basic authentication, provide the username and password. If you use OAuth 2.0 authentication, provide the username, password, client ID, and client secret. | `string` The minimum length is 20 and the maximum length is 2,048 characters. If you use basic authentication (authType should be Basic), the secret must contain a JSON structure with the following keys: 
{
    "username": "SharePoint (Online) account user name",
    "password": "SharePoint (Online) password"
}
If you use Azure AD App-only authentication (authType should be OAuth2Certificate), the secret must contain a JSON structure with the following keys: 
{
    "clientId": "SharePoint (Online) client ID",
    "privateKey": "SharePoint (Online) private key"
}
If you use OAuth2 authentication (authType should be OAuth) or Sharepoint App-Only authentication (authType should be OAuth2App) the secret must contain a JSON structure with the following keys: 
{
  "clientId": "SharePoint (Online) client ID",
  "clientSecret": "SharePoint (Online) client secret",
  "userName": "SharePoint (Online) account user name",
  "password": "SharePoint (Online) password"
}
| Yes | | `version` | The version of this template that's currently supported. | `string` | No | ## SharePoint (Online) JSON schema The following is the SharePoint (Online) JSON schema: ``` { "type": "object", "properties": { "type": { "type": "string", "enum": ["SHAREPOINTV2", "SHAREPOINT"] }, "syncMode": { "type": "string", "enum": ["FULL_CRAWL", "FORCED_FULL_CRAWL", "CHANGE_LOG"] }, "secretArn": { "type": "string", "minLength": 20, "maxLength": 2048 }, "enableIdentityCrawler": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "connectionConfiguration": { "type": "object", "properties": { "repositoryEndpointMetadata": { "type": "object", "properties": { "tenantId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "minLength": 36, "maxLength": 36 }, "domain": { "type": "string" }, "siteUrls": { "type": "array", "items": { "type": "string", "pattern": "https://.*" } }, "repositoryAdditionalProperties": { "type": "object", "properties": { "s3bucketName": { "type": "string" }, "s3certificateName": { "type": "string" }, "authType": { "type": "string", "enum": [ "OAuth2", "OAuth2Certificate", "OAuth2App", "Basic" ] }, "version": { "type": "string", "enum": ["Online"] }, "enableDeletionProtection": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ], "default": false }, "deletionProtectionThreshold": { "type": "string", "default": "15" } }, "required": ["authType", "version"] } }, "required": ["siteUrls", "domain", "repositoryAdditionalProperties"] } }, "required": ["repositoryEndpointMetadata"] }, "repositoryConfigurations": { "type": "object", "properties": { "event": { "type": "object", "properties": { "fieldMappings": { "type": "array", "items": [ { "type": "object", "properties": { "indexFieldName": { "type": "string" }, "indexFieldType": { "type": "string", "enum": ["STRING", "STRING_LIST", "DATE"] }, "dataSourceFieldName": { "type": "string" }, "dateFieldFormat": { "type": "string", "pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'" } }, "required": [ "indexFieldName", "indexFieldType", "dataSourceFieldName" ] } ] } }, "required": ["fieldMappings"] }, "page": { "type": "object", "properties": { "fieldMappings": { "type": "array", "items": [ { "type": "object", "properties": { "indexFieldName": { "type": "string" }, "indexFieldType": { "type": "string", "enum": ["STRING", "DATE", "LONG"] }, "dataSourceFieldName": { "type": "string" }, "dateFieldFormat": { "type": "string", "pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'" } }, "required": [ "indexFieldName", "indexFieldType", "dataSourceFieldName" ] } ] } }, "required": ["fieldMappings"] }, "file": { "type": "object", "properties": { "fieldMappings": { "type": "array", "items": [ { "type": "object", "properties": { "indexFieldName": { "type": "string" }, "indexFieldType": { "type": "string", "enum": ["STRING", "DATE", "LONG"] }, "dataSourceFieldName": { "type": "string" }, "dateFieldFormat": { "type": "string", "pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'" } }, "required": [ "indexFieldName", "indexFieldType", "dataSourceFieldName" ] } ] } }, "required": ["fieldMappings"] }, "link": { "type": "object", "properties": { "fieldMappings": { "type": "array", "items": [ { "type": "object", "properties": { "indexFieldName": { "type": "string" }, "indexFieldType": { "type": "string", "enum": ["STRING", "STRING_LIST", "DATE"] }, "dataSourceFieldName": { "type": "string" }, "dateFieldFormat": { "type": "string", "pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'" } }, "required": [ "indexFieldName", "indexFieldType", "dataSourceFieldName" ] } ] } }, "required": ["fieldMappings"] }, "attachment": { "type": "object", "properties": { "fieldMappings": { "type": "array", "items": [ { "type": "object", "properties": { "indexFieldName": { "type": "string" }, "indexFieldType": { "type": "string", "enum": ["STRING", "STRING_LIST", "DATE"] }, "dataSourceFieldName": { "type": "string" }, "dateFieldFormat": { "type": "string", "pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'" } }, "required": [ "indexFieldName", "indexFieldType", "dataSourceFieldName" ] } ] } }, "required": ["fieldMappings"] }, "comment": { "type": "object", "properties": { "fieldMappings": { "type": "array", "items": [ { "type": "object", "properties": { "indexFieldName": { "type": "string" }, "indexFieldType": { "type": "string", "enum": ["STRING", "STRING_LIST", "DATE"] }, "dataSourceFieldName": { "type": "string" }, "dateFieldFormat": { "type": "string", "pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'" } }, "required": [ "indexFieldName", "indexFieldType", "dataSourceFieldName" ] } ] } }, "required": ["fieldMappings"] } } }, "additionalProperties": { "type": "object", "properties": { "eventTitleFilterRegEx": { "type": "array", "items": { "type": "string" } }, "pageTitleFilterRegEx": { "type": "array", "items": { "type": "string" } }, "linkTitleFilterRegEx": { "type": "array", "items": { "type": "string" } }, "inclusionFilePath": { "type": "array", "items": { "type": "string" } }, "exclusionFilePath": { "type": "array", "items": { "type": "string" } }, "inclusionFileTypePatterns": { "type": "array", "items": { "type": "string" } }, "exclusionFileTypePatterns": { "type": "array", "items": { "type": "string" } }, "inclusionFileNamePatterns": { "type": "array", "items": { "type": "string" } }, "exclusionFileNamePatterns": { "type": "array", "items": { "type": "string" } }, "inclusionOneNoteSectionNamePatterns": { "type": "array", "items": { "type": "string" } }, "exclusionOneNoteSectionNamePatterns": { "type": "array", "items": { "type": "string" } }, "inclusionOneNotePageNamePatterns": { "type": "array", "items": { "type": "string" } }, "exclusionOneNotePageNamePatterns": { "type": "array", "items": { "type": "string" } }, "crawlFiles": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "crawlPages": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "crawlEvents": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "crawlComments": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "crawlLinks": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "crawlAttachments": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "crawlListData": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "crawlAcl": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "isCrawlLocalGroupMapping": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "isCrawlAdGroupMapping": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "maxFileSizeInMegaBytes": { "type": "string" } }, "required": [] }, "version": { "type": "string", "anyOf": [ { "pattern": "1.0.0" } ] } }, "required": [ "type", "syncMode", "secretArn", "enableIdentityCrawler", "connectionConfiguration", "repositoryConfigurations", "additionalProperties" ] } ``` ## SharePoint (Online) JSON schema example The following is the SharePoint (Online) JSON schema example: ``` { "type": "SHAREPOINTV2", "syncMode": "FULL_CRAWL", "secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-sharepoint-secret", "enableIdentityCrawler": "true", "connectionConfiguration": { "repositoryEndpointMetadata": { "tenantId": "1234567a-890b-1234-567c-123456789012", "domain": "example.sharepoint.com", "siteUrls": ["https://example.sharepoint.com/sites/mysite"], "repositoryAdditionalProperties": { "s3bucketName": "my-bucket", "s3certificateName": "my-certificate", "authType": "OAuth2", "version": "Online", "enableDeletionProtection": "false", "deletionProtectionThreshold": "15" } } }, "repositoryConfigurations": { "event": { "fieldMappings": [ { "indexFieldName": "event_id", "indexFieldType": "STRING", "dataSourceFieldName": "id", "dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'" } ] }, "page": { "fieldMappings": [ { "indexFieldName": "page_id", "indexFieldType": "STRING", "dataSourceFieldName": "id", "dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'" } ] } }, "additionalProperties": { "eventTitleFilterRegEx": ["^.*$"], "pageTitleFilterRegEx": ["^.*$"], "linkTitleFilterRegEx": ["^.*$"], "inclusionFilePath": ["documents/"], "exclusionFilePath": ["drafts/"], "inclusionFileTypePatterns": ["*.docx"], "exclusionFileTypePatterns": ["*.tmp"], "inclusionFileNamePatterns": ["*report*"], "exclusionFileNamePatterns": ["*draft*"], "enableDeletionProtection": "false", "maxFileSizeInMegaBytes": "50" } } ``` # Connecting Amazon Q Business to SharePoint (Online) using AWS CloudFormation You use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html) resource to connect a data source to your Amazon Q application. Use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid) property to provide a JSON or YAML schema with the necessary configuration details specific to your data source connector. To learn more about AWS CloudFormation, see [What is AWS CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) in the *CloudFormation User Guide*. **Topics** + [SharePoint (Online) configuration properties](#sharepoint-cloud-configuration-keys) + [SharePoint (Online) JSON schema for using the configuration property with AWS CloudFormation](#sharepoint-cloud-cfn-json) + [SharePoint (Online) YAML schema for using the configuration property with AWS CloudFormation](#sharepoint-cloud-cfn-yaml) ## SharePoint (Online) configuration properties The following provides information about important configuration properties required in the schema. | Configuration | Description | Type | Required | | --- | --- | --- | --- | | `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has a sub-property called `repositoryEndpointMetadata`. | Yes | | `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-cfn.html) | Yes | | `tenantId` | The tenant id of your SharePoint (Online) account. | `string` OAuth2 series required | Yes | | `domain` | The domain of your SharePoint (Online) account. | `string` | Yes | | `siteUrls` | The host URLs of your SharePoint (Online) account. | `array (string)` Specify the URL in the pattern `https://*` | Yes | | `repositoryAdditionalProperties` | Additional properties to connect with your repository endpoint. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-cfn.html) | Yes | | `s3bucketName` | The name of the Amazon S3 bucket that stores your Azure AD self-signed X.509 certificate. | `string` Azure AD App-Only auth required | No | | `s3certificateName` | The name of the SSL certificate stored in your Amazon S3 bucket. | `string` Azure AD App-Only auth required | No | | `authType` | The type of authentication you are using: OAuth2, OAuth2Certificate, OAuth2App, or Basic. | `string` | Yes | | `version` | The SharePoint version you are using: Online. | `string (Online)` Azure AD App-Only auth required | Yes | | `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-cfn.html) | Yes | | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-cfn.html) | A list of objects that map the attributes or field names of your SharePoint (Online) pages and assets to Amazon Q index field names. | `object` These properties have the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-cfn.html) | No | | `indexFieldName` | The field name of your SharePoint (Online) events, pages, files, links, attachments, or comments. | `string` | Yes | | `indexFieldType` | The field type of your SharePoint (Online) events, pages, files, links, attachments, or comments. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes | | `dataSourceFieldName` | The data source field name of your SharePoint (Online) events, pages, files, links, attachments, or comments. | `string` | Yes | | `dateFieldFormat` | The date format of your SharePoint (Online) events, pages, files, links, attachments, or comments. | `string` Specify the date format in the form `yyyy-MM-dd'T'HH:mm:ss'Z'` | No | | `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-cfn.html) | Yes | | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-cfn.html) | A list of regular expression patterns to include/exclude specific files in your SharePoint (Online) data source. Files that match the patterns are included in the index. File that don't match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the file isn't included in the index. | `array (string)` | No | | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-cfn.html) | Input TRUE to index. | `boolean` | No | | `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` | No | | `type` | We recommend that you use SHAREPOINTV2 as your data source type | `string` Valid values are `SHAREPOINTV2` and `SHAREPOINT`. | Yes | | `enableIdentityCrawler` | `true` to activate identity crawler. Identity crawler is activated by default. Crawling identity information on users and groups with access to specific documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). | `boolean` | Yes | | `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-cfn.html) | Yes | | `secretARN` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your SharePoint. If you use basic authentication, provide the username and password. If you use OAuth 2.0 authentication, provide the username, password, client ID, and client secret. | `string` The minimum length is 20 and the maximum length is 2,048 characters. If you use basic authentication (authType should be Basic), the secret must contain a JSON structure with the following keys: 
{
    "username": "SharePoint (Online) account user name",
    "password": "SharePoint (Online) password"
}
If you use Azure AD App-only authentication (authType should be OAuth2Certificate), the secret must contain a JSON structure with the following keys: 
{
    "clientId": "SharePoint (Online) client ID",
    "privateKey": "SharePoint (Online) private key"
}
If you use OAuth2 authentication (authType should be OAuth) or Sharepoint App-Only authentication (authType should be OAuth2App) the secret must contain a JSON structure with the following keys: 
{
  "clientId": "SharePoint (Online) client ID",
  "clientSecret": "SharePoint (Online) client secret",
  "userName": "SharePoint (Online) account user name",
  "password": "SharePoint (Online) password"
}
| Yes | | `version` | The version of this template that's currently supported. | `string` | No | ## SharePoint (Online) JSON schema for using the configuration property with AWS CloudFormation The following is the SharePoint (Online) JSON schema and examples for the configuration property for AWS CloudFormation. **Topics** + [SharePoint (Online) JSON schema for using the configuration property with AWS CloudFormation](#sharepoint-cloud-cfn-json-schema) + [SharePoint (Online) JSON schema example for using the configuration property with AWS CloudFormation](#sharepoint-cloud-cfn-json-example) ### SharePoint (Online) JSON schema for using the configuration property with AWS CloudFormation The following is the SharePoint (Online) JSON schema for the configuration property for CloudFormation ``` { "type": "object", "properties": { "type": { "type": "string", "enum": ["SHAREPOINTV2", "SHAREPOINT"] }, "syncMode": { "type": "string", "enum": ["FULL_CRAWL", "FORCED_FULL_CRAWL", "CHANGE_LOG"] }, "secretArn": { "type": "string", "minLength": 20, "maxLength": 2048 }, "enableIdentityCrawler": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "connectionConfiguration": { "type": "object", "properties": { "repositoryEndpointMetadata": { "type": "object", "properties": { "tenantId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "minLength": 36, "maxLength": 36 }, "domain": { "type": "string" }, "siteUrls": { "type": "array", "items": { "type": "string", "pattern": "https://.*" } }, "repositoryAdditionalProperties": { "type": "object", "properties": { "s3bucketName": { "type": "string" }, "s3certificateName": { "type": "string" }, "authType": { "type": "string", "enum": [ "OAuth2", "OAuth2Certificate", "OAuth2App", "OAuth2_RefreshToken", "Basic" ] }, "version": { "type": "string", "enum": ["Online"] }, "enableDeletionProtection": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ], "default": false }, "deletionProtectionThreshold": { "type": "string", "default": "15" } }, "required": ["authType", "version"] } }, "required": ["siteUrls", "domain", "repositoryAdditionalProperties"] } }, "required": ["repositoryEndpointMetadata"] }, "repositoryConfigurations": { "type": "object", "properties": { "event": { "type": "object", "properties": { "fieldMappings": { "type": "array", "items": [ { "type": "object", "properties": { "indexFieldName": { "type": "string" }, "indexFieldType": { "type": "string", "enum": ["STRING", "STRING_LIST", "DATE"] }, "dataSourceFieldName": { "type": "string" }, "dateFieldFormat": { "type": "string", "pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'" } }, "required": [ "indexFieldName", "indexFieldType", "dataSourceFieldName" ] } ] } }, "required": ["fieldMappings"] }, "page": { "type": "object", "properties": { "fieldMappings": { "type": "array", "items": [ { "type": "object", "properties": { "indexFieldName": { "type": "string" }, "indexFieldType": { "type": "string", "enum": ["STRING", "DATE", "LONG"] }, "dataSourceFieldName": { "type": "string" }, "dateFieldFormat": { "type": "string", "pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'" } }, "required": [ "indexFieldName", "indexFieldType", "dataSourceFieldName" ] } ] } }, "required": ["fieldMappings"] }, "file": { "type": "object", "properties": { "fieldMappings": { "type": "array", "items": [ { "type": "object", "properties": { "indexFieldName": { "type": "string" }, "indexFieldType": { "type": "string", "enum": ["STRING", "DATE", "LONG"] }, "dataSourceFieldName": { "type": "string" }, "dateFieldFormat": { "type": "string", "pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'" } }, "required": [ "indexFieldName", "indexFieldType", "dataSourceFieldName" ] } ] } }, "required": ["fieldMappings"] }, "link": { "type": "object", "properties": { "fieldMappings": { "type": "array", "items": [ { "type": "object", "properties": { "indexFieldName": { "type": "string" }, "indexFieldType": { "type": "string", "enum": ["STRING", "STRING_LIST", "DATE"] }, "dataSourceFieldName": { "type": "string" }, "dateFieldFormat": { "type": "string", "pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'" } }, "required": [ "indexFieldName", "indexFieldType", "dataSourceFieldName" ] } ] } }, "required": ["fieldMappings"] }, "attachment": { "type": "object", "properties": { "fieldMappings": { "type": "array", "items": [ { "type": "object", "properties": { "indexFieldName": { "type": "string" }, "indexFieldType": { "type": "string", "enum": ["STRING", "STRING_LIST", "DATE"] }, "dataSourceFieldName": { "type": "string" }, "dateFieldFormat": { "type": "string", "pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'" } }, "required": [ "indexFieldName", "indexFieldType", "dataSourceFieldName" ] } ] } }, "required": ["fieldMappings"] }, "comment": { "type": "object", "properties": { "fieldMappings": { "type": "array", "items": [ { "type": "object", "properties": { "indexFieldName": { "type": "string" }, "indexFieldType": { "type": "string", "enum": ["STRING", "STRING_LIST", "DATE"] }, "dataSourceFieldName": { "type": "string" }, "dateFieldFormat": { "type": "string", "pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'" } }, "required": [ "indexFieldName", "indexFieldType", "dataSourceFieldName" ] } ] } }, "required": ["fieldMappings"] } } }, "additionalProperties": { "type": "object", "properties": { "eventTitleFilterRegEx": { "type": "array", "items": { "type": "string" } }, "pageTitleFilterRegEx": { "type": "array", "items": { "type": "string" } }, "linkTitleFilterRegEx": { "type": "array", "items": { "type": "string" } }, "inclusionFilePath": { "type": "array", "items": { "type": "string" } }, "exclusionFilePath": { "type": "array", "items": { "type": "string" } }, "inclusionFileTypePatterns": { "type": "array", "items": { "type": "string" } }, "exclusionFileTypePatterns": { "type": "array", "items": { "type": "string" } }, "inclusionFileNamePatterns": { "type": "array", "items": { "type": "string" } }, "exclusionFileNamePatterns": { "type": "array", "items": { "type": "string" } }, "inclusionOneNoteSectionNamePatterns": { "type": "array", "items": { "type": "string" } }, "exclusionOneNoteSectionNamePatterns": { "type": "array", "items": { "type": "string" } }, "inclusionOneNotePageNamePatterns": { "type": "array", "items": { "type": "string" } }, "exclusionOneNotePageNamePatterns": { "type": "array", "items": { "type": "string" } }, "crawlFiles": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "crawlPages": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "crawlEvents": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "crawlComments": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "crawlLinks": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "crawlAttachments": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "crawlListData": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "crawlAcl": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "aclConfiguration": { "type": "string", "enum": [ "ACLWithLDAPEmailFmt", "ACLWithManualEmailFmt", "ACLWithUsernameFmt" ] }, "emailDomain": { "type": "string" }, "isCrawlLocalGroupMapping": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "isCrawlAdGroupMapping": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "maxFileSizeInMegaBytes": { "type": "string" } }, "required": [] }, "version": { "type": "string", "anyOf": [ { "pattern": "1.0.0" } ] } }, "required": [ "type", "syncMode", "secretArn", "enableIdentityCrawler", "connectionConfiguration", "repositoryConfigurations", "additionalProperties" ] } ``` ### SharePoint (Online) JSON schema example for using the configuration property with AWS CloudFormation The following is the SharePoint (Online) JSON schema example for the configuration property for CloudFormation ``` { "AWSTemplateFormatVersion": "2010-09-09", "Description": "CloudFormation SHAREPOINT Data Source Template", "Resources": { "DataSourceSharePoint": { "Type": "AWS::QBusiness::DataSource", "Properties": { "ApplicationId": "app12345-1234-1234-1234-123456789012", "IndexId": "indx1234-1234-1234-1234-123456789012", "DisplayName": "MySharePointDataSource", "RoleArn": "arn:aws:iam::123456789012:role/qbusiness-data-source-role", "Configuration": { "type": "SHAREPOINTV2", "syncMode": "FULL_CRAWL", "secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-sharepoint-secret", "enableIdentityCrawler": "true", "connectionConfiguration": { "repositoryEndpointMetadata": { "tenantId": "1234567a-890b-1234-567c-123456789012", "domain": "example.sharepoint.com", "siteUrls": ["https://example.sharepoint.com/sites/mysite"], "repositoryAdditionalProperties": { "s3bucketName": "my-bucket", "s3certificateName": "my-certificate", "authType": "OAuth2", "version": "Online", "enableDeletionProtection": "false", "deletionProtectionThreshold": "15" } } }, "repositoryConfigurations": { "event": { "fieldMappings": [ { "indexFieldName": "event_id", "indexFieldType": "STRING", "dataSourceFieldName": "id", "dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'" } ] }, "page": { "fieldMappings": [ { "indexFieldName": "page_id", "indexFieldType": "STRING", "dataSourceFieldName": "id", "dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'" } ] } }, "additionalProperties": { "eventTitleFilterRegEx": ["^.*$"], "pageTitleFilterRegEx": ["^.*$"], "linkTitleFilterRegEx": ["^.*$"], "inclusionFilePath": ["documents/"], "exclusionFilePath": ["drafts/"], "inclusionFileTypePatterns": ["\\.docx"], "exclusionFileTypePatterns": ["\\.tmp"], "inclusionFileNamePatterns": ["*report*"], "exclusionFileNamePatterns": ["*draft*"], "enableDeletionProtection": "false", "maxFileSizeInMegaBytes": "50" } } } } } } ``` ## SharePoint (Online) YAML schema for using the configuration property with AWS CloudFormation The following is the SharePoint (Online) YAML schema and examples for the configuration property for AWS CloudFormation: **Topics** + [SharePoint (Online) YAML schema for using the configuration property with AWS CloudFormation](#sharepoint-cloud-cfn-yaml-schema) + [SharePoint (Online) YAML schema example for using the configuration property with AWS CloudFormation](#sharepoint-cloud-cfn-yaml-example) ### SharePoint (Online) YAML schema for using the configuration property with AWS CloudFormation The following is the SharePoint (Online) YAML schema for the configuration property for CloudFormation. ``` $schema: http://json-schema.org/draft-04/schema# type: object properties: type: type: string enum: - SHAREPOINTV2 - SHAREPOINT syncMode: type: string enum: - FULL_CRAWL - FORCED_FULL_CRAWL - CHANGE_LOG secretArn: type: string minLength: 20 maxLength: 2048 enableIdentityCrawler: anyOf: - type: boolean - type: string enum: - true - false connectionConfiguration: type: object properties: repositoryEndpointMetadata: type: object properties: tenantId: type: string pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" minLength: 36 maxLength: 36 domain: type: string siteUrls: type: array items: type: string pattern: "https://.*" repositoryAdditionalProperties: type: object properties: s3bucketName: type: string s3certificateName: type: string authType: type: string enum: - OAuth2 - OAuth2Certificate - OAuth2App - OAuth2_RefreshToken - Basic version: type: string enum: - Online enableDeletionProtection: anyOf: - type: boolean - type: string enum: - true - false default: false deletionProtectionThreshold: type: string default: "15" required: - authType - version required: - siteUrls - domain - repositoryAdditionalProperties required: - repositoryEndpointMetadata repositoryConfigurations: type: object properties: event: type: object properties: fieldMappings: type: array items: type: object properties: indexFieldName: type: string indexFieldType: type: string enum: - STRING - STRING_LIST - DATE dataSourceFieldName: type: string dateFieldFormat: type: string pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'" required: - indexFieldName - indexFieldType - dataSourceFieldName required: - fieldMappings page: type: object properties: fieldMappings: type: array items: type: object properties: indexFieldName: type: string indexFieldType: type: string enum: - STRING - DATE - LONG dataSourceFieldName: type: string dateFieldFormat: type: string pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'" required: - indexFieldName - indexFieldType - dataSourceFieldName required: - fieldMappings file: type: object properties: fieldMappings: type: array items: type: object properties: indexFieldName: type: string indexFieldType: type: string enum: - STRING - DATE - LONG dataSourceFieldName: type: string dateFieldFormat: type: string pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'" required: - indexFieldName - indexFieldType - dataSourceFieldName required: - fieldMappings link: type: object properties: fieldMappings: type: array items: type: object properties: indexFieldName: type: string indexFieldType: type: string enum: - STRING - STRING_LIST - DATE dataSourceFieldName: type: string dateFieldFormat: type: string pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'" required: - indexFieldName - indexFieldType - dataSourceFieldName required: - fieldMappings attachment: type: object properties: fieldMappings: type: array items: type: object properties: indexFieldName: type: string indexFieldType: type: string enum: - STRING - STRING_LIST - DATE dataSourceFieldName: type: string dateFieldFormat: type: string pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'" required: - indexFieldName - indexFieldType - dataSourceFieldName required: - fieldMappings comment: type: object properties: fieldMappings: type: array items: type: object properties: indexFieldName: type: string indexFieldType: type: string enum: - STRING - STRING_LIST - DATE dataSourceFieldName: type: string dateFieldFormat: type: string pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'" required: - indexFieldName - indexFieldType - dataSourceFieldName required: - fieldMappings required: [] additionalProperties: type: object properties: eventTitleFilterRegEx: type: array items: type: string pageTitleFilterRegEx: type: array items: type: string linkTitleFilterRegEx: type: array items: type: string inclusionFilePath: type: array items: type: string exclusionFilePath: type: array items: type: string inclusionFileTypePatterns: type: array items: type: string exclusionFileTypePatterns: type: array items: type: string inclusionFileNamePatterns: type: array items: type: string exclusionFileNamePatterns: type: array items: type: string inclusionOneNoteSectionNamePatterns: type: array items: type: string exclusionOneNoteSectionNamePatterns: type: array items: type: string inclusionOneNotePageNamePatterns: type: array items: type: string exclusionOneNotePageNamePatterns: type: array items: type: string crawlFiles: anyOf: - type: boolean - type: string enum: - true - false crawlPages: anyOf: - type: boolean - type: string enum: - true - false crawlEvents: anyOf: - type: boolean - type: string enum: - true - false crawlComments: anyOf: - type: boolean - type: string enum: - true - false crawlLinks: anyOf: - type: boolean - type: string enum: - true - false crawlAttachments: anyOf: - type: boolean - type: string enum: - true - false crawlListData: anyOf: - type: boolean - type: string enum: - true - false crawlAcl: anyOf: - type: boolean - type: string enum: - true - false aclConfiguration: type: string enum: - ACLWithLDAPEmailFmt - ACLWithManualEmailFmt - ACLWithUsernameFmt emailDomain: type: string isCrawlLocalGroupMapping: anyOf: - type: boolean - type: string enum: - true - false isCrawlAdGroupMapping: anyOf: - type: boolean - type: string enum: - true - false maxFileSizeInMegaBytes: type: string required: [] version: type: string anyOf: - pattern: 1.0.0 required: - type - syncMode - secretArn - enableIdentityCrawler - connectionConfiguration - repositoryConfigurations - additionalProperties ``` ### SharePoint (Online) YAML schema example for using the configuration property with AWS CloudFormation The following is the SharePoint (Online) YAML example for the Configuration property for CloudFormation: ``` AWSTemplateFormatVersion: "2010-09-09" Description: CloudFormation SHAREPOINT Data Source Template Resources: DataSourceSharePoint: Type: AWS::QBusiness::DataSource Properties: ApplicationId: app12345-1234-1234-1234-123456789012 IndexId: indx1234-1234-1234-1234-123456789012 DisplayName: MySharePointDataSource RoleArn: arn:aws:iam::123456789012:role/qbusiness-data-source-role Configuration: type: SHAREPOINTV2 syncMode: FULL_CRAWL secretArn: arn:aws:secretsmanager:us-west-2:123456789012:secret:my-sharepoint-secret enableIdentityCrawler: "true" connectionConfiguration: repositoryEndpointMetadata: tenantId: 1234567a-890b-1234-567c-123456789012 domain: example.sharepoint.com siteUrls: - https://example.sharepoint.com/sites/mysite repositoryAdditionalProperties: s3bucketName: my-bucket s3certificateName: my-certificate authType: OAuth2 version: Online enableDeletionProtection: "false" deletionProtectionThreshold: "15" repositoryConfigurations: event: fieldMappings: - indexFieldName: event_id indexFieldType: STRING dataSourceFieldName: id dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z' page: fieldMappings: - indexFieldName: page_id indexFieldType: STRING dataSourceFieldName: id dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z' additionalProperties: eventTitleFilterRegEx: - "^.*$" pageTitleFilterRegEx: - "^.*$" linkTitleFilterRegEx: - "^.*$" inclusionFilePath: - documents/ exclusionFilePath: - drafts/ inclusionFileTypePatterns: - ".docx" exclusionFileTypePatterns: - ".tmp" inclusionFileNamePatterns: - "*report*" exclusionFileNamePatterns: - "*draft*" enableDeletionProtection: "false" maxFileSizeInMegaBytes: "50" ``` # How Amazon Q Business connector crawls SharePoint (Online) ACLs When you connect an SharePoint (Online) data source to Amazon Q Business, Amazon Q crawls ACL information attached to a document (user and group information) from your SharePoint (Online) instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level. To filter using a username, use the **User principal name** from your Azure portal. For example, johnstiles@amazonq.onmicrosoft.com. When you use a SharePoint group for user context filtering, calculate the group ID as follows: **For local groups** 1. Get the site name. For example, `https://host.onmicrosoft.com/sites/siteName.` 1. Take the SHA256 hash of the site name. For example, `430a6b90503eef95c89295c8999c7981`. 1. Create the group ID by concatenating the SHA256 hash with a vertical bar ( \$1 ) and the group name. For example, if the group name is "local group name", the group ID is the following: `"430a6b90503eef95c89295c8999c7981 | localGroupName"` (with a space before and after the vertical bar). **For Microsoft Entra ID (formerly Azure AD) groups** 1. You must integrate the Microsoft Entra ID (formerly Azure AD) with Amazon Identity Center and use the same group name present on Azure portal. For more information, see: + [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) + [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler) + [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) # SharePoint (Online) data source connector field mappings To help you structure data for retrieval and chat filtering, Amazon Q Business crawls data source document attributes or metadata and maps them to fields in your Amazon Q index. Amazon Q has reserved fields that it uses when querying your application. When possible, Amazon Q automatically maps these built-in fields to attributes in your data source. If a built-in field doesn't have a default mapping, or if you want to map additional index fields, use the custom field mappings to specify how a data source attribute maps to your Amazon Q application. You create field mappings by editing your data source after your application environment and retriever are created. To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html). **Important** Filtering using document attributes in chat is only supported through the API. The Amazon Q Sharepoint connector supports the following entities and the associated reserved and custom attributes. **Important** If you map any SharePoint (Online) field to Amazon Q document title and document body fields, Amazon Q will generate responses from data in the document title and body. **Note** You can map any Sharepoint field to the document title or document body Amazon Q reserved/default index fields. **Topics** + [Files](#sharepoint-field-mappings-files) + [Events](#sharepoint-field-mappings-events) + [Pages](#sharepoint-field-mappings-pages) + [Links](#sharepoint-field-mappings-links) + [Attachments](#sharepoint-field-mappings-attachments) + [Comments](#sharepoint-field-mappings-comments) ## Files | Sharepoint field name | Index field name | Description | Data type | | --- | --- | --- | --- | | title | sp\$1title | Custom | String | | sourceUri | \$1source\$1uri | Default | String | | checkInComment | sp\$1checkInComment | Custom | String | | size | sp\$1sizeLong | Custom | Long (numeric) | | lastModifiedDateTime | \$1last\$1updated\$1at | Default | Date | | createdAt | \$1created\$1at | Default | Date | | author | \$1authors | Default | String list | | majorVersion | sp\$1majorVersion | Custom | String | | uiVersionLabel | sp\$1uiVersionLabel | Custom | String | | uniqueId | sp\$1uniqueId | Custom | String | | irmEnabled | sp\$1irmEnabled | Custom | String | | checkOutType | sp\$1checkOutType | Custom | String | | category | \$1category | Default | String | | modifiedBy | sp\$1modifiedBy | Custom | String | | level | sp\$1level | Custom | String | | uiVersion | sp\$1uiVersion | Custom | String | | contentTag | sp\$1contentTag | Custom | String | | eTag | sp\$1eTag | Custom | String | | oneNoteDocument | sp\$1oneNoteDocument | Custom | String | | oneNoteSection | sp\$1oneNoteSection | Custom | String | | oneNotePage | sp\$1oneNotePage | Custom | String | ## Events | Sharepoint field name | Index field name | Description | Data type | | --- | --- | --- | --- | | title | sp\$1title | Custom | String | | lastModifiedDateTime | \$1last\$1updated\$1at | Default | Date | | sourceUri | \$1source\$1uri | Default | String | | attachments | sp\$1hasAttachments | Custom | String | | createdDate | \$1created\$1at | Default | Date | | authorId | sp\$1authorId | Custom | String | | editorId | sp\$1editorId | Custom | String | | location | sp\$1location | Custom | String | | eventDate | sp\$1eventDate | Custom | Date | | eventEndDate | sp\$1eventEndDate | Custom | Date | | ifRecurrence | sp\$1ifRecurrence | Custom | String | | ifAllDayEvent | sp\$1ifAllDayEvent | Custom | String | | category | \$1category | Default | String | | eventCategory | sp\$1eventcategory | Custom | String | ## Pages | Sharepoint field name | Index field name | Description | Data type | | --- | --- | --- | --- | | createdDateTime | \$1created\$1at | Default | Date | | lastModifiedDateTime | \$1last\$1updated\$1at | Default | Date | | title | sp\$1title | Custom | String | | sourceUri | \$1source\$1uri | Default | String | | firstPublishedDate | sp\$1firstPublishedDate | Custom | Date | | authorId | sp\$1authorId | Custom | String | | editorId | sp\$1editorId | Custom | String | | category | \$1category | Default | String | ## Links | Sharepoint field name | Index field name | Description | Data type | | --- | --- | --- | --- | | createdAt | \$1created\$1at | Default | Date | | lastModifiedDateTime | \$1last\$1updated\$1at | Default | Date | | title | sp\$1title | Custom | String | | sourceUri | \$1source\$1uri | Default | String | | fileType | sp\$1fileType | Custom | String | | fileDirPath | sp\$1fileDirPath | Custom | String | | firstPublishedDate | sp\$1firstPublishedDate | Custom | Date | | authorId | sp\$1authorId | Custom | String | | editorId | sp\$1editorId | Custom | String | | category | \$1category | Default | String | | size | sp\$1sizeLong | Custom | Long (numeric) | ## Attachments | Sharepoint field name | Index field name | Description | Data type | | --- | --- | --- | --- | | title | sp\$1\$1title | Custom | String | | parentCreatedDate | \$1created\$1at | Default | Date | | sourceUri | \$1source\$1uri | Default | String | | parentModifiedDate | \$1last\$1updated\$1at | Custom | Date | | parentListId | sp\$1parentListId | Custom | String | | parentTitle | sp\$1parentTitle | Custom | String | | category | \$1category | Default | String | ## Comments | Sharepoint field name | Index field name | Description | Data type | | --- | --- | --- | --- | | createdDateTime | \$1created\$1at | Default | Date | | likedBy | sp\$1likedBy | Custom | String | | sourceUri | \$1source\$1uri | Custom | String | | isReply | sp\$1isReply | Custom | String | | author | \$1authors | Default | String list | | listId | sp\$1listId | Custom | String | | category | \$1category | Default | String | | replyCount | sp\$1replyCount | Custom | String | | parentTitle | sp\$1parentTitle | Custom | String | # IAM role for SharePoint (Online) connector **Note** **(Optional)** If you use **Azure App-Only authentication**, you also need to add permissions for Amazon Q to access the certificate stored in your Amazon S3 bucket. If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached. If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role. To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*. To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions: + Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents. + Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents. + Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance. + **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC. ``` { "Version": "2012-10-17", , "Statement": [ { "Sid": "AllowsAmazonQToGetSecret", "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue" ], "Resource": [ "arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]" ] }, { "Sid": "AllowsAmazonQToDecryptSecret", "Effect": "Allow", "Action": [ "kms:Decrypt" ], "Resource": [ "arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]" ], "Condition": { "StringLike": { "kms:ViaService": [ "secretsmanager.*.amazonaws.com" ] } } }, { "Sid": "AllowsAmazonQToIngestDocuments", "Effect": "Allow", "Action": [ "qbusiness:BatchPutDocument", "qbusiness:BatchDeleteDocument" ], "Resource": [ "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}", "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}" ] }, { "Sid": "AllowsAmazonQToIngestPrincipalMapping", "Effect": "Allow", "Action": [ "qbusiness:PutGroup", "qbusiness:CreateUser", "qbusiness:DeleteGroup", "qbusiness:UpdateUser", "qbusiness:ListGroups" ], "Resource": [ "arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}", "arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}", "arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*" ] } ``` **To allow Amazon Q to assume a role, you must also use the following trust policy:** ``` { "Version": "2012-10-17", , "Statement": [ { "Sid": "AllowsAmazonQServicePrincipal", "Effect": "Allow", "Principal": { "Service": "qbusiness.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "{{source_account}}" }, "ArnEquals": { "aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}" } } } ] } ``` For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds). **To ensure that Amazon Q Business is able to access Amazon S3 you objects:** If you are using Microsoft Entra ID (formerly Azure AD) App only authentication, you must ensure that Amazon Q Business is able access Amazon S3 to get the objects in your bucket. The following policy statement is provides permissions to access Amazon S3: ``` { "Version": "2012-10-17", , "Statement": [ { "Sid": "AllowsAmazonQToGetS3Objects", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::{{input_bucket_name}}/*" ], "Effect": "Allow", "Condition": { "StringEquals": { "aws:ResourceAccount": "{{account_id}}" } } } ] } ``` **If using a VPC:** If you are using a VPC, you must ensure that the permissions included in the following policy statement are included in your policy statement: ``` { "Version": "2012-10-17", , "Statement": [ { { "Sid": "AllowsAmazonQToCreateAndDeleteNI", "Effect": "Allow", "Action": [ "ec2:CreateNetworkInterface", "ec2:DeleteNetworkInterface" ], "Resource": [ "arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]", "arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]" ] }, { "Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag", "Effect": "Allow", "Action": [ "ec2:CreateNetworkInterface", "ec2:DeleteNetworkInterface" ], "Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*", "Condition": { "StringLike": { "aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*" }, "ForAllValues:StringEquals": { "aws:TagKeys": [ "AMAZON_Q" ] } } }, { "Sid": "AllowsAmazonQToCreateTags", "Effect": "Allow", "Action": [ "ec2:CreateTags" ], "Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*", "Condition": { "StringEquals": { "ec2:CreateAction": "CreateNetworkInterface" } } }, { "Sid": "AllowsAmazonQToCreateNetworkInterfacePermission", "Effect": "Allow", "Action": [ "ec2:CreateNetworkInterfacePermission" ], "Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*", "Condition": { "StringLike": { "aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*" } } }, { "Sid": "AllowsAmazonQToDescribeResourcesForVPC", "Effect": "Allow", "Action": [ "ec2:DescribeNetworkInterfaces", "ec2:DescribeAvailabilityZones", "ec2:DescribeNetworkInterfaceAttribute", "ec2:DescribeVpcs", "ec2:DescribeRegions", "ec2:DescribeNetworkInterfacePermissions", "ec2:DescribeSubnets" ], "Resource": "*" } ] } ``` # Understand error codes in the SharePoint (Online) connector The following table provides information about error codes you may see for the Microsoft SharePoint connector and suggested resolutions. If you used the Amazon Q section of the AWS [console](https://console.aws.amazon.com/console/home) to configure your connectors, be sure to make the changes associated with an error through the console as well. You can refer to the Microsoft SharePoint [documentation](https://learn.microsoft.com/en-us/sharepoint/) for more information regarding SharePoint settings and details. **Authentication issues** | Error code | Error message | Suggested resolution | Context | Where to find error | | --- | --- | --- | --- | --- | | SPE-5001 | Authentication failed. Configuration might contain wrong credentials. | Provide valid credentials like username, password or client Id, client secret and tenant Id. | Occurs during initial connector setup or when authentication credentials expire | Console: During configuration or Sync run history | | SPE-5124 | There was a problem while retrieving authType. Auth-Type might be empty or null. | Ensure AUTH Type in configuration must be not null. | Authentication type configuration error | Console: Configuration page | | SPE-5129 | There was a problem while retrieving password. Password might be empty or null. | Provide password. | Basic authentication configuration error | Console: During initial setup | | SPE-5130 | There was a problem while retrieving username.Username might be empty or null. | Provide username. | Basic authentication configuration error | Console: During initial setup | | SPE-5136 | The provided authType was not a valid Sharepoint Connector authentication method. | Provide valid authType. The value of authType should be one of [Basic, OAuth2Certificate, OAuth2]. | Authentication method configuration error | Console: Configuration page | | SPE-5125 | There was a problem while retrieving clientId. Client ID might be empty or null. | Provide Client Id. | OAuth configuration error | Console: Authentication Configuration | | SPE-5126 | There was a problem while retrieving clientSecret. Client Secret might be empty or null. | Provide Client Secret. | OAuth configuration error | Console: Authentication Configuration | | SPE-5127 | There was a problem while retrieving tenantId. Tenant ID might be empty or null. | Provide Tenant Id. | SharePoint tenant configuration error | Console: Authentication Configuration | **SharePoint Configuration issues** | Error code | Error message | Suggested resolution | Context | Where to find error | | --- | --- | --- | --- | --- | | SPE-5135 | The provided version was not a valid Sharepoint Connector version. Version should be one of [Online, Server]. | Version should be one of [Online, Server]. | SharePoint version selection error | Console: During initial setup | | SPE-5138 | There was a problem while retrieving onPremVersion. On prem Version might be empty or null | Ensure onPremVersion is not be null or non-empty. | SharePoint on-premises version error | Console: Version Configuration | | SPE-5139 | The provided onPremVersion was not valid Sharepoint on-prem version. On prem version should be one of [2013, 2016, 2019, SubscriptionEdition]. | Provide a valid onPremVersion. On prem version should be one of [2013, 2016, 2019, SubscriptionEdition]. | SharePoint on-premises version selection error | Console: Version Configuration | | SPE-5121 | There was a problem while retrieving values for crawl entities. Values might be empty or incorrect. It should be either true or false. | In the connector's settings, ensure all crawl options are set to either 'true' or 'false'. These settings determine what content types are indexed. | Crawler configuration error | Console: Crawl Configuration | | SPE-5122 | There was a problem while retrieving domain. Domain might be empty or null. | Provide a valid SharePoint domain name in the connector configuration. | Domain configuration error during SharePoint connection setup. | Console: Domain Configuration | | SPE-5123 | There was a problem while retrieving version. Version might be empty or null. | Provide valid version and it should not be null. | SharePoint version configuration error | Console: Version Configuration | **Network and Connectivity issues** | Error code | Error message | Suggested resolution | Context | Where to find error | | --- | --- | --- | --- | --- | | SPE-5004 | Inet Address validation Failed. | Check your network configuration and ensure the SharePoint server address is accessible from your network. Verify DNS resolution and network routing are properly configured. | Network address validation error | CloudWatch Logs during sync | | SPE-5005 | Failed : HTTP protocol violation has occurred. | Try running the connector again. | Occurs when the connector is configured to use a proxy but cannot establish connection. | CloudWatch Logs during sync | | SPE-5200 | There was a problem while connecting to the URL. | Verify that the SharePoint site URL is accessible and that you have proper network connectivity. Check SharePoint site status and your network configuration. | Site connectivity error | Console: Sync run history | | SPE-5002 | SPE-5002 Connection failed due to wrong credentials or invalid sites. Update your configuration and try again. | Provide valid Host URL or Domain. | Happens during connector configuration when trying to establish initial connection | Console: Basic Configuration | | SPE-5003 | Provided URL is incorrect | Provide correct URL. | Generic URL validation error | Console: Site Configuration | **LDAP Configuration issues** | Error code | Error message | Suggested resolution | Context | Where to find error | | --- | --- | --- | --- | --- | | SPE-5009 | There was a problem while connecting to LDAP. Check LDAP configuration. | Provide valid LDAP configuration details. | LDAP connection failure | Console: LDAP Configuration | | SPE-5140 | There was a problem while retrieving ldapUrl. LDAP Url might be empty or null. | Ensure ldapUrl is not null or empty. | LDAP configuration error | Console: LDAP Configuration | | SPE-5141 | There was a problem while retrieving baseDn. Base DN might be empty or null. | Ensure baseDn is not be null or empty. | LDAP configuration error | Console: LDAP Configuration | | SPE-5146 | There was a problem while retrieving ldapUsername. LDAP Username might be empty or null. | Ensure ldapUser is not null or empty. | LDAP authentication error | Console: LDAP Configuration | | SPE-5147 | There was a problem while retrieving ldapPassword. LDAP Password might be empty or null. | Ensure ldapPassword is not null or empty. | LDAP authentication error | Console: LDAP Configuration | **Microsoft Entra ID (formerly Azure AD) Configuration issues** | Error code | Error message | Suggested resolution | Context | Where to find error | | --- | --- | --- | --- | --- | | SPE-5152 | There was a problem while retrieving AD Client ID. AD Client ID should not be empty. | Ensure AD Client Id must be non-empty. | Microsoft Entra ID (formerly Azure AD) configuration error | Console: Microsoft Entra ID (formerly Azure AD) Configuration | | SPE-5153 | Invalid AD Client Id pattern. | Provide valid AD Client Id pattern. | Microsoft Entra ID (formerly Azure AD) Client ID format error | Console: Microsoft Entra ID (formerly Azure AD) Configuration | | SPE-5154 | There was a problem while retrieving AD Client Secret. AD Client Secret should not be empty. | Ensure AD Client Secret is non-empty. | Microsoft Entra ID (formerly Azure AD) configuration error | Console: Microsoft Entra ID (formerly Azure AD) Configuration | **Document Access and Permissions issues** | Error code | Error message | Suggested resolution | Context | Where to find error | | --- | --- | --- | --- | --- | | SPE-5144 | There was a problem while retrieving aclConfiguration. ACL Configuration might be empty, null or invalid | Provide valid aclConfiguration. aclConfiguration should be one of [ ACLWithLDAPEmailFmt, ACLWithManualEmailFmt, ACLWithUsernameFmt ]. | ACL configuration error | Console: Access Control Configuration | | SPE-5145 | There was a problem while retrieving emailDomain. Email Domain might be empty or null. | Ensure emailDomain is not null or empty. | Email domain configuration error | Console: Domain Configuration | | SPE-5155 | There can't be more than one site for SharePoint on-prem app-only authentication. | Ensure that their must be only single site present for SharePoint on-prem app-only authentication. | SharePoint on-premises app authentication configuration error | Console: Site Configuration | **Security Configuration issues** | Error code | Error message | Suggested resolution | Context | Where to find error | | --- | --- | --- | --- | --- | | SPE-5008 | Valid SSL Certificate could not be found for connector. | Upload a valid SSL certificate. For SharePoint on-premises installations, ensure you have exported your SharePoint SSL certificate and uploaded it to the connector. | SSL certificate validation failure | Console: Security Configuration | **IAM Configuration issues** | Error code | Error message | Suggested resolution | Context | Where to find error | | --- | --- | --- | --- | --- | | SPE-5101 | There was a problem while retrieving dataSourceIamRoleArn. Data Source IAM Role ARN might be empty or null. | Verify that the IAM role exists and has the correct permissions. Check the IAM console to ensure the role is properly configured. | This error occurs when the connector cannot access the required IAM role during synchronization. | Console: IAM Configuration | **Site Configuration issues** | Error code | Error message | Suggested resolution | Context | Where to find error | | --- | --- | --- | --- | --- | | SPE-5128 | There was a problem while retrieving siteUrls. Site URLs might be empty or null. | Provide at least one Site Url. | Site configuration error | Console: Site Configuration | | SPE-5131 | There was a problem while retrieving username. Email was invalid. | Provide valid email address. | User email validation error | Console: User Configuration | | SPE-5132 | There was a problem while retrieving url. This URL was invalid. | Provide a valid URL. | Provide a valid SharePoint site URL in the format https://your-sharepoint-site.com | Console: Site Configuration | | SPE-5149 | The provided siteUrls contain duplicate sites. Remove duplicates. | Ensure SiteUrls must not be the same. | Duplicate site URL configuration error | Console: Site Configuration | **Other Configuration issues** | Error code | Error message | Suggested resolution | Context | Where to find error | | --- | --- | --- | --- | --- | | SPE-5133 | There was a problem while retrieving s3CertificateName. S3 Certificate Name might be empty or null. | When using certificate-based authentication, upload your authentication certificate to an S3 bucket and provide the certificate name and bucket details in the connector configuration. | S3 certificate configuration error | Console: Security Configuration | | SPE-5134 | There was a problem while retrieving s3BucketName. S3 Bucket Name might be empty or null | When using certificate-based authentication, upload your authentication certificate to an S3 bucket and provide the certificate name and bucket details in the connector configuration. | S3 bucket configuration error | Console: S3 Configuration | | SPE-5151 | Error parsing the field value. Size is over maximum allowed limit. | Reduce the field value size to within the maximum allowed limit. | Field size limit exceeded | Console: Field Configuration |