docs: improve client swagger specs and add jwk specs

bat-21 · May 7, 2017 · c613540 · c613540
1 parent f16cb77
commit c613540
Show file tree

Hide file tree

Showing 7 changed files with 1,277 additions and 317 deletions.
diff --git a/client/doc.go b/client/doc.go
@@ -1,2 +1,36 @@
 // Package client implements the OAuth 2.0 Client functionality and provides http handlers, http clients and storage adapters.
 package client
+
+// swagger:parameters createOAuthClient
+type swaggerCreateClientPayload struct {
+	// in: body
+	// required: true
+	Body Client
+}
+
+// swagger:parameters updateOAuthClient
+type swaggerUpdateClientPayload struct {
+	// in: path
+	// required: true
+	ID string `json:"id"`
+
+	// in: body
+	// required: true
+	Body Client
+}
+
+// A list of clients.
+// swagger:response clientsList
+type swaggerListClientsResult struct {
+	// in: body
+	Body []Client
+}
+
+// swagger:parameters getOAuthClient deleteOAuthClient
+type swaggerQueryClientPayload struct {
+	// The id of the OAuth 2.0 Client.
+	//
+	// unique: true
+	// in: path
+	ID string `json:"id"`
+}
diff --git a/client/handler.go b/client/handler.go
@@ -37,18 +37,34 @@ func (h *Handler) SetRoutes(r *httprouter.Router) {
 	r.DELETE(ClientsHandlerPath + "/:id", h.Delete)
 }
 
-// swagger:parameters createOAuthClient updateOAuthClient
-type createClientPayload struct {
-	// in: body
-	// required: true
-	Client
-}
-
 // swagger:route POST /clients oauth2 clients createOAuthClient
 //
-// Updates an OAuth 2.0 Client. Be aware that an OAuth 2.0 Client may gain highly priviledged access if configured that way. This
+// Creates an OAuth 2.0 Client
+//
+// Be aware that an OAuth 2.0 Client may gain highly priviledged access if configured that way. This
 // endpoint should be well protected and only called by code you trust.
 //
+// The subject making the request needs to be assigned to a policy containing:
+//
+//  ```
+//  {
+//    "resources": ["rn:hydra:clients"],
+//    "actions": ["create"],
+//    "effect": "allow"
+//  }
+//  ```
+//
+//  Additionally, the context key "owner" is set to the owner of the client, allowing policies such as:
+//
+//  ```
+//  {
+//    "resources": ["rn:hydra:clients"],
+//    "actions": ["create"],
+//    "effect": "allow",
+//    "conditions": { "owner": { "type": "EqualsSubjectCondition" } }
+//  }
+//  ```
+//
 //     Consumes:
 //     - application/json
 //
@@ -106,11 +122,34 @@ func (h *Handler) Create(w http.ResponseWriter, r *http.Request, _ httprouter.Pa
 	h.H.WriteCreated(w, r, ClientsHandlerPath + "/" + c.GetID(), &c)
 }
 
-// swagger:route PUT /clients oauth2 clients updateOAuthClient
+// swagger:route PUT /clients/{id} oauth2 clients updateOAuthClient
+//
+// Updates an OAuth 2.0 Client
 //
-// Updates an OAuth 2.0 Client. Be aware that an OAuth 2.0 Client may gain highly priviledged access if configured that way. This
+// Be aware that an OAuth 2.0 Client may gain highly priviledged access if configured that way. This
 // endpoint should be well protected and only called by code you trust.
 //
+// The subject making the request needs to be assigned to a policy containing:
+//
+//  ```
+//  {
+//    "resources": ["rn:hydra:clients"],
+//    "actions": ["update"],
+//    "effect": "allow"
+//  }
+//  ```
+//
+//  Additionally, the context key "owner" is set to the owner of the client, allowing policies such as:
+//
+//  ```
+//  {
+//    "resources": ["rn:hydra:clients"],
+//    "actions": ["update"],
+//    "effect": "allow",
+//    "conditions": { "owner": { "type": "EqualsSubjectCondition" } }
+//  }
+//  ```
+//
 //     Consumes:
 //     - application/json
 //
@@ -166,16 +205,21 @@ func (h *Handler) Update(w http.ResponseWriter, r *http.Request, ps httprouter.P
 	h.H.WriteCreated(w, r, ClientsHandlerPath + "/" + c.GetID(), &c)
 }
 
-// A list of clients.
-// swagger:response clientsList
-type listClientsResult struct {
-	// in: body
-	Clients []Client
-}
-
 // swagger:route GET /clients oauth2 clients listOAuthClients
 //
-// Fetches OAuth 2.0 Clients, never returns a client's secret.
+// Lists OAuth 2.0 Clients
+//
+// Never returns a client's secret.
+//
+// The subject making the request needs to be assigned to a policy containing:
+//
+// ```
+// {
+//   "resources": ["rn:hydra:clients"],
+//   "actions": ["get"],
+//   "effect": "allow"
+// }
+// ```
 //
 //     Consumes:
 //     - application/json
