DEV Community: Scott Brady

OAuth is Not User Authorization

Scott Brady — Fri, 11 Dec 2020 12:02:21 +0000

In the same way that OAuth is not authentication, it also does not tell us what the user is allowed to do or represent that the user can access a protected resource (an API).

Understanding what OAuth is not is just as important as knowing what it is, in order to use it effectively. In this article, I’m going to discuss how OAuth does not include user authorization and why user authorization rules should not live within your OAuth authorization server.

TL;DR: OAuth is not suitable for user authorization. The fact that you have an access token that allows you to act on the user’s behalf does not mean that the user can perform an action.

Client Authorization (Delegation)

OAuth is an authorization protocol, but maybe a better name for it is a delegation protocol. It is a protocol that allows a client application to request permission to access a protected resource (API) on the resource owner’s (the user’s) behalf.

Let’s take a look at the authorization process:

The client application asks the user if they can access a protected resource on their behalf (by redirecting the user to the authorization server’s authorization endpoint, specifying exactly what they would like to access (scopes))
The user identifies themselves to the authorization server (but remember, OAuth is not authentication; you’ll need OpenID Connect to help you with that)
The user authorizes the client application to access the protected resource on their behalf (using the OAuth consent process)
The client application is issued an access token

An access token represents that the client application has been authorized by the user. The protected resource can look at the access token and say, “okay, Alice authorized this application to access these parts of my system on their behalf; I’ll let it through”. However, just because Alice said it was okay does not mean that Alice is authorized to access the protected resource.

Client Authorization vs. User Authorization

Let’s break that down, using a banking system as an example:

Client authorization: can this client application read Alice’s transaction history?
User authorization: can Alice view the balance of account #123? OAuth can handle client authorization by issuing an access token that Alice authorized. OAuth cannot handle user authorization.

Open Banking & FAPI introduce Rich Authorization Requests (RAR), where a client application can ask the user to authorize a specific transaction. But again, this is about the user consenting to the transaction, as opposed to what the user is allowed to do.

User Authorization Rules in your OAuth Authorization Server

Hopefully, it’s now clear that an OAuth access token (or an OpenID Connect identity token for that matter) does not represent the user’s permission to do something. But what about putting user-level authorization rules within your authorization server? After all, you already kind of have that with the user authentication process.

User-level authorization during authentication

This is where I am happy to give some ground. Confirming that the user is authorized to use your system when they authenticate is perfectly acceptable. For example, has the user been disabled by an administrator? Do they still qualify to use your services?

If you decide that the authenticating user is not authorized to use your system, you simply do not let them log in. These kinds of checks can also be performed during token generation or maybe as part of token validation (think of the introspection endpoint).

User-level authorization based on request

What breaks this is when you try and add user-level authorization per client application or protected resource. For instance, is the user permitted to use this scope? Are they permitted to use this client application (while OAuth is not authentication, you may see this check when using OpenID Connect)?

This would make your OAuth authorization process look like this:

The client application asks the user if they can access a protected resource on their behalf
The user identifies themselves to the authorization server
The authorization server decides if the user is authorized to access the client or protected resource
The user authorizes the client application to access the protected resource on their behalf
The client application is issued an access token

Adding another Access-Control List (ACL) to your authorization server can’t be that bad, right? After all, it is an authorization server!

In my opinion, this is brittle and prone to error. You are now back to relying on the fact that tokens were issued to represent that the user and the request have been authorized, which is not something OAuth was designed for and is a dangerous assumption to make.

Just as many attempts to use OAuth to represent user authentication have failed, I’ve seen the same happen with user authorization too many times. The protocols just weren’t designed for it, and it’s just too easy to get wrong, especially when your token issuer is also providing SSO, issuing tokens without user interaction.

You are likely using a framework or out-of-the-box solution as your OAuth authorization server, which will want to follow the OAuth specification and issue a token to the authorized client application. You’ll spend your time fighting the design of OAuth, and if you make a single mistake or misunderstand how your framework of choice works, then the authorization server will kick in and issue the token as the user and client have requested, just like it is meant to.

I know I’m blurring the lines between OAuth and OpenID Connect a little here, but here’s a Stack Overflow question that I think highlights the kind of bizarre scenario you could find yourself in:

