@devries-cameron20 / composio Mirror · read-only
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 06:00 UTC

next
md 220 lines 12.3 KB
Rendered Raw
1 ## Use a tenant-specific Microsoft endpoint for SharePoint Graph
2
3 Set `issuer` to your Microsoft Entra tenant ID to authenticate SharePoint Graph
4 through that tenant's endpoint instead of `/common`. Use the directory (tenant)
5 ID, not your SharePoint site name. Microsoft's [tenant authority
6 reference](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc#find-your-apps-openid-configuration-document-uri)
7 explains how tenant-specific sign-in differs from `common`.
8
9 First, retrieve the toolkit's authentication fields with your Composio project
10 API key:
11
12 ### Inspect the toolkit metadata
13
14 #### Python
15
16 ```python
17 from composio import Composio
18
19 composio = Composio()
20 print(composio.toolkits.get("sharepoint_graph"))
21 ```
22
23 #### TypeScript
24
25 ```typescript
26 import { Composio } from "@composio/core";
27
28 const composio = new Composio();
29 console.log(await composio.toolkits.get("sharepoint_graph"));
30 ```
31
32 #### API
33
34 ```bash
35 curl --fail-with-body \
36 'https://backend.composio.dev/api/v3.1/toolkits/sharepoint_graph' \
37 -H "x-api-key: $COMPOSIO_API_KEY"
38 ```
39
40 <!-- end-languages -->
41
42 Find the `OAUTH2` auth scheme and inspect `fields.auth_config_creation` and
43 `fields.connected_account_initiation`. The `issuer` field appears under
44 `connected_account_initiation`.
45
46 To apply the same tenant ID to new connections, [update your custom auth
47 config](/reference/api-reference/auth-configs/patchAuthConfigsByNanoid) with
48 `shared_credentials.issuer`:
49
50 ### Update the auth config
51
52 #### Python
53
54 The high-level Python update helper does not forward `shared_credentials`; use its public generated client.
55
56 ```python
57 from composio import Composio
58
59 composio = Composio()
60 result = composio.client.auth_configs.update(
61 "<AUTH_CONFIG_ID>",
62 type="custom",
63 shared_credentials={"issuer": "<MICROSOFT_TENANT_ID>"},
64 )
65 print(result)
66 ```
67
68 #### TypeScript
69
70 ```typescript
71 import { Composio } from "@composio/core";
72
73 const composio = new Composio();
74 const result = await composio.getClient().authConfigs.update("<AUTH_CONFIG_ID>", {
75 type: "custom",
76 shared_credentials: { issuer: "<MICROSOFT_TENANT_ID>" },
77 });
78 console.log(result);
79 ```
80
81 #### API
82
83 ```bash
84 curl --fail-with-body -X PATCH \
85 'https://backend.composio.dev/api/v3.1/auth_configs/<AUTH_CONFIG_ID>' \
86 -H "x-api-key: $COMPOSIO_API_KEY" \
87 -H 'content-type: application/json' \
88 -d '{
89 "type": "custom",
90 "shared_credentials": {
91 "issuer": "<MICROSOFT_TENANT_ID>"
92 }
93 }'
94 ```
95
96 <!-- end-languages -->
97
98 Replace `<AUTH_CONFIG_ID>` with your SharePoint Graph custom auth config ID.
99 Every new connection created through this auth config inherits the tenant ID.
100 Create a new connection using that config and complete Microsoft sign-in to use
101 the tenant-specific endpoint. This recipe configures new connections; it does
102 not migrate existing connected accounts.
103
104 ## SharePoint REST APIs and SharePoint Graph are separate API families
105
106 Treat the current SharePoint toolkit and the SharePoint Graph toolkit as separate API families, not as interchangeable variants of the same connection.
107
108 - The current SharePoint toolkit uses SharePoint REST/OData endpoints on the tenant SharePoint host, usually shaped like `https://<tenant>.sharepoint.com/_api/...`.
109
110 - The SharePoint Graph toolkit uses Microsoft Graph endpoints, usually shaped like `https://graph.microsoft.com/v1.0/sites/...`.
111
112 - The scopes and token audience must match the endpoint family. SharePoint REST expects a SharePoint resource token such as `https://<tenant>.sharepoint.com/.default`; SharePoint Graph expects Microsoft Graph permissions/scopes such as `Sites.*`, `Files.*`, `User.Read`, or `https://graph.microsoft.com/.default` for S2S.
113
114 - Do not add Microsoft Graph scopes such as `Sites.Read.All` or `User.Read.All` to the current SharePoint REST auth config as a workaround. Those scopes produce a Graph-audience token and can cause 401 responses when the toolkit calls SharePoint REST.
115
116 - Do not reuse an existing SharePoint REST connected account/token for SharePoint Graph. A Graph-scoped token is not valid for SharePoint REST, and a SharePoint-audience token is not valid for Graph.
117
118 - The same Microsoft Entra app registration may be reused only if it has the right API permissions and redirect/client-credential setup for the target toolkit, but create or use a separate Composio auth config and reconnect.
119
120 SharePoint REST is not deprecated just because SharePoint Add-Ins / Azure ACS are retiring. Microsoft still documents SharePoint REST/CSOM as valid when Graph does not cover the needed functionality. Graph is the unified Microsoft 365 API and is usually better for cross-service or client-secret S2S flows, but it does not have perfect parity with SharePoint REST.
121
122 Example response:
123
124 ```text
125 The SharePoint and SharePoint Graph toolkits use different Microsoft API surfaces.
126
127 The existing SharePoint toolkit uses SharePoint REST/OData endpoints such as `https://<tenant>.sharepoint.com/_api/...` and needs a SharePoint-resource scope like `https://<tenant>.sharepoint.com/.default`.
128
129 The SharePoint Graph toolkit uses Microsoft Graph endpoints such as `https://graph.microsoft.com/v1.0/sites/...` and needs Graph permissions such as `Sites.*`, `Files.*`, `User.Read`, or for S2S `https://graph.microsoft.com/.default`.
130
131 Because the tokens are issued for different resources, please create/use a separate Composio auth config for SharePoint Graph and reconnect. You may be able to reuse the same Microsoft Entra app registration if it has the required Graph permissions configured, but the existing SharePoint connected account token should not be used for SharePoint Graph.
132 ```
133
134 ## `/teams/` SharePoint sites require the server-relative Subsite path
135
136 If your SharePoint site URL is under `/teams/<site>` instead of `/sites/<site>`, do not pass only `<site>` in the SharePoint Subsite field. A bare subsite value is interpreted as `/sites/<site>` by the toolkit.
137
138 Reconnect the SharePoint account and set SharePoint Subsite to the full server-relative path, for example `/teams/<site>`. For per-call overrides, pass `site_name: "/teams/<site>"`.
139
140 Debugging signal: tool logs show SharePoint calls like `https://tenant.sharepoint.com/sites/<site>/_api/...` returning `404 FILE NOT FOUND`, while the customer's actual SharePoint URL is `https://tenant.sharepoint.com/teams/<site>`. If the connected account is `ACTIVE` and the auth config is enabled, treat this as a path-prefix mismatch first, not an OAuth issue.
141
142 Example response:
143
144 ```text
145 This looks like a SharePoint site-path mismatch. Your site is under `/teams/...`, but the current connection/tool call is hitting `/sites/...`, which SharePoint returns as 404.
146
147 Please reconnect the SharePoint account and set the Subsite value to the full server-relative path: `/teams/<site-name>`. If you're passing it per tool call, use `site_name: "/teams/<site-name>"`. A bare value like `<site-name>` gets treated as `/sites/<site-name>`.
148 ```
149
150 ## SharePoint REST app-only client credentials use certificate auth
151
152 For the current Composio `share_point` toolkit, client credentials and certificate-based authentication are the same app-only path: client credentials is implemented with certificate-based authentication.
153
154 The required setup is:
155
156 - SharePoint tenant name, used for `https://<tenant>.sharepoint.com/_api` and the resource scope `https://<tenant>.sharepoint.com/.default`
157
158 - Microsoft Entra tenant ID
159
160 - Application/client ID
161
162 - RSA private key in PEM format for the certificate uploaded to the Entra app registration
163
164 - Certificate thumbprint (`x5t#S256`)
165
166 - Admin-consented SharePoint application permissions appropriate for the use case
167
168 Composio signs a JWT client assertion with the certificate/private key and requests a token from `https://login.microsoftonline.com/<tenantId>/oauth2/v2.0/token` using `grant_type=client_credentials` and the SharePoint `.default` scope. Customers should provide the fields above; they do not need to manually construct or pass a JWT assertion.
169
170 Scope wording: the token request uses `https://<tenant>.sharepoint.com/.default`. In Microsoft client credentials, `.default` means the token is issued for the application permissions/app roles already configured and admin-consented for that SharePoint resource. Composio's action-to-scope mapping API should not be recommended for this SharePoint S2S/certificate path today; it is useful for OAuth2 scope discovery, not as the S2S permission source of truth.
171
172 Do not offer a client-secret-only client-credentials setup for the SharePoint REST toolkit. That belongs to Microsoft Graph app-only flows and Composio's `sharepoint_graph` toolkit, which uses `https://graph.microsoft.com/.default` and accepts client ID + client secret. The legacy SharePoint Azure ACS app-only client ID/secret model existed but is retired and should not be recommended for new/current SharePoint REST integrations.
173
174 Example setup outline:
175
176 1. Generate a private key and self-signed/public certificate, for example with OpenSSL.
177
178 2. Upload the public certificate to the Microsoft Entra app registration under Certificates & secrets > Certificates.
179
180 3. Add/admin-consent SharePoint application permissions, such as the least-privileged site/list/file permission set appropriate for the customer.
181
182 4. Create/connect the Composio SharePoint S2S auth config with the SharePoint tenant name, Entra tenant ID, client ID, private key PEM, and certificate thumbprint. Composio handles the JWT client assertion and token exchange.
183
184 5. Ensure the Entra app has/admin-consented the SharePoint application permissions needed for the intended SharePoint REST operations. The requested token scope is `https://<tenant>.sharepoint.com/.default`; if using Selected permissions such as `Sites.Selected`, also grant explicit access to the target site/list/file.
185
186 6. Test with a simple SharePoint REST call such as `GET https://<tenant>.sharepoint.com/_api/web?$select=Title` using the connected account.
187
188 ## SharePoint `.default` scope uses the tenant domain placeholder
189
190 For a custom Microsoft Entra app, replace `{{site_name}}` in `https://{{site_name}}.sharepoint.com/.default` with the customer's SharePoint tenant/domain name. The resulting `.default` scope requests the application permissions already configured and admin-consented for that SharePoint resource.
191
192 ## Pass the SharePoint tenant/subdomain during connection initiation
193
194 The SharePoint tenant/subdomain is an explicit connection field; Composio does not derive it automatically from the OAuth token. If a connection points at `default.sharepoint.com` or the wrong tenant, reinitiate the connection and provide the correct tenant name.
195
196 ## The SharePoint subsite field is not a permission boundary
197
198 The SharePoint Subsite field supplies a default target when a tool call omits `site_name`. It does not restrict the Microsoft token, which retains the access granted to the consenting user or application.
199
200 ## Retrieve SharePoint site name from connected account state
201
202 Fetch the connected account and inspect its stored state to confirm the SharePoint site name. Newer SDK responses expose it under a shape such as `state.val.site_name`; older toolset responses may expose `data.site_name`.
203
204 ## Use `SHARE_POINT_SEARCH_QUERY` for KQL/FQL SharePoint search
205
206 Use `SHARE_POINT_SEARCH_QUERY` when a workflow needs flexible SharePoint search with KQL or FQL. For broader agentic discovery across SharePoint actions, Tool Router can discover and execute the relevant tools dynamically.
207
208 ## SharePoint toolkit slug is `share_point`
209
210 The SharePoint toolkit slug is `share_point`, while its tool slugs use the `SHARE_POINT_...` prefix. Related Microsoft toolkit slugs include `outlook`, `one_drive`, and `sharepoint_graph`.
211
212 ## Disable destructive SharePoint tools with `destructiveHint` or explicit tool filters
213
214 At session creation, disable tools carrying `destructiveHint` globally or for selected toolkits such as SharePoint and OneDrive. For finer control, explicitly allow or deny destructive tools by name.
215
216 ## `SHARE_POINT_UPLOAD_FROM_URL` needs a server-fetchable URL
217
218 This action first downloads `file_url` from Composio's backend and then uploads the bytes to SharePoint. The source must be a reachable HTTP(S) download URL; raw base64 content is not a URL.
219
220 For base64 or in-memory bytes, use `SHARE_POINT_UPLOAD_FILE` with the file content and name, or first create a temporary URL that the backend can reach. A 401/403 while downloading the source should be debugged as source-URL access, not as a destination folder problem. `conflict_behavior="rename"` only affects the target name after download succeeds.