Secure Swagger Configuration

[MH61Aus]

We've implemented swaggerui for a couple of APIs, and secured it following the blog post here: https://duendesoftware.com/blog/20251126-securing-openapi-and-swagger-ui-with-oauth-in-dotnet-10

We've allowed swagger on our production environment, since it allows easy interaction with endpoints that we haven't built UI for. We felt this wasn't an issue since only a few internal users that have an admin role are able to load the swagger UI.

however, we're looking at FAPI conformance since we work in healthcare, and the swagger client failed on PAR and other checks. when digging into the swagger and open API docs, I see that microsoft and swagger both say that swagger is intended for DEV environments only.

When I worketh though securing swagger, the Dunde blog post didn't give me the impression that it was intended for DEV only. the samples don't guard AddOpenApi() with an environment check.

Does Duende also advise against putitng the swagger ui on production? if so, the blog post should make that explicit.

[khalidabuhakmeh]

👋🏼 Hello @MH61Aus,

First of all, thanks for reading the post. Always appreciated.

The short answer to your question of "Does Duende also advise against putitng the swagger ui on production?" is it depends.

OpenAPI and the Swagger UI element are dev-focused tools, and it depends on what you and your organization are trying to do. We don't make any recommendations for production/staging/dev environments because we don't know what you're trying to accomplish with them.

Let's walk through a couple of scenarios in which you may or may not want to deploy these elements across different environments:

Development

If you are implementing OpenAPI schema and Swagger to enable your local development team to build C# SDKs that ultimately only apply during the development process, then you likely wouldn't deploy the OpenAPI schema or Swagger UI outside of development. You can build these C# SDKs locally and use the libraries during development.

Dev & Staging

If you are creating a business partnership with an outside party, you may only publish the OpenAPI schema and allow them to generate their own client, and use their own UI tools to exercise the endpoints. Security and identity are still important, but you don't need to provide the Swagger UI in this case (and thus don't need to secure it).

Dev, Staging, & Production

If you are building a business where the API is the product, you will want to deploy both the schema and the UI to create an enjoyable developer experience that enables potential customers to try the API as frictionlessly as possible. In this case, you would deploy (and secure) these in a production environment. In this case, the schema and UI would be present and accessible throughout your CI/CD process, from dev, staging, and production.

Conclusion

The answer is, it depends on what you're attempting to accomplish and what your team's goals are. I hope that clarifies why we didn't make a recommendation and instead wrote about how to address the security aspect of hosting a Swagger UI instance. While these tools are developer-focused, empowering developers to build faster and better apps, they do not specify which environment they are best suited for; that's a question you have to answer.

Cheers,

Khalid

[MH61Aus]

Thanks for the response @khalidabuhakmeh.

This does clear a few things up for me - and makes me lean towards pulling it off of production since we're only using it for internal operational use, and we should probably focus our time on building some admin screens for these scenarios.

The remining thing I'm curious about though is whether its possible to enforce PAR via swagger UI. If we're trying to achieve FAPI compliance, I imagine this failing on conformance report will be further justification to pull it off production.

[khalidabuhakmeh]

Swagger UI doesn't support PAR. It handles OAuth entirely in the browser: redirects, token acquisition, everything client-side.

PAR requires a back-channel POST to the authorization server's PAR endpoint before the front-channel redirect, but Swagger UI has no mechanism to do so.

So if you enforce RequirePushedAuthorization = true on the client Swagger uses, the flow will just fail. Same story with the other FAPI requirements: sender-constrained tokens (DPoP/mTLS) and confidential client authentication aren't possible from a browser-based public client.

If you still need API exploration tooling:

1. Separate non-FAPI client for Swagger: Dedicated client without PAR requirements, restricted to non-production. Most common approach, but obviously doesn't prove FAPI compliance.
2. Swagger behind Duende BFF: The BFF handles the OIDC flow (including PAR) server-side, Swagger calls APIs through the BFF proxy. More complex, but tokens stay out of the browser.
3. Ditch Swagger for a non-browser tool: Postman, Bruno, or custom CLI tools can implement PAR since they can act as confidential clients with back-channel access.

So yes, this is further justification for pulling the Swagger UI out of production. In an FAPI-compliant deployment, Swagger UI can't participate in the required security flows. For internal operational use, a purpose-built admin UI behind a BFF, or something like Postman configured as a confidential client, would be the way to go.

If you were to productize your API, my personal recommendation is (2) to implement an API/Documentation tool behind BFF. Get a great team of backend, front-end, and design together and make it look really nice.

Links:

• Swagger UI OAuth 2.0 config: https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/
• Duende PAR: https://docs.duendesoftware.com/identityserver/tokens/par/
• Duende FAPI: https://docs.duendesoftware.com/identityserver/tokens/fapi-2-0-specification/
• Duende BFF: https://docs.duendesoftware.com/bff/

[khalidabuhakmeh]

OK, @MH61Aus, you nerd-sniped me! I hope you're proud of yourself (of course I'm kidding 🤣).

It took a little bit of work, but it's actually a pretty nice solution for Swagger working with Duende BFF Security Framework. At no point does the token make it to the browser, but we can still call the APIs with the token. There was some modification of Swagger, but it works nicely (check out the video below).

Again, you may be right about removing Swagger, but this is an option for other community members looking for options. Cheers :)

CleanShot.2026-07-20.at.13.52.25.mp4

[khalidabuhakmeh]

I think I remember why I believed this was a good option. Because @Erwinvandervalk and I wrote a blog post about it already. https://duendesoftware.com/blog/20250430-managing-openapi-specifications-with-backend-for-frontend-and-swagger-ui

[MH61Aus]

@khalidabuhakmeh - thanks for all of this. Setting up a BFF for the swagger UI is a little out of scope for now, but I'll be bookmarking this for whenever I get a quiet day, as i'd love to give it a go.

you mentioned Postman allows PAR - I tried to get that working as we do already have a Postmen client defined, but I can't figure it out.

[khalidabuhakmeh]

Hey! I think there may have been a small miscommunication. I didn't mean to imply that Postman itself supports PAR. Unfortunately, Postman doesn't have built-in support for Pushed Authorization Requests, since PAR requires the client to first POST the authorization parameters directly to the server's PAR endpoint and then redirect with the resulting request_uri. That's not something Postman's OAuth 2.0 flow can do out of the box.

What I was suggesting is that you could define a separate client in IdentityServer specifically for Postman. One that doesn't require PAR. That way, Postman can still use a standard authorization code flow for day-to-day testing and development, while your actual application clients continue to enforce PAR as part of your compliance requirements. The Postman client wouldn't need to be part of that compliance exercise; it's just a developer tool.

So in short: PAR needs a server-side application with an accessible address that can make backchannel requests to the PAR endpoint. Postman can't fill that role. But you can absolutely keep using Postman with a non-PAR client alongside your PAR-enforcing clients.

Cheers :)

[MH61Aus]

@khalidabuhakmeh - thanks for clarifying. Circling back though, we already have swagger set up as a separate client. so in our conformance report, the web client passes the FAPI checks for PAR, etc, whereas the swagger and postman client fail.