Skip to content

Home

Jump to bottom
Marc edited this page Dec 13, 2019 · 37 revisions

Endpoints exposed by the Access and Authorization Provider service. Hence forth named AAP. The endpoints control anything in relations to authorizing an Identity.

Table of Contents

Usage

The functions in this REST API is using HTTP method POST to allow for a uniform interface on all endpoints and overcome the inconsistencies in HTTP GET vs POST. To use a GET, POST, PUT or DELETE you must set the X-HTTP-METHOD-OVERRIDE header.

All endpoints can only be reached trough HTTPS with TLS. All endpoints are protected by OAuth2 scopes that are required by the client to call the endpoints.

Structure of Input and Output

All endpoints are designed to be bulk first, meaning input and output are always Sets. Heavily inspired by functional programming. To simplify this structure the API uses Bulky golang package.

A consequence of the bulk first idea is that all HTTP responses has to be 200 even when a request fails. To see the actual status of the request parsing the OK response is needed. A status field is returned for each output entry aswell as an index, that matches the index of input (zero indexed).

AAP comes with github.com/opensentry/aap/client golang package which is an implementation of all endpoints with unmarshalling of output into go structs. This can be imported into go projects to avoid having to parse output manually.

Input

Post [endpoint] HTTP/1.1
Host [hostname of service]
Accept: application/json
Content-Type: application/json
Authorization: Bearer [access_token]
[
  { "message": "hello world" }
]

Output

Status: 200 OK
Content-Type: application/json
[
  {
    "index": 0,
    "status": 200,
    "errors": null,
    "ok": {"message": "hello world"}
  }
]

Concepts

Entity

Endpoint: /entities

An entity is a representation of a human, an application or anything that needs to be uniquely identified within a system.

{
  "id": {
    "type": "string",    
    "description": "A globally unique identifier.",
    "validate": "uuid"
  }
}

Scope

Endpoint: /scopes

A scope is a string which is exposed publicly to form the interface for access and authorization requests and requirements.

In the OAuth2 model this is the scope.

{
  "name": {
    "type": "string",    
    "description": "The scope definition string",
    "validate": "required"
  }
}

Consent

Endpoint: /consents

A consent is a rule that allows an entity access on behalf of another entity. This does not infer that the entity issuing the consent is actually granted access to the resources it consented to.

Grant

Endpoint: /grants

A grant is a rule rule that allows an entity access to a resource on a resource provider. This is the actual access control model.

Publishing

Endpoint: /publishing

A publishing is a rule that exposes a scope for a resource provider. A publishing allows the resource provider to define meaning to the scope. Aka. the same scope can be used by different resource providers, but may mean different things in the context of the resource provider.

Subscription

Endpoint: /subscriptions

A subscription is a rule that allows an entity to request access to a publishing. In an access model this can be used to limit what entities are allowed to request access to resources.

In the OAuth2 model this is the set of scopes that a client is allowed to request access tokens for.

Shadow

Endpoint: /shadows

A shadow is a kind of proxy entity that holds grants which is given to entities that are granted the shadow. In an access model this is often referred to as a role.

Endpoints

TODO

POST /entities

TODO

GET /entities

TODO

DELETE /entities

TODO

GET /entities/judge

Judge an entity. Requires scope aap:read:entities:judge.

Input

{
  "access_token": {
    "type": "string",
    "description": "The access token performing a function.",
    "validate": "required"
  },
  "publisher_id": {
    "type": "string",
    "description": "The resource provider id publishing the function.",
    "validate": "required, uuid"
  },
  "scope": {
    "type": "string",
    "description": "The scope protecting the function.",
    "validate": "required"
  },
  "owners": {
    "type": "array of string",
    "description": "List of owners of the data the function operates on.",
    "validate": "optional, uuid"
  }
}

Output

TODO

POST /consents

TODO

GET /consents

TODO

DELETE /consents

TODO

GET /consents/authorize

TODO

POST /consents/authorize

TODO

POST /consents/reject

TODO

POST /grants

TODO

GET /grants

TODO

DELETE /grants

TODO

POST /publishings

TODO

GET /publishings

TODO

DELETE /publishings

TODO

POST /scopes

TODO

GET /scopes

TODO

POST /subscriptions

TODO

GET /subscriptions

TODO

DELETE /subscriptions

TODO

POST /shadows

TODO

GET /shadows

TODO

DELETE /shadows

TODO

Authorize an Entity

TODO

A part of the Open Sentry Stack.

Clone this wiki locally