docToolchain / docToolchain/docToolchain
Connecting to Confluence cloud via Atlassian ReST API currently not possible with scoped tokens
- Dominant language
- Groovy
- Stars
- 864
- Forks
- 240
- Avg merge
- 2m
- Merged PRs (30d)
- 2
Description
**Describe the bug**
As we want to automate documentation generation we want to adopt docToolChain. Since we use Confluence Cloud and want clean processes we asked internal IT for a service account which must use scoped tokens as per [official docs for scoped tokens](https://support.atlassian.com/confluence/kb/scoped-api-tokens-in-confluence-cloud/)
This changes the API endpoint to be `https://api.atlassian.com/ex/confluence//`
After altering the config endpoint in the groovy file the calls did still not work but the curl counterparts did.
The reason is the way doctoolchain checks for context in the url and if there is more than one "/" after the baseurl the context is returned empty (ConfluenceClient.groovy)
I patched a local version (after downloading sources) and added a switch and now the verifyConfluenceAPIAccess tasks runs successfully and also the publishToConfluence tasks (with a token that contains the permissions below)
**To Reproduce**
Steps to reproduce the behavior:
1. Use Confluence Cloud
2. Use Scoped API tokens (service accounts are enforced to use scoped tokens)
3. Adjust base-url to match documented api endpoint
4. See error
**Expected behavior**
API endpoint handling (context) that is aware of differing url and does not drop context
**Configuration**
- docToolchain version 3.5
- OS: docToolchain docker container respectively windows
- Browser independent
**Additional context**
I would either prefer a clean config switch for scoped tokens which is then used in the context determination or a clear indicator in the docs and an url match against "https://api.atlassian.com/ex/confluence" as the url must start with this fragment.
I'm happy to help and develop the fix in a branch if I get guidance which branch to use for creating the fix-branch.
I would also be happy if it's possible to address this in the 3.x versions (at least starting from 3.5.x) and not postponing to 4.0
I also looked up permissions for the api calls which are in the doctoolchain code and matched it against confluence api docs to determin granular permissions:
**Read**
read:space:confluence
read:content-details:confluence
read:confluence-user (only classic scope I couldn't get rid of as of now)
read:page:confluence
read:attachment:confluence
**Write**
write:page:confluence
write:attachment:confluence
**Delete**
delete:page:confluence
delete:attachment:confluence
**Find a good headline**
verifyConfluenceAPIAccess does fail on scoped API token usage
Contributor guide
Research direction
Start in ConfluenceClient.groovy and reproduce the failure with the scoped-token endpoint https://api.atlassian.com/ex/confluence//. Trace how the URL context is determined, then verify that verifyConfluenceAPIAccess and publishToConfluence work with the documented endpoint and scoped permissions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- groovy
- Domain
- api, documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100