“I am looking [for] a way for [my authorization server] to invalidate the submitted token if the user doesn’t have access to the application in a single go, even though the challenged token might be valid if it is submitted by other application which the user has access to”

While you initially wanted to have all of your user authorization rules live within your central OAuth authorization server, you will likely end up duplicating these checks into your client applications and APIs to solve these kinds of problems. You are probably going to code yourself into a corner.

User Permissions in your OAuth Authorization Server

This is where most of my customers end up after understanding that user-level authorization is not part of the OAuth protocol and that it is not an easy fit within their OAuth authorization server. But the desire to write all of their authorization logic and user permissions in a single place still exists, which is understandable, especially when they have already achieved that with authentication and API access by using an SSO solution that implements both OAuth and OpenID Connect.

So, what is the solution? Role-Based Access Control (RBAC)? Stuff tokens full of user permissions?

Well, that is a story for another day and well outside of this OAuth story. I recommend checking out Dom’s excellent article on how identity and permissions don’t mix within an SSO solution. For solutions, take a look at how authorization languages are evolving with ALFA and how you can create authorization policies in a single place that are readable by non-developers.

The Random Stuff

This article would not be complete without collating some of the weird and wonderful loaded questions I have received on Stack Overflow or my blog. These are often followed by a “gotcha” or a “checkmate”, or sometimes even a personal insult. But I’ll let your imagination come up with those.

“Then why is it called an authorization code?”

The authorization code represents the user authorizing the client application on their behalf. Again, that is client authorization, not permission to add user authorization.

“Then why do people return 401 Unauthorized when you don’t have a token?”

Naming is hard. In this use case, it would be nice to have named this status code “Unauthenticated”, but at least RFC 7235 requires that you include a WWW-Authenticate header alongside this status code.

“Then why is it called the Authorization header?”

Again, naming is hard. Basic Authentication also uses the Authorization header, but that doesn’t mean the user has full access or is even allowed to use the application. You still have to check if the user is allowed to perform an action.

“Then what are scopes for?”

Scopes represent a level of access that a client application is asking for from the user. For instance, a scope called “email.read” might mean “can I read your emails?”, or “email.send” might mean “can I send emails on your behalf?”. Check out Auth0’s article on the nature of OAuth scopes.

This is a fairly common mistake to make when starting out with OAuth, so I’ll forgive you for this one.

“I still don’t believe you! Everyone does this!”

Well, that’s just, like, your opinion, man. But it isn’t OAuth.

JWTs: Which Signing Algorithm Should I Use?

Scott Brady — Tue, 25 Aug 2020 07:44:47 +0000

JSON Web Tokens (JWTs) can be signed using many different algorithms: RS256, PS512, ES384, HS1; you can see why some developers scratch their heads when asked which one they would like to use.

In my experience, many of the mainstream identity providers have historically only offered RS256 or at least defaulted to it. However, thanks to initiatives such as Open Banking, these identity providers are now expanding their support to cover more signing algorithms, which means you will need to start understanding which ones to use.

I am not a cryptographer, but through my work with OpenID Connect and FIDO2, I have gained a practitioner’s understanding of the various signing algorithms and the cryptography communities’ general feelings towards each one. In this article, I’m going to arm you with some of that knowledge so that you can understand what each “alg” value means and choose the best signing algorithm available to you.

TL;DR: EdDSA > ECDSA or RSASSA-PSS > RSASSA-PKCS1-v1_5 and know what to expect.

Algorithm (alg) Values

Before we look at each family of signature algorithms, let’s first clarify what we mean by “alg” values such as RS256. These are JSON Web Algorithms (JWA), which are part of the JavaScript Object Signing and Encryption (JOSE) family. You’ll see “alg” values in JWT headers, telling you how the JWT was signed, and in JSON Web Keys (JWK), telling you what algorithm a key is used for.

As a general rule of thumb, an “alg” value, such as RS256, can be broken down as: RS (signature algorithm) 256 (hashing algorithm).

Signature algorithm family: In this case, RS means RSASSA-PKCS1-v1_5.
Hashing algorithm used by the signature algorithm. In this case, 256 means SHA-256.

