API seamless security

[Xavier Dury]

Hi,

I've been working with Hypermedia APIs recently (mostly with HAL) and what I like the most with that kind of APIs is the discoverability aspect: with only the root URL of the API, it is possible to navigate through resources by following links (with something like the HAL Browser/Navigator) without any prior knowledge.

Now, with HAL-Forms, it's even possible to declare the parameters/json-payload that must be sent with POST/PUT and generate forms dynamically on the client.

But there is still one aspect of APIs which seems to require out-of-band information: security. Once you have secured resources which require specific authorization tokens, discoverability stops.

I haven't (yet) found any *standard* way for the resource server to give the client the required information about what kind of authorization tokens it needs nor how to acquire one.

In contrast, for a standard server-side rendered app, things are easy: when the user needs to be authenticated, you respond with a WWW-Authenticate: Basic header or redirect the user to some login system and after authentication, a cookie is baked and voilà... but things seem so more complicated with SPAs + APIs.

Does anybody know if some initiatives exist in that matter? I would (naively) think of something in the like of:

>> GET /myApi/myProtectedResource

<< 401 Unauthorized

<< Link: <https://facebook.com/connect>; rel="auth"; title="Facebook"; path="/myApi/myProtectedResource"

<< Link: <https://twitter.com/connect>; rel="auth"; title="Twitter"; path="/myApi/myProtectedResource"

>> GET(OPTIONS?) https://facebook.com/connect

<< 200 OK

<< Content-Type: application/auths+json

<< {

<<   "auths": [

<<     {

<<       "type": "OAuth2",

<<       "flow": "authorization-code",

<<       "href": "...",

<<       ... /* specific parameters needed to initiate an authorization code flow */

<<     },

<<     {

<<       "type": "OAuth2",

<<       "flow": "authorization-code-pkce",

<<       "href": "...",

<<       ... /* specific parameters needed to initiate an authorization code with PKCE flow */

<<     }

<<   ]

<< }

Regards,

Xavier

[Joost Cassee]

Hi Xavier,

I haven't seen anything like that, to be honest. Two things I tend to do:

• Only send links the user has access to.
• Add a link with relation "http://openid.net/specs/connect/1.0/issuer" to the OIDC token issuer. Adding ".well-known/openid-configuration" to that URL should then give you everything you need to get a token.

However, this is all non-standard and does not solve your problem of giving a link and the required information to access it.

Best,

Joost

Op wo 14 jul. 2021 om 11:56 schreef Xavier Dury <xavie...@gmail.com>:

--
You received this message because you are subscribed to the Google Groups "HAL Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hal-discuss...@googlegroups.com.
To view this discussion on the web, visit https://groups.google.com/d/msgid/hal-discuss/138db2a1-00c4-4e91-aa93-037eac2f101cn%40googlegroups.com.

--

Joost Cassee
+31 (0)6 14585693
https://jcassee.com

[m...@evertpot.com]

Not exactly an answer to your question, but here's a random collection of thoughts:

1. Like Joost, we hide links and forms that a user doesn't have access to.
2. link-hints, which is something we use to make HAL links richer, has _some_ support for authentication-related hints. I think this is a good add-on to HAL and we've been using its features whenever we need them (although never used the auth features): https://tools.ietf.org/id/draft-nottingham-link-hint-01.html
3. Typically we only kick-off authentication, after we receive a 401. The `401` response itself (with headers) can also provide information on how to make the request succeed.
4. I've worked on a draft RFC to provide a few standard link relationships specifically pertaining to authentication. Might be useful? https://datatracker.ietf.org/doc/html/draft-pot-authentication-link-01
5. The OAuth2 project itself also has a 'discovery document' with tons of information on what OAuth2 features are available, and this at least duplicates some stuff from your question: https://datatracker.ietf.org/doc/html/rfc8414 Maybe all you need is link to this?

[futy...@gmail.com]

Absolutely agree with only provided related and accessible links. However this doesn’t prevent the response 401 when session expired or killed by admin.

The response resource comes with 401 code should include links for authentication. If your server supports a single authentication schema, the Client should be coded to be able to use it. So one or more links and some fields with additional data should be enough discoverability.

The tricky case where server supports multiple authentication schemas and User can choose one of them. For this case you can (in the same 401 resource) provide embedded list of resources with appropriate links and fields for each schema. That embedded list can be used to build the page for User to pick the schema or the Client can pick one out of the list it (the Client) “knows” for to use.

The presentation of this process is up to the Client (as always), but unlike other HAL resources, containing data for “known” resource type, here you asking to include a login process (different for each schema) into resource. Each schema can be represented by its own resource, but what to do with data, provided by that resource, is up to the Client. The URL-template may provide some clues...