A library that allows Node.js applications to interact with a Sharepoint Online site
npm install @wmfs/sharepoint
> A library that allows Node.js applications to interact with a Sharepoint Online site
For more information, see https://learn.microsoft.com/en-gb/entra/identity-platform/msal-authentication-flows#client-credentials
Interaction with Sharepoint Online is via the Sharepoint REST API. For more information, see https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins/get-to-know-the-sharepoint-rest-service?tabs=csom and https://learn.microsoft.com/en-us/previous-versions/office/developer/sharepoint-rest-reference/dn450841(v=office.15)
Note that this library makes use of a certificate as a credential, which is required by the Sharepoint REST API. For future reference, be aware that attempting to use a shared secret instead will result in the Sharepoint REST API refusing access with a HTTP 401 (Unauthorised) error.
``
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365
Note that (if your on Windows), if openssl hangs at any point, press ctrl+c a couple of times to return to the command prompt and re-run the command, but pre-pend 'winpty' and a space (so the command starts like winpty openssl...).
After executing the above command, you will be asked to enter the following information...
- A passphrase (twice). Do make a note of this as you will need it later.
- A 2 character country code ('UK')
- A state/province name ('Greater London')
- A locality name ('London')
- An organisation name ('Home Office')
- Common name ('.')
- Email address ('.')
After entering this information, openssl will generate two files - 'key.pem' (the private key) and 'cert.pem' (the certificate).
We also need the 'fingerprint' of the certificate - you can get this by executing the following command...
`
openssl x509 -in cert.pem -noout -fingerprint
This command will output something like this...
> SHA1 Fingerprint=XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX
Make a note of the fingerprint, but get rid of the colons - in your notes, the fingerprint should be exactly 40 characters long.
1. Sign in to the Microsoft Entra admin centre as at least a 'Cloud Application Administrator'.
2. If you have access to multiple tenants, click Settings in the top menu to switch to the tenant in which you want to register the app from the Directories+subscriptions menu.
3. Browse to Identity > Applications > App registrations and select New registration.
4. In Name, enter 'Test Application'
5. For sign-in audience, select 'Accounts in this organizational directory only'
6. Click the Register button
7. Copy the 'Application (client) ID' and the 'Directory (tenant) ID' and make a note of them somewhere as you'll need them later.
8. On the left, select 'Certificates & secrets'
9. In the 'Certificates' section, select 'Upload certificate'
10. Select the 'cert.pem' file you created earlier and click the Upload button
11. In the description, enter 'Test Application Certificate'
12. Click the Add button.
13. On the left, select 'API Permissions'
14. On the right, under Configured permissions, click the 'Add a permission' button
15. Ensure that the Microsoft APIs tab is selected
16. In the 'Commonly used Microsoft APIs' section, select 'Sharepoint'
17. In the 'Application permissions' section, select the Sites.Selected in the list (use the search box if necessary)
18. Click the 'Add permissions' button at the bottom
19. Click the 'Grant admin consent' button (next to the 'Add a permission' button)
20. In a Web Browser, open Graph Explorer (https://developer.microsoft.com/en-us/graph/graph-explorer) and log in as someone who has the necessary privileges to create/modify sharepoint access permissions.
21. Execute the following GET request, replacing '
`
https://graph.microsoft.com/v1.0/sites?select=webUrl,Title,Id&$search="
You should see something like this - make a note of the value.id property (the 'site id') as you'll need it later...
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites",
"value": [
{
"id": "XXX.sharepoint.com,XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX,XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"webUrl": "https://XXX.sharepoint.com/sites/SiteName",
"displayName": "SiteName"
}
]
}
22. We now need to make a POST request (though this time we need to put something in the body) to give the above application permissions to read and write to the site, via an URL like this (replacing '
`
https://graph.microsoft.com/v1.0/sites/
So for the above site for example, the URL would look like this...
> https://graph.microsoft.com/v1.0/sites/XXX.sharepoint.com,XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX,XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/permissions
...with this as the body, changing XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX to the 'application (client) id' you made a note of earlier in step 7...
{
"roles": [
"manage"
],
"grantedToIdentities": [
{
"application": {
"id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"displayName": "Test Application"
}
}
]
}
| Name | Value |
|------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| SHAREPOINT_AUTH_SCOPE | https://XXX.sharepoint.com/.default, replacing SHAREPOINT_CLIENT_IDXXX with your tenant name |
| | The 'application (client) id' produced by Azure Portal when the application is registered |SHAREPOINT_CERT_PRIVATE_KEY_FILE
| | The path and filename of the certificate private key file (the 'key.pem' file) |SHAREPOINT_CERT_PASSPHRASE
| | The certificate passphrase |SHAREPOINT_CERT_FINGERPRINT
| | The 40 character (no colons!) hexadecimal fingerprint of the certificate |SHAREPOINT_DEBUG
| | SHAREPOINT_TENANT_IDY or YES or TRUE if you want information helpful for debugging logged to the console (optional) |
| | The 'directory (tenant) id' produced by Azure Portal when the application is registered |
Alternatively, you can edit a /.env file if you prefer (as per dotenv)
Here are the functions the Sharepoint class makes available...
`javascript
const Sharepoint = require('@wmfs/sharepoint')
const sp = new Sharepoint('URL HERE')
sp.authenticate()
sp.getWebEndpoint()
sp.getContents(path)
sp.createFolder(path)
sp.deleteFolder(path)
sp.createFile(options) // options = { path, fileName, data }
sp.deleteFile(options) // options = { path, fileName }
sp.createFileChunked(options) // options = { path, fileName, stream, fileSize, chunkSize }
`
| Name | Value |
|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| SHAREPOINT_TESTS_DIR_PATH | The location in your site under which the tests will work with when creating/deleting files/folders e.g. /Shared Documents/General/test |SHAREPOINT_URL
| | This url of the site that the tests will interact with - something like https://XXX.sharepoint.com/sites/SiteName, replacing /.envXXX with your tenant name and SiteName with your site name |
Again, you can edit a file if you prefer (as per dotenv)
Then, run:
`
npm run test