Most signing algorithms have variants for SHA-256, SHA-384, and SHA-512. In some cases, you can even have something like “RS1”, which uses SHA-1 🤢 and is required for FIDO2 conformance.

These algorithms are typically defined in RFC 7518, but you can find a full list of supported algorithms in the JOSE IANA registry.

Which Hashing Algorithm Should I Use?

SHA-256, SHA-384, and SHA-512 are all variations of the same hashing algorithm family: SHA-2.

As a rule of thumb, the number in an algorithm refers to the size of the hash it will generate. For example, SHA-256 will produce a 256-bit hash, while SHA-512 will produce a 512-bit hash.

The level of security each one gives you is 50% of their output size, so SHA-256 will provide you with 128-bits of security, and SHA-512 will provide you with 256-bits of security. This means that an attacker will have to generate 2^128 hashes before they start finding collisions, thanks to the birthday bound. This is why we use a minimum of 128-bit security.

You’re not going to be needing anything better than SHA-256 any time soon. Just don’t use SHA-1.

Validation: Know your Algorithm

Every application validating JWT signatures should know ahead of time which algorithms to expect and exactly which key to use. You can do this by assigning each public key to an algorithm (e.g. this key is for RS384, this one for ES256). When you have many keys for a single algorithm, you can use the key ID (kid) in a JWT header to understand which one to use.

Basically, you want to make sure the kid and alg values in a JWT match what you expect. If they do not match, then someone is up to no good.

{
    "typ": "JWT",
    "kid": "123", // is this key...
    "alg": "RS256" // ...allowed to be used for this algorithm?
}

Protocols such as OpenID Connect facilitate this using a discovery document and a JSON Web Key Set (JWKS) available on an endpoint protected by TLS.

These days, you should not trust the “alg” value in the JWT header alone, nor should you accept JWTs with an algorithm of “none” or JWTs with a public key embedded in its header.

RSASSA-PKCS1-v1_5 (e.g. RS256)

RS256 = RSASSA-PKCS1-v1_5 using SHA-256

While RSAES-PKCS1-v1_5 is no longer safe for encryption, RSASSA-PKCS1-v1_5 is still suitable for digital signatures. As I mentioned earlier, in my experience, RS256 has historically been the default for most JWT implementations, with many SaaS identity providers only offering this signature algorithm. It’s hard to find a system that can’t support JWTs signed with RS256.

JWTs signed with RSASSA-PKCS1-v1_5 have a deterministic signature, meaning that the same JWT header & payload will always generate the same signature.

RSASSA-PKCS1-v1_5 has been around for a long time, but these days, you should generally prefer RSASSA-PSS (RSA with a probabilistic signature). That’s not to say RSASSA-PKCS1-v1_5 is broken but rather that RSASSA-PSS simply has desirable features that the other does not. In fact, RFC 8017 now considers RSASSA-PSS a requirement when using RSA for signing:

Although no attacks are known against RSASSA-PKCS1-v1_5, in the interest of increased robustness, RSASSA-PSS is REQUIRED in new applications. - RFC 8017

That being said, when discussing Bleichenbacher’s attacks against the RSA PKCS#1 encryption and signature standards, David Wong in Real-Word Cryptography shares an interesting statistic:

Unlike the first attack that broke the encryption algorithm completely, the second attack is an implementation attack [against signature validation]. This means that if the signature scheme is implemented correctly (according to the specification), the attack does not work.

Yet, it was shown in 2019 that many open source implementations of RSA PKCS#1 v1.5 for signatures actually fell for that trap and mis-implemented the standard, which enabled different variants of Bleichenbacher’s forgery attack to work! - Real-World Cryptography

Since the attacks are against signature validation, you will have to be confident that all recipients who validate your JWTs are using a library that is not vulnerable to Bleichenbacher’s attack. That would be difficult if you are dealing with many 3rd parties.

The work around Open Banking, such as OpenID’s Financial-grade API (FAPI), does not allow the use of RSASSA-PKCS1-v1_5. For my regular readers, this was the only algorithm available in IdentityServer up until IdentityServer4 version 3.

RSASSA-PSS (e.g. PS256)

PS256 = RSASSA-PSS using SHA-256 with MGF1 with SHA-256

