Client certificate verification (mTLS) in Starlette/FastAPI

[kaleming]

I have found two discussions about this topic, but no solution using Fastapi was proposed:

• Issue How to authenticate requests with SSL client certificates #1029
• Stackoverflow

According to Starlette documentation, no certificate verification is natively implemented in Starlette.

This approach using flask to deal with certificate verification works fine.

It would be very cool if Fastapi support certificate verification.

[Mause]

If you run fastapi with gunicorn with uvicorn workers, the instructions at the bottom of the article you linked will probably fill your need?

[kaleming]

If you run fastapi with gunicorn with uvicorn workers, the instructions at the bottom of the article you linked will probably fill your need?

Hi @Mause, I will give a try using this approach at the bottom to see if it works fine.

[cryptoroo]

@kaleming -- this is an interesting one.

https://www.uvicorn.org/settings/ indicates this is in fact supported however the verification mode will be against the chain rather than more flexibility.

Looking at the code this is to do with the fact that the Python SSLContext object is not actually exposed (i.e. you can't get the peer (client)) certificate natively.

For example if you had access to the actual client certificate you could choose a verification strategy. That is the motivation for using L7 (nginx,trafik etc) tools that can put the certificate in the header.

Saying that this is how I would go about this

A) You will actually need need two CAs

• one for creating the Secure SSL channel (think of things like let's encrypt)
• one for verifying incoming certificates

B) You will need to choose a Verification mode

• I believe this is related to this flag in uvicorn --ssl-cert-reqs - Whether client certificate is required (see stdlib ssl module's)
• https://docs.python.org/3/library/ssl.html#ssl.CERT_NONE
• I believe valid values are 0-2 https://docs.python.org/3/library/ssl.html#ssl.SSLContext.verify_mode

C) You will Need to provide your verification CA root and leaf certs

-in a PEM format to pass as this parameter --ssl-ca-certs - CA certificates file

D) If you are developing in a local environment then you will also need to map a hostname to an ip.

• Let's say your CA Certificate is for bob.alice.xyz you will need to create a mapping for bob.alice.xyz in your local PC dns so that the CA certificate will be trusted and a secure channel can be established
• Most Client SSL and Browsers won't treat a connection as secure unless the hostname requested and the one on cert match.
• You can disable this behavior for example in postman or HTTP Client libraries.

Long story short this should be doable however I might need to do some more experimentation.

[cryptoroo]

@kaleming -- i have got MTLS working 👍

@tiangolo -- what is the process to contribute documentation.

[ycd]

@cryptoroo You can find the process in here: Development - Contributing: Docs

[kaleming]

Hi @cryptoroo,

That`s very cool.
Thank you very much to go further into this issue.

[cryptoroo]

@kaleming https://ahaw021.medium.com/mutual-tls-mtls-with-fastapi-and-uvicorn-3b9e91bdf5a6 is the detailed steps 👍

I will try doing a PR for both SSL and SSL with mTLS in the next week or so

[navan0]

@cryptoroo any updates on your PR?

[tsaridas]

@kaleming https://ahaw021.medium.com/mutual-tls-mtls-with-fastapi-and-uvicorn-3b9e91bdf5a6 is the detailed steps 👍

I will try doing a PR for both SSL and SSL with mTLS in the next week or so

That all works fine but how do we get the client info to fastapi ? I checked headers but no success.

[cryptoroo]

@tsaridas -- what client information were you after?

@navan0 - should see a PR in the next few days

[tsaridas]

@tsaridas -- what client information were you after?

@navan0 - should see a PR in the next few days

I'm looking for the CN of the client certificate to perform authorisation based on that.

[septatrix]

As far as I know this is currently impossible as the ASGI spec does not provide access to any information on the transport level. The current status can be seen in the corresponding issue in the asgiref repo: django/asgiref#112

[stereobutter]

As far as I understand the ASGI spec extensions may be used to pass additional information from the server to the application. In fact the ASGI spec seems to already specify an TLS extension.

Using the extension would look something like this:

@app.get("/foo")
def foo(request: Request):
    if 'tls' in request.scope.extensions:
        client_name = request.scope.extensions['tls']['client_cert_name']
    ...

I don't fully understand how that relates to django/asgiref#112 but to me it appears that at least for TLS/mTLS all the necessary pieces are specified and ASGI servers and applications are free to implement this?

[tiangolo]

Thanks for the discussion here everyone! ☕

@cryptoroo it's great that you wrote an article! 😎

It seems all this would actually be outside of FastAPI, right? At the server (Uvicorn) level or in users' code, right?