How to represent RESTful attribute level access control?

Question

I've been wracking my brain and googling away for ages without coming up with a satisfactory way of handling this. I want to write a nice fully RESTful service to return resources, but the data you have permission to read (or write) variest per-resource depending on your role. So, for example, a user may be able to see their private phone number on their profile, and so may a site administrator, but another user wouldn't. An anonymous visitor might not be able to see another user's real name, but other users (and the site admin) could do. There are around 4 or 5 access levels and rules about which attributes can be read or written. The writing I'm happy with as the client can PUT changes and the server is not bound to accept them all (or at all), but the reading is my problem.

<user>
 <id>jimbob</id>
 <real-name>Jim Roberts</real-name> <!-- only logged-in users should see this -->
 <phone-number>+1 42424151</phone-number> <!-- only the user and admin users should see this -->
</user>

I want to have a properly cacheable user-profile resource which contains all the public data, but how do I model all the stuff that only certain users can see? I could up to 4 links to extra information, most of which would return Unauthorized errors for most users, with each link holding the extra information related to a role. But that seems very inefficient and also ties the clients into the role concept, when previously all they needed to know about was users. Are there any better ideas?

<user>
 <id>...</id>
 <link rel="more" href="extra-user-profile-data-for-logged-in-users"/>
 <link rel="more" href="extra-user-profile-data-for-senior-users"/>
 <link rel="more" href="extra-user-profile-data-for-admin-users"/>
 <link rel="more" href="extra-user-profile-data-for-superadmin-users"/>
</user>

Please note - I am not struggling with any of

• Authentication
• Resource-level access control
• Implementing access control or authorisation on the server side

I am struggling with

• How to represent resources which in a 'normal' HTML website would appear different to different people, in a truly RESTful way.

This seems like a really common problem that everyone should be having, but I can't find anything on it! Please help!

Answer 1

If you think about it, the User resource that an admin client sees (with all of the fields visible) is exactly the same resource that an anonymous or less-privileged client sees. The URI is identical, but the representation they see is different.

It's similar to having the client request the representation be encoded in JSON instead of XML via the Accept header: the server can agree to honor that request but it doesn't necessarily have to. In your case the server should return a representation appropriate to the client's supplied credentials.

Therefore, an admin might receive the content within a media type of application/vnd.yourcompany.user.full+xml as the body returned by a GET on your User resource, and it will contain all the fields possible.

However an anonymous user might receive the payload encoded as say, application/vnd.yourcompany.user.limited+xml which your documentation would describe clearly as a representation that may or may not contain all the elements from the full version. The client would have to use a flexible decoder or schema that would tolerate certain elements not being present at all.

Alternatively, you could return all the resource's information but use a special field value to indicate that a particular value was redacted:

<user>
 <id>jimbob</id>
 <real-name>--FORBIDDEN--</real-name> 
</user>

You could create a media type for each role, but that would introduce a strong coupling between your security scheme and your representations, and that's probably not desirable. Flexible representation schemes that use either field omission or value redaction would be more maintainable in the long term.

The final decision to make is whether or not to return links to other resources which would not be navigable based on the credentials the client supplied. In my opinion those links should always be returned, even if those credentials would not work. Why? Because the client could theoretically supply other credentials when calling those URIs. Even if they don't, the resulting 401 challenge might lead the client to eventually provide them. But if they never even get the URI, they'd be prevented from ever making that decision.