Clarify on claims about security

[odrotbohm]

Would you mind clarifying on this paragraph:

While that concept is appealing, it also has security implications. We always say that security by obscurity is not security, but providing attackers with full discoverability of your API is not necessarily wise.

What are you actually trying to express here? That hypermedia implies less security? That it implies security by obscurity? That discoverability implies less security?

Let me raise the counter question: if not though HATEOAS, how do you communicate security rules about which user is allowed to do what to clients and how is that approach more secure than the HATEOAS based approach?

[dsebastien]

Hello @olivergierke,

Glad to have some feedback around this, I know that it's controversial so let me try to clarify.

I don't imply that hypermedia implies less security or anything like this, so we should probably rewrite that section to be clearer.

What I meant is that discoverability is not necessarily always a good property to have. If people want to rob a bank, they'll most likely be very happy to get full plans of the building. It doesn't mean that they can get in easily or that cameras won't notice them etc, but it helps them.

It's a discussion that we've had with one of our pentesters. At the end of the day having a discoverable API or publishing the full API documentation doesn't expose security risks since the actual security depends on security measures actually in place whether at the infrastructure and/or code levels.

I guess I understand your concern that it might give the wrong idea about HATEOAS itself...

[odrotbohm]

What I meant is that discoverability is not necessarily always a good property to have. If people want to rob a bank, they'll most likely be very happy to get full plans of the building. It doesn't mean that they can get in easily or that cameras won't notice them etc, but it helps them.

In how far does moving that "plan" into the out of band documentation make anything more secure there? Following that train of argument you better don't document anything at all. But that's then the security by obscurity you were originally complaining about.

It sounds like you have the arguments completely flipped around. Which of the two is more secure:

1. A client that relies on the the presence of links and only links to invoke functionality. It doesn't know anything additional about security constraints. It relies on being able to issue requests to links it gets presented. If it's not allowed to consume a resource or manipulate it, it doesn't even see the link to it. It doesn't construct any URIs, it just follows the given ones. Even in the worst case — a client tempering with URIs and trying to invoke requests to those — the server can change those URIs and all non-malicious clients work the same way as they just follow the same links, only the target URIs change.
2. You document all available resources and their security constraints accessible to everyone at some external web page (how else is anyone going to be able to implement e.g. admin functionality?). A malicious client would be able to just abuse the same information, but the server not being able to mitigate an attack (changing behavior to avoid running into the malicious requests without breaking well-behaving clients).

No matter how much I turn things around, the completely opposite of what is (was?) originally stated is true.

[dsebastien]

First off: I do see your point and you are 100% correct. Indeed we have full control over the links generation and we could simply not add links for things that the client does not have access to/shouldn't see/discover.

I'm really glad that you come up with this because it actually makes me see things differently, which is nice. I now feel like we should be adding support for HATEOAS in our APIs as it's not actually an issue.

The good thing is that our current design doesn't prevent us from adding the links in our responses, so it's not very hard to do so..

Still, just for the sake of it, here's how I was considering things up to now:

Consider the following "use case" that we have (which is indeed not the only possible one). I'm developing a REST(ish) API and am exposing it to the Web so that my Web front-end (Angular based) can consume it.

In this case, imagine that the API is only available to serve the Web front-end and is not necessarily exposed so that third parties interact with it.

If I implement HATEOAS or a similar solution for API discoverability then I will, by design, be providing information about the API, and maybe functionality that the Web front-end is not using but is still exposed through the API.

If I don't implement HATEOAS and don't publish API documentation, I'm not exposing that information to the world. This is the distinction that I had in mind for a long time.

I know that there are a million ways to design things and that I could make sure that users of my front-end only have access to what they should and will never see links for features they're not supposed to see/interact with, I could implement microservices, expose only those resources/features that the front-end uses, etc etc etc.

[dsebastien]

I'll adapt the home page to make things clear :)