RSASSA-PSS is the probabilistic version of RSA, where the same JWT header and payload will generate a different signature each time. Unlike other algorithms, this is probabilistic in a good way; while a random value may be used during signature generation, it is not critical to security. In general, it’s a lot simpler to implement and therefore harder to get wrong.

If you want to use an RSA key, then it’s recommended that you use RSASSA-PSS over RSASSA-PKCS1-v1_5, but luckily an RSA key can be used for either signature scheme. Signature length is also identical between the two.

The UK’s Open Banking initially mandated the use of PS256, but later opened it up to ES256.

ECDSA (e.g. ES256)

ES256 = ECDSA using P-256 and SHA-256

In the case of Elliptical Curve Digital Signing Algorithms (ECDSA), the number in ES256 that refers to the hashing algorithm also relates to the curve. ES256 uses P-256 (secp256r1, aka prime256v1), ES384 uses P-384 (secp384r1), and, the odd one out, ES512 uses P-521 (secp521r1). Yes, 521. Yes, even Microsoft has typoed this.

Elliptical Curve Cryptography (ECC) is much harder to crack than RSA (or maybe we are just really good at breaking RSA). As a result, ECDSA can use much shorter keys than RSA along with much shorter signatures. A short Elliptical Curve (EC) key of around 256 bits provides the same security as a 3072 bit RSA key.

You will often see ECDSA listed as faster than its equivalent in RSA, but this is only really true for signature generation; signature validation is still typically faster with RSA. With JWTs, you’re most likely going to be signing once and verifying many times.

JWTs signed with ECDSA have a probabilistic signature, meaning that the same JWT header & payload will always generate a different signature. But unfortunately, ECDSA is probabilistic in a bad way, where random generation is vital to the security of the signature.

ECDSA uses a random nonce (no more than once) that is generated per signature. Failure to only ever use a nonce value once makes the private key easily recoverable, and this has been seen in the wild with both Sony’s Playstation 3 and Bitcoin. With the Playstation 3, the private key was recovered due to a static nonce, and with Bitcoin, Android users were affected due to a bug in Java’s SecureRandom class on Android. If random values are required for the security of a probabilistic signature, then you should prefer a deterministic signature that does not.

Whereas RSASSA-PKCS1-v1_5 has issues with signature validation, ECDSA has issues with signature generation, which is much easier to deal with when you are the token issuer.

ECDSA is gaining popularity but seems to generally be frowned upon by cryptographers due to how elliptical curve cryptography was implemented, with concerns around implementation difficulty due to the use of random values. It has a better reputation than RSA, but cryptographers are still advocating the migration to EdDSA.

The curves JOSE initially used where defined by NIST. If you are concerned about using curves defined by NIST but want to use ECDSA, a popular alternative is to use a Koblitz curve, such as secp256k1 (as opposed to secp256r1). Kobiltz curves are a few bits weaker, but if you have concerns that the unexplained random numbers used in the NIST curves indicate another NSA backdoor, then Kobiltz curves offer an increasingly popular alternative. You can find usages on these curves in Bitcoin, Ethereum, and FIDO2. However, you should be using EdDSA if you want to use a non-NIST curve. In JOSE, algorithms using Kobiltz end with a K, e.g. ES256K.

EdDSA

EdDSA = an EdDSA signature algorithm was used 🤷‍♂️

EdDSA bucks the trend of the previous algorithms and uses a single alg value. Instead, it relies upon the curve (crv) defined in a pre-agreed key.

For example, a JWK containing an EdDSA public key would look like the following:

{
  "kty": "OKP",
  "alg": "EdDSA",
  "crv": "Ed25519",
  "x": "60mR98SQlHUSeLeIu7TeJBTLRG10qlcDLU4AJjQdqMQ"
}

This forces the modern behavior of using the curve assigned to the key, as opposed to from the JWT, and eliminates various alg related attacks.

EdDSA is a form of elliptical curve cryptography that takes advantage of twisted Edwards curves. It is a variant of Schnorr’s signature system (rather than DSA). EdDSA is fast at both signing and validation, has a short signature, and side-steps whole classes of security vulnerabilities.

RFC 8037 defines JOSE support for the following EdDSA variants:

