search

swagger-api / swagger-ui

Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.
https://swagger.io
Apache License 2.0
26.24k stars 8.9k forks source link

OpenAPI 3.1.0 support: mutualTLS support #8020

Open IvanHalim opened 2 years ago

IvanHalim commented 2 years ago

How can we help?

Hi Swagger, Amazon API Gateway released mutual TLS authentication for Amazon API Gateway: https://aws.amazon.com/blogs/compute/introducing-mutual-tls-authentication-for-amazon-api-gateway/

So now we need to provide the .key and .cert file as part of the request:

curl --key my_client.key --cert my_client.pem https://api.yourdomain.com

Does swagger-ui have any support for this?

alexb-uk commented 2 years ago

FYI for anyone else that arrives here after a google search....

MTLS support in Swagger UI is not actually required / appropriate. Instead add your client certificate to your browser and it will automatically be used.

For many browsers this is done by adding the certificate to your operating system cert store. I've done this using Chrome on Windows 11 ✅ by importing the *.pfx file into my Personal user area.

char0n commented 1 year ago

Hi everybody,

NOTE: this is OpenAPI 3.1.0 specific feature

Here is proposed implementation:

Inside the Auth dialog, we can just display the information that the mutualTLS was defined and the only additional field that applies to this type from Security Scheme Object is description.

Reasoning

Chrome, Edge, IE, and Safari are all configured to use client certificates and private keys provided by the OS.

Beginning with version 75, Firefox can be configured to use client certificates and private keys provided by the OS on Windows and macOS. In general, this is now the preferred and simplest method to use client certificates in Firefox.

So all major browsers now uses OS to provide client certificates for them and it's now the recommended way. There nothing we can do with JavaScript inside the browser to manage the certificates for mTLS communication.

There is also a native "TLS client certificate dialog" as described in here: Fetch Standard

It looks like this in latest Edge: image

and this dialog displays all certificates that meet the server’s filtering criteria

this is all native stuff and doesn't concern us; So to implement implement mutualTLS support in SwaggerUI might mean only to somehow indicate that it's defined, but that's about it.

We don't need to provide info how to create/upload certificate to the browser, as that's now managed via OS and every OS does it differently.