@@ -218,18 +262,32 @@ func (h *Handler) List(w http.ResponseWriter, r *http.Request, ps httprouter.Par
 	h.H.Write(w, r, c)
 }
 
-// swagger:parameters getOAuthClient deleteOAuthClient
-type queryClientPayload struct {
-	// The id of the OAuth 2.0 Client.
-	//
-	// unique: true
-	// in: path
-	ID string `json:"id"`
-}
-
 // swagger:route GET /clients/{id} oauth2 clients getOAuthClient
 //
-// Fetches an OAuth 2.0 Client. Never returns the client's secret.
+// Fetches an OAuth 2.0 Client.
+//
+// Never returns the client's secret.
+//
+// The subject making the request needs to be assigned to a policy containing:
+//
+//  ```
+//  {
+//    "resources": ["rn:hydra:clients:<some-id>"],
+//    "actions": ["get"],
+//    "effect": "allow"
+//  }
+//  ```
+//
+//  Additionally, the context key "owner" is set to the owner of the client, allowing policies such as:
+//
+//  ```
+//  {
+//    "resources": ["rn:hydra:clients:<some-id> "],
+//    "actions": ["get"],
+//    "effect": "allow",
+//    "conditions": { "owner": { "type": "EqualsSubjectCondition" } }
+//  }
+//  ```
 //
 //     Consumes:
 //     - application/json
@@ -274,7 +332,28 @@ func (h *Handler) Get(w http.ResponseWriter, r *http.Request, ps httprouter.Para
 
 // swagger:route DELETE /clients/{id} oauth2 clients deleteOAuthClient
 //
-// Deletes an OAuth 2.0 Client.
+// Deletes an OAuth 2.0 Client
+//
+// The subject making the request needs to be assigned to a policy containing:
+//
+//  ```
+//  {
+//    "resources": ["rn:hydra:clients:<some-id>"],
+//    "actions": ["delete"],
+//    "effect": "allow"
+//  }
+//  ```
+//
+//  Additionally, the context key "owner" is set to the owner of the client, allowing policies such as:
+//
+//  ```
+//  {
+//    "resources": ["rn:hydra:clients:<some-id>"],
+//    "actions": ["delete"],
+//    "effect": "allow",
+//    "conditions": { "owner": { "type": "EqualsSubjectCondition" } }
+//  }
+//  ```
 //
 //     Consumes:
 //     - application/json
@@ -296,9 +375,18 @@ func (h *Handler) Delete(w http.ResponseWriter, r *http.Request, ps httprouter.P
 	var ctx = r.Context()
 	var id = ps.ByName("id")
 
+	c, err := h.Manager.GetConcreteClient(id)
+	if err != nil {
+		h.H.WriteError(w, r, err)
+		return
+	}
+
 	if _, err := h.W.TokenAllowed(ctx, h.W.TokenFromRequest(r), &firewall.TokenAccessRequest{
 		Resource: fmt.Sprintf(ClientResource, id),
 		Action:   "delete",
+		Context: ladon.Context{
+			"owner": c.GetOwner(),
+		},
 	}, Scope); err != nil {
 		h.H.WriteError(w, r, err)
 		return

diff --git a/doc.go b/doc.go
@@ -13,7 +13,7 @@
 //     Host:
 //     BasePath: /
 //     Version: Latest
-//     License: MIT https://github.com/ory/hydra/blob/master/LICENSE
+//     License: Apache 2.0 https://github.com/ory/hydra/blob/master/LICENSE
 //     Contact: ORY <[email protected]> https://www.ory.am
 //
 //     Consumes:

diff --git a/doc_swagger.go b/doc_swagger.go
@@ -1,26 +1,20 @@
 package main
 
-// A genericError is the error format of Hydra's RESTful APIs.
+// The standard error format
 // swagger:response genericError
 type genericError struct {
 	// in: body
-	body struct {
-		     // code
-		     code    int                      `json:"code,omitempty"`
+	Body struct {
+		     Code    int                      `json:"code,omitempty"`
 
-		     // status
-		     status  string                   `json:"status,omitempty"`
-		     // request
-		     request string                   `json:"request,omitempty"`
+		     Status  string                   `json:"status,omitempty"`
 
-		     // reason
-		     reason  string                   `json:"reason,omitempty"`
+		     Request string                   `json:"request,omitempty"`
 
-		     // details
-		     details []map[string]interface{} `json:"details,omitempty"`
+		     Reason  string                   `json:"reason,omitempty"`
 
+		     Details []map[string]interface{} `json:"details,omitempty"`
 
-		     // message
-		     message string                   `json:"message"`
+		     Message string                   `json:"message"`
 	     }
 }