Ed25519: a 255-bit curve Curve25519 (32-byte private key, 32-byte public key, 64-byte signature). Signing uses SHA-512. Provides 128-bit security
Ed448: a 448-bit curve Curve448-Goldilocks (57-byte private key, 57-byte public key, 114-byte signature). Signing uses SHAKE256. Provides 224-bit security JWTs signed with EdDSA have a deterministic signature, meaning that the same JWT header & payload will always generate the same signature. This is deterministic in a good way, addressing the concern of relying on random nonce values to protect the private key. EdDSA only uses random values during private key creation. This is the algorithm that critics of JOSE & JWTs recommend.

Support for EdDSA in JWT libraries is a little patchy, but expect to see more of EdDSA soon.

HMAC (e.g. HS256)

HS256 = HMAC using SHA-256

Up until now, we’ve been talking about asymmetric cryptography, where only the token issuer has the private key to create the signature, and everyone else has the corresponding public key that can be used to validate the signature. For example, the identity provider has the private key and relying parties use a public key.

In the rare event that you will be the only person who issues and validates tokens, then you could consider using symmetric cryptography with something like HS256. This uses the same key to both create and validate a signature.

In my opinion, if you find yourself in this position, then I don’t think JWTs are the right solution for you. If the same entity is both reading and writing, then what is the requirement for round-tripping structured, plaintext data in a JWT? I would recommend storing the data in a database and passsing around a reference or to use something like a Branca token or JSON Web Encryption (JWE) to ensure only you can read the data.

Generally, using HMAC for JWT signing is seen as something of an anti-pattern.

None

none = base64 encrypted

Sorry, I couldn't resist. Please don’t use this.

Recommendations

Use EdDSA where possible and use ECDSA when it is not. If you are forced to use RSA, prefer RSASSA-PSS over RSASSA-PKCS1-v1_5.

I don’t think it’s a controversial statement to say that RSA is slowly on its way out. At the moment, offering ECDSA is a good alternative, but ideally, you’ll be wanting to move to EdDSA where possible.

But, no matter which algorithm you use, make sure you know ahead of time which algorithm to expect and which key to use for validation.

A huge thank you to Neil Madden for the technical review of this blog post.

Creating Elliptical Curve Keys using OpenSSL

Scott Brady — Mon, 20 Jul 2020 17:22:48 +0000

Recently, I have been using OpenSSL to generate private keys and X509 certificates for Elliptical Curve Cryptography (ECC) and then using them in ASP.NET Core for token signing.

In this article, I’m going to show you how to use OpenSSL to generate private and public keys on the curve of your choice.

tl;dr - OpenSSL ECDSA Cheat Sheet

# find your curve
openssl ecparam -list_curves

# generate a private key for a curve
openssl ecparam -name prime256v1 -genkey -noout -out private-key.pem

# generate corresponding public key
openssl ec -in private-key.pem -pubout -out public-key.pem

# optional: create a self-signed certificate
openssl req -new -x509 -key private-key.pem -out cert.pem -days 360

# optional: convert pem to pfx
cat private-key.pem cert.pem > cert-with-private-key
openssl pkcs12 -export -inkey private-key.pem -in cert-with-private-key -out cert.pfx

Generating an Elliptical Curve Private Key Using OpenSSL

To start, you will need to choose the curve you will be working with. You can use the following command to see a list of supported curve names and descriptions.

openssl ecparam -list_curves

In this example, I am using prime256v1 (secp256r1), which is suitable for JWT signing; this is the curve used for JOSE’s ES256.

You can now generate a private key:

openssl ecparam -name prime256v1 -genkey -noout -out private-key.pem

This should give you a PEM file containing your EC private key, which looks something like the following:

----------BEGIN EC PRIVATE KEY-----
MHcCAQEEIKEubpBiHkZQYlORbCy8gGTz8tzrWsjBJA6GfFCrQ98coAoGCCqGSM49
AwEHoUQDQgAEOr6rMmRRNKuZuwws/hWwFTM6ECEEaJGGARCJUO4UfoURl8b4JThG
t8VDFKeR2i+ZxE+xh/wTBaJ/zvtSqZiNnQ==
----------END EC PRIVATE KEY-----

