Signing keys, certificates and client secrets confusion

Question

I am somewhat confused with the difference between certificates and signing keys and have a few questions....

I have OpenIddict configured to use JWT Bearer Authentication.

1) What is the difference between AddDevelopmentSigningCertificate() and AddEphemeralSigningKey()?

My app works when I use one or the other. Does it matter which one to use during development?

2) What is the difference between AddSigningCertificate() and AddSigningKey() and when would you use one or the other or both?

From what I understand, the signing certificate is used to sign the JWT token. But when you use AddSigningKey - that is also used to sign the JWT token. If you use both, does this mean that the JWT token gets signed twice - one on top of the other? Or does one override the other?

In my scenario I am using either AddDevelopmentCertificate() or AddEphemeralSigningKey() for development but for production I understand that I need to set up a signed certificate that ideally should be located in the machine store.

But I also require a unique signing key that is shared with my API endpoint (in .NET Framework 4.x) that uses JWT Bearer Authentication.

I would like to know what these functions are doing to the JWT token and how they work with each other.

Last question: When setting up the OpenIddict tables, and seeding the database with the Client app, there is a Client Secret that is populated. In the Samples project these are always GUIDs.

3) Is the client secret used when using JWT Bearer authentication? And how does this play along with the signing certificate and signing key?

I really want to understand how this stuff all works but am getting a bit lost in the signing key/certificate wilderness!

Thanks

Answer 1

What is the difference between AddDevelopmentSigningCertificate() and AddEphemeralSigningKey()?

AddDevelopmentSigningCertificate will try to generate a self-signed X.509 certificate (containing a RSA key) and store it in the user's certificate store so it can be re-used even after you restart your application.

AddEphemeralSigningKey will simply generate a RSA signing key but won't persist it anywhere. It will be lost once you restart your application.

Both methods serve exactly the same purpose: creating a signing key used to protect your tokens.

---

What is the difference between AddSigningCertificate() and AddSigningKey() and when would you use one or the other or both?

The only difference is that AddSigningCertificate() accepts a X509Certificate2 parameter while AddSigningKey() takes a SecurityKey instance. Ultimately, AddSigningCertificate() takes care of resolving the RSA or ECDSA key from the certificate and calls AddSigningKey().

---

But when you use AddSigningKey - that is also used to sign the JWT token. If you use both, does this mean that the JWT token gets signed twice - one on top of the other? Or does one override the other?

When you register multiple asymmetric signing keys, OpenIddict only uses the first one to sign tokens. The other ones are only exposed by the discovery endpoint so you can later decide to make them the "primary keys" without breaking your clients.

---

I understand that I need to set up a signed certificate that ideally should be located in the machine store.

Yes. If you don't have access to the machine or user store (the recommended option), you can alternatively store it in an embedded assembly file.

---

But I also require a unique signing key that is shared with my API endpoint (in .NET Framework 4.x) that uses JWT Bearer Authentication.

That's what AddSigningCertificate() and AddSigningKey() are for. The recommendation is to use an asymmetric signing key (i.e a certificate or a RsaSecurityKey/EcdsaSecurityKey instance).

If you prefer using a symmetric key to HMAC your JWT tokens, use AddSigningKey(new SymmetricSecurityKey([bytes])).

If your authorization server issues identity tokens, you'll need at least one asymmetric key (certificate or raw RSA/ECDSA key) but the symmetric key will be preferred for the JWT access tokens.

---

Is the client secret used when using JWT Bearer authentication? And how does this play along with the signing certificate and signing key?

The client secret is only used when communicating with the token or revocation endpoints, not when you use your own API endpoints. For more information, read https://www.rfc-editor.org/rfc/rfc6749#section-2.3