When a Swagger macro stores a password in the page

Most Confluence apps that render an OpenAPI or Swagger specification offer to fetch it from a URL, and offer somewhere to put the credentials that URL needs — a username and password, or a repository access token.

In several of them those fields are ordinary macro parameters. Macro parameters are stored in the Confluence page itself. So the credential ends up in the page body, where anyone who can read the page can read it, and where it travels into every page copy, template, export and backup.

This is not a hypothetical. It is the one security problem this category's customers report in their own words:

"the document URL is displayed under the Swagger title including the Git token that allows access to the code in our repos which we do not want."

How to find out whether it affects you

Look at the page, not at the macro. The configuration dialog usually masks the field — that is a display choice and it says nothing about where the value is kept.

• In the page editor, open the macro's configuration and check whether a credential field has a value. If it does, that value is somewhere.
• Ask a person who cannot edit that page whether they can see it. In some apps the value renders in the page.
• Export the page to Word or PDF and search the output.
• Check the vendor's documentation for the words "stored securely", and check whether it says where. An app that keeps credentials outside the page will say so plainly, because it is the thing they built.

What to do if you find one

1. Rotate the credential first. Treat it as disclosed. Everyone who could read that page could read it, and page history keeps old versions.
2. Then remove it from the macro. Removing it without rotating leaves the old value in the page's version history.
3. Replace the private URL with something that does not need a secret. In practice this is either a specification your CI publishes to a location Confluence can already reach, or the document itself attached to the page.

What our app does

Two things, and they are both deliberate constraints rather than features:

We do not accept repository credentials at all. There is no field for a Git token, a username or a password anywhere in the app. That rules out fetching from a private repository — a real limitation, written down on the Limitations page rather than discovered later. The alternatives are attaching the file to the page, pasting it, or pushing it from CI.

Our migration warns you about other apps' credentials. When you scan a space before moving from another OpenAPI app, the dry run flags every macro that is storing a username, password or token — before anything is changed. It detects those fields in order to warn you, and never reads, stores or carries them across. For a site that has had these macros for years, that scan is often the first complete list of where the credentials went.

You do not have to migrate anything to get the list. The dry run writes nothing.

Moving from another OpenAPI app · Documentation · Limitations