Granted Endpoint Proposal: Performant access decisions for resource providers using REST

[aeneasr]

Right now, there is no endpoint for resource providers. They rely on the guard and introspect endpoint. I propose to merge the guard and introspect in a new and powerful endpoint called Granted (available at /oauth2/granted). This endpoint requires:

Header

• Authorize: basic with a client id and secret. The client must exist and be explicitly allowed to access the lookup endpoint.

POST JSON Body

• token: {token}: The access token to be inspected
• resource: {resource-name}: The resource that is being accessed
• permission: {permission}: The permission that is being required
• context: A object for decisions based on conditions.
  • resourceOwner: {owner-id}: The resource's owner
  • requestIP: {request-ip-address}: The IP address which issued the request
  • requestedAt: {ISO-8601-date}: The time the request was issued
  • requestUserAgent: {request-user-agent}: The user agent that issued the request
  • ... this list could be expandable

Non-normative example:

{
    "token": "jklsdfopiqw34-ltspgodyxoz.jfkal1jk8g09",
    "resource": "rn:some:resource:name",
    "permission": "delete",
    "context": {
        "resourceOwner": "peter",
        "resourceIP": "127.0.0.1",
    }
}

Response JSON

• granted: {true|false}: If access was granted to the token
• error: {message}: Error explains why the grant request was denied. Only set if access was denied.

Errors

• This endpoint returns 401 unauthorized if the client credentials are invalid
• This endpoint returns 403 forbidden if the client is forbidden from using this endpoint.

This prevents third parties from using this endpoint. Third parties should use the introspect endpoint instead, because it checks if token audience and client id match, which is not required for resource providers!

[joeblew99]

This allows a user or system admin to reflect on a users account, and see all the things they are authorised to do ? Like auditing you could say ?

[aeneasr]

Yes, I think that is a good summary!

Whops, clicked close and comment

[joeblew99]

Ok nice feature. As a system grows it helps allot

On Mon, 8 Feb 2016, 13:21 Aeneas notifications@github.com wrote:

Reopened #48 #48.

—
Reply to this email directly or view it on GitHub
#48 (comment).

[aeneasr]

Cool! Thank's for looking over it :) Did you check out how policies work?

[joeblew99]

wow you have been busy.

i gave it a quick read. yes acls basically suck once the code and api expands.

how is the ability to audit coming along as per this main issue.
i would really like to try this out with some test examples too.

[aeneasr]

Yeah still some cleaning up to do and test cases to write. Docs will follow alongside :)