8

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

Pacificoder
  • 1,581
  • 4
  • 18
  • 32

1 Answers1

12

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

Community
  • 1
  • 1
Kévin Chalet
  • 39,509
  • 7
  • 121
  • 131
  • Thanks for that detailed explanation - very enlightening and helps me make sense of the pieces. You mention that "If your authorization server issues identity tokens, you'll need at least one asymmetric key (certificate or raw RSA/ECDSA key). My endpoint does issue tokens and I have created a certificate that is embedded in my assembly using the AddSigningCertificate method. Now when configuring the signing key for a different API endpoint using JWT Bearer auth, how do I get this RSASecurityKey? Do I explicitly have to load the certificate here and extract the key? – Pacificoder Jun 19 '18 at 21:50
  • 1
    I have seen examples using symmetricSecurityKey where a value is given for the IssuerSigningKey property, for example: IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("06d5bc80-17a6-4add-9458-506547d66d6b") , but if I want to use that assymetric RSA signing key from my Auth server also for my other API. I have not seen any clear examples of doing this with the RSASecurityKey. Is there an equivalent way to do this when using an RSASecurityKey without explicitly loading the certificate again and extracting the key? I would like to "re-use" the same RSA key for my API – Pacificoder Jun 19 '18 at 22:08
  • Update: I've modified my code to just use the machine store like in production. And am able to load the certificate from there to get the signing key. All good now :) – Pacificoder Jun 20 '18 at 17:27
  • @Pinpoint When using AddDevelopmentSigningCertificate(), how do I get the signing key to use as token validation parameter? – Palmi Jan 23 '19 at 03:57
  • @Palmi you can either set the `Authority` in the JWT options (so the JWT handler can automatically download the metadata document using HTTP) or do something like that: https://github.com/openiddict/openiddict-core/issues/688#issuecomment-442485170 – Kévin Chalet Jan 23 '19 at 14:04
  • @Pinpoint Thank you for your prompt response. I tried to use your suggestion to use Authority but I ran into an error. I opened another question for this issue (https://stackoverflow.com/questions/54333631/openiddict-using-adddevelopmentsigningcertificate). I would appreciate your input when you have time. Thanks – Palmi Jan 23 '19 at 18:38
  • @KévinChalet, sorry, one more question to the topic. How all these keys are related to the .net core DataProtection key specified by `services.AddDataProtection().Persist...()`? – Andrew May 06 '20 at 23:58
  • @Andrew those keys are completely separate: Data Protection maintains its own set of master keys, that are completely unrelated to the IdentityModel signing keys used by OpenIddict. – Kévin Chalet May 08 '20 at 13:36
  • I was going to create a new question and it lead me here. Was wondering in net core hosted on Linux can I get away with signingkeys rather than certs? – AliK May 01 '21 at 08:28