Creating an EC Public Key from a Private Key Using OpenSSL

Now that you have your private key, you can use it to generate another PEM, containing only your public key.

openssl ec -in private-key.pem -pubout -out public-key.pem

This should give you another PEM file, containing the public key:

----------BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEOr6rMmRRNKuZuwws/hWwFTM6ECEE
aJGGARCJUO4UfoURl8b4JThGt8VDFKeR2i+ZxE+xh/wTBaJ/zvtSqZiNnQ==
----------END PUBLIC KEY-----

Creating an EC Self-Signed Certificate Using OpenSSL

Now that you have a private key, you could use it to generate a self-signed certificate. This is not required, but it allows you to use the key for server/client authentication, or gain X509 specific functionality in technologies such as JWTs and SAML.

openssl req -new -x509 -key private-key.pem -out cert.pem -days 360

This will again generate another PEM file, this time containing the certificate created by your private key:

----------BEGIN CERTIFICATE-----
MIIB4DCCAYWgAwIBAgIUH53ssiPt4JEGx+VJyntCpHL+TdAwCgYIKoZIzj0EAwIw
RTELMAkGA1UEBhMCQVUxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoMGElu
dGVybmV0IFdpZGdpdHMgUHR5IEx0ZDAeFw0yMDA3MTgxMTE4NDNaFw0yMTA3MTMx
MTE4NDNaMEUxCzAJBgNVBAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEwHwYD
VQQKDBhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQwWTATBgcqhkjOPQIBBggqhkjO
PQMBBwNCAAQ6vqsyZFE0q5m7DCz+FbAVMzoQIQRokYYBEIlQ7hR+hRGXxvglOEa3
xUMUp5HaL5nET7GH/BMFon/O+1KpmI2do1MwUTAdBgNVHQ4EFgQU9yjFBqAZOMv+
cD6a3KHTWuYrcFEwHwYDVR0jBBgwFoAU9yjFBqAZOMv+cD6a3KHTWuYrcFEwDwYD
VR0TAQH/BAUwAwEB/zAKBggqhkjOPQQDAgNJADBGAiEAwCpA5Nx083qqUqU6LUd0
vzZLK4etuInxNvXohXH5LiACIQDSI63J4DiN3dq2sPPLw5iQi9MMefcV1iAySbKT
B9BaAw==
----------END CERTIFICATE-----

You could leave things there, but if you are working on Windows, you may prefer a PFX file that contains both the certificate and the private key for you to export and use.

You can do this by first concatenating your private key and certificate into a single file:

cat private-key.pem cert.pem > cert-with-private-key

And then using OpenSSL to create a PFX file:

openssl pkcs12 -export -inkey private-key.pem -in cert-with-private-key -out cert.pfx

OpenSSL will ask you to create a password for the PFX file. Feel free to leave this blank.

This should leave you with a certificate that Windows both install and export the private key from.

DEV Community: Scott Brady

OAuth is Not User Authorization

Client Authorization (Delegation)

Client Authorization vs. User Authorization

User Authorization Rules in your OAuth Authorization Server

User-level authorization during authentication

User-level authorization based on request

User Permissions in your OAuth Authorization Server

The Random Stuff

“Then why is it called an authorization code?”

“Then why do people return 401 Unauthorized when you don’t have a token?”

“Then why is it called the Authorization header?”

“Then what are scopes for?”

“I still don’t believe you! Everyone does this!”

JWTs: Which Signing Algorithm Should I Use?

Algorithm (alg) Values

Which Hashing Algorithm Should I Use?

Validation: Know your Algorithm

RSASSA-PKCS1-v1_5 (e.g. RS256)

Further Reading

RSASSA-PSS (e.g. PS256)

Further Reading

ECDSA (e.g. ES256)

Further Reading

EdDSA

Further Reading

HMAC (e.g. HS256)

Further Reading

None

Recommendations

Creating Elliptical Curve Keys using OpenSSL

tl;dr - OpenSSL ECDSA Cheat Sheet

Generating an Elliptical Curve Private Key Using OpenSSL

Creating an EC Public Key from a Private Key Using OpenSSL

Creating an EC Self-Signed Certificate Using OpenSSL