[OpenAPI.Next Proposal] Add client certificate to authentication methods

[jimfox]

Use of client certificate for authn is very popular and support is ubiquitous.

[khazelton]

There are a number of client/service interactions where this would be a good choice. In particular this fits when the security requirements can be met by mutual authentication of client and server.

[tobilarscheid]

I vote for this, we have some real world use cases where we would like to use something like this. Also, this feature has already been proposed but than somehow got ignored: #451 (comment)

One thing though that from my point of view requires consideration:
When I talk about "client certificate authentication" I typically mean a client presenting a certificate during the TLS handshake and the server granting or denying access based on that (as in rfc5264#section-7.4.6) This is not part of any HTTP interaction at all, it's actually one OSI-Layer lower.
There is now two points of view that you could take:

• The Extremist:
  OpenAPI is about RESTful APIs, RESTful is HTTP based and happens on Layer 7, let's leave out all this TLS stuff
• The Realist:
  In reality, RESTful APIs should be served over a TLS secured connection. To access a number of RESTful APIs, certificate based authentication on TLS Level is required and it is therefore reasonable for OpenAPI Spec to acknowledge this fact and allow documentation of it in the Spec.

I personally take the realist's view.

Still, it will be somewhat hard to cramp a TLS based client certificate authentication into the existing Security Scheme Object - this one is heavily based on HTTP. Smartest solution I see for now is adding another type and making all the other fields optional for it.
As for the name of this new type I am not really sure what is the standard name for client certificates in the TLS handshake, I have read mTLS (for mutual TLS) in some contexts, but never really in RFCs. Also, the term mutual makes it somewhat confusable with mutual HTTP authentication - a whole different story. I therefore propose to simply name the type tls - the authentication is based on TLS.
Users might then want to use the description to state the requirements for the cert, but this is optional as servers typically send a list of accepted CAs during the handshake (rfc5246#section-7.4.4).

A typical client certificate security definition would therefore then look like this:

{
   "type": "tls",
   "description": "Cert must be signed by evilcorp.com CA"
}

type: tls
description: Cert must be signed by evilcorp.com CA

[cmheazel]

Concur. I have a number of customers who require TLS with client certificates. If we don't add it to OpenAPI I'll have to write an extension. Better to have it as part of the spec.

[MikeRalphson]

@cmheazel thanks for the additional data-point. As per #1466 this request is under consideration for OAS 3.1

[fterpstra]

Within the Dutch public sector we have identified this requirement as well.
b.t.w. @cmheazel nice to see you here as well ;)

[bourgpa]

We also plan to implement a REST API service for EU Customs & Taxations IAM system between European Commision and member states. In that case, it is far more easier for us to use two-way SSL as it is already the case for the SOAP WS already exposed. But for the moment my major problem is the lack of implementation at server-side. I had to switch back to Swager 2.0 api because of that. I hope that a 3.0 implementation will come soon, but I have doubt that the 3.1 will met my dead lines. Do we have an idea when 3.1 specifications will be frozen?

[arnoudquanjer]

@tobilarscheid I support your realist view. The Dutch municipalities are aiming to convert/replace their current monolithic information systems with an API-first software landscape, fulfilling societal demand for automation, transparency and privacy. To facilitate this we are setting up an open source inter-organisational system facilitating federated authentication, secure connecting and protocolling in a large-scale, dynamic API landscape. In this landscape we want to use two-way TLS.

[MikeRalphson]

On the subject of TLS client certificate authentication, as a straw man, would the following be sufficient to indicate that the client MUST provide a TLS certificate?

components:
  securitySchemes:
    clientCert:
      type: clientTLS
      serverSelfSigned: true

The default value of serverSelfSigned would be false. A true value would indicate that the client MUST accept self-signed certificates from the server.

Client-side tools would be free to identify or prompt for the relevant certificate using any means they wish.

[tobilarscheid]

Hi @MikeRalphson, thanks for your input. The solution looks like a good first step to me. However I do not quiet understand the emphasis on serverSelfSigned - why would that be something so important to include it here right away?

[bourgpa]

Hello, I agree. Moreover, self-signed certificates are not used in production environements. If you want to put more information useful for the client side, you could optionally list the CA certificates or URL of CA or eIDAS / alternate LOTL (for European Union) that are trusted for an 2 WAY SSL authentification with this service. But it should only be informative. Pascal

…

On 15 May 2018 at 09:55, tobilarscheid ***@***.***> wrote: Hi @MikeRalphson <https://github.com/MikeRalphson>, thanks for your input. The solution looks like a good first step to me. However I do not quiet understand the emphasis on serverSelfSigned - why would that be something so important to include it here right away? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#1004 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AiSLQN7RoFEVJbRJioNpVCP_r5vMt_-_ks5tyonbgaJpZM4MmFhZ> .