From ddca997bc6b43efd1ef8f1aee5d78ac246e72877 Mon Sep 17 00:00:00 2001 From: Aeneas Date: Mon, 5 Jun 2017 11:01:56 +0200 Subject: [PATCH] docs: add health check to swagger and resolve swagger issues (#488) Closes #355 --- client/handler.go | 2 +- cmd/server/handler.go | 5 +- cmd/server/handler_health_factory.go | 13 + doc.go | 17 +- doc_swagger.go | 6 + docs/api.swagger.yaml | 739 +++++++++++++++++++++------ health/handler.go | 25 + jwk/handler.go | 4 +- oauth2/handler.go | 4 +- policy/handler.go | 2 +- warden/group/doc.go | 2 +- warden/group/handler.go | 6 +- 12 files changed, 661 insertions(+), 164 deletions(-) create mode 100644 cmd/server/handler_health_factory.go create mode 100644 health/handler.go diff --git a/client/handler.go b/client/handler.go index aa123d625f0..f5b38a9848d 100644 --- a/client/handler.go +++ b/client/handler.go @@ -367,7 +367,7 @@ func (h *Handler) Get(w http.ResponseWriter, r *http.Request, ps httprouter.Para // oauth2: hydra.clients // // Responses: -// 204 +// 204: emptyResponse // 401: genericError // 403: genericError // 500: genericError diff --git a/cmd/server/handler.go b/cmd/server/handler.go index 0dd815f52e6..d0e6bbdc704 100644 --- a/cmd/server/handler.go +++ b/cmd/server/handler.go @@ -129,10 +129,7 @@ func (h *Handler) registerRoutes(router *httprouter.Router) { Manager: ctx.GroupManager, } h.Groups.SetRoutes(router) - - router.GET("/health", func(rw http.ResponseWriter, r *http.Request, _ httprouter.Params) { - rw.WriteHeader(http.StatusNoContent) - }) + _ = newHealthHandler(c, router) // Create root account if new install createRS256KeysIfNotExist(c, oauth2.ConsentEndpointKey, "private", "sig") diff --git a/cmd/server/handler_health_factory.go b/cmd/server/handler_health_factory.go new file mode 100644 index 00000000000..7760b3b3261 --- /dev/null +++ b/cmd/server/handler_health_factory.go @@ -0,0 +1,13 @@ +package server + +import ( + "github.com/julienschmidt/httprouter" + "github.com/ory/hydra/config" + "github.com/ory/hydra/health" +) + +func newHealthHandler(c *config.Config, router *httprouter.Router) *health.Handler { + h := &health.Handler{} + h.SetRoutes(router) + return h +} diff --git a/doc.go b/doc.go index fca7522ca7a..cccfea7e7e9 100644 --- a/doc.go +++ b/doc.go @@ -27,13 +27,26 @@ // type: oauth2 // authorizationUrl: /oauth2/auth // tokenUrl: /oauth2/token -// in: header // flow: accessCode -// // Extensions: // --- // x-request-id: string +// x-forwarded-proto: string // --- // // swagger:meta package main + + +// scopes: +// hydra.clients: "A scope required to manage OAuth 2.0 Clients" +// hydra.policies: "A scope required to manage access control policies" +// hydra.groups: "A scope required to manage warden groups" +// hydra.warden: "A scope required to make access control inquiries" +// hydra.keys.get: "A scope required to fetch JSON Web Keys" +// hydra.keys.create: "A scope required to create JSON Web Keys" +// hydra.keys.delete: "A scope required to delete JSON Web Keys" +// hydra.keys.update: "A scope required to get JSON Web Keys" +// offline: "A scope required when requesting refresh tokens" +// openid: "Request an OpenID Connect ID Token" +// \ No newline at end of file diff --git a/doc_swagger.go b/doc_swagger.go index c9a6704b472..51644a31269 100644 --- a/doc_swagger.go +++ b/doc_swagger.go @@ -18,3 +18,9 @@ type genericError struct { Message string `json:"message"` } } + +// The standard error format +// swagger:response emptyResponse +type emptyResponse struct { + Description string `json:"description,omitempty"` +} \ No newline at end of file diff --git a/docs/api.swagger.yaml b/docs/api.swagger.yaml index 4a68b6aa026..f0658c9c7c4 100644 --- a/docs/api.swagger.yaml +++ b/docs/api.swagger.yaml @@ -8,12 +8,26 @@ schemes: - https swagger: '2.0' info: - description: |- - Please refer to the user guide for in-depth documentation: https://ory.gitbooks.io/hydra/content/ + description: >- + Please refer to the user guide for in-depth documentation: + https://ory.gitbooks.io/hydra/content/ + + + Hydra offers OAuth 2.0 and OpenID Connect Core 1.0 capabilities as a + service. Hydra is different, because it works with any existing + authentication infrastructure, not just LDAP or SAML. By implementing a + consent app (works with any programming language) you build a bridge between + Hydra and your authentication infrastructure. + + Hydra is able to securely manage JSON Web Keys, and has a sophisticated + policy-based access control you can use if you want to. + + Hydra is suitable for green- (new) and brownfield (existing) projects. If + you are not familiar with OAuth 2.0 and are working on a greenfield project, + we recommend evaluating if OAuth 2.0 really serves your purpose. Knowledge + of OAuth 2.0 is imperative in understanding what Hydra does and how it + works. - Hydra offers OAuth 2.0 and OpenID Connect Core 1.0 capabilities as a service. Hydra is different, because it works with any existing authentication infrastructure, not just LDAP or SAML. By implementing a consent app (works with any programming language) you build a bridge between Hydra and your authentication infrastructure. - Hydra is able to securely manage JSON Web Keys, and has a sophisticated policy-based access control you can use if you want to. - Hydra is suitable for green- (new) and brownfield (existing) projects. If you are not familiar with OAuth 2.0 and are working on a greenfield project, we recommend evaluating if OAuth 2.0 really serves your purpose. Knowledge of OAuth 2.0 is imperative in understanding what Hydra does and how it works. The official repository is located at https://github.com/ory/hydra title: Hydra OAuth2 & OpenID Connect Server @@ -29,17 +43,27 @@ basePath: / paths: /.well-known/jwks.json: get: - description: |- - Use this method if you do not want to let Hydra generate the JWKs for you, but instead save your own. + description: >- + Use this method if you do not want to let Hydra generate the JWKs for + you, but instead save your own. + + + The subject making the request needs to be assigned to a policy + containing: - The subject making the request needs to be assigned to a policy containing: ``` + { + "resources": ["rn:hydra:keys:hydra.openid.id-token:public"], + "actions": ["GET"], + "effect": "allow" + } + ``` consumes: - application/json @@ -70,7 +94,9 @@ paths: $ref: '#/responses/genericError' /.well-known/openid-configuration: get: - description: 'For more information, please refer to https://openid.net/specs/openid-connect-discovery-1_0.html' + description: >- + For more information, please refer to + https://openid.net/specs/openid-connect-discovery-1_0.html consumes: - application/x-www-form-urlencoded produces: @@ -96,17 +122,26 @@ paths: $ref: '#/responses/genericError' /clients: get: - description: |- + description: >- Never returns a client's secret. - The subject making the request needs to be assigned to a policy containing: + + The subject making the request needs to be assigned to a policy + containing: + ``` + { + "resources": ["rn:hydra:clients"], + "actions": ["get"], + "effect": "allow" + } + ``` consumes: - application/json @@ -133,29 +168,50 @@ paths: '500': $ref: '#/responses/genericError' post: - description: |- - Be aware that an OAuth 2.0 Client may gain highly priviledged access if configured that way. This + description: >- + 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: + + 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: + + 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 @@ -191,28 +247,47 @@ paths: $ref: '#/responses/genericError' '/clients/{id}': get: - description: |- + description: >- Never returns the client's secret. - The subject making the request needs to be assigned to a policy containing: + + The subject making the request needs to be assigned to a policy + containing: + ``` + { + "resources": ["rn:hydra:clients:"], + "actions": ["get"], + "effect": "allow" + } + ``` - Additionally, the context key "owner" is set to the owner of the client, allowing policies such as: + + Additionally, the context key "owner" is set to the owner of the client, + allowing policies such as: + ``` + { + "resources": ["rn:hydra:clients: "], + "actions": ["get"], + "effect": "allow", + "conditions": { "owner": { "type": "EqualsSubjectCondition" } } + } + ``` consumes: - application/json @@ -249,29 +324,50 @@ paths: '500': $ref: '#/responses/genericError' put: - description: |- - Be aware that an OAuth 2.0 Client may gain highly priviledged access if configured that way. This + description: >- + 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: + + 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: + + 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 @@ -311,26 +407,44 @@ paths: '500': $ref: '#/responses/genericError' delete: - description: |- - The subject making the request needs to be assigned to a policy containing: + description: >- + The subject making the request needs to be assigned to a policy + containing: + ``` + { + "resources": ["rn:hydra:clients:"], + "actions": ["delete"], + "effect": "allow" + } + ``` - Additionally, the context key "owner" is set to the owner of the client, allowing policies such as: + + Additionally, the context key "owner" is set to the owner of the client, + allowing policies such as: + ``` + { + "resources": ["rn:hydra:clients:"], + "actions": ["delete"], + "effect": "allow", + "conditions": { "owner": { "type": "EqualsSubjectCondition" } } + } + ``` consumes: - application/json @@ -356,23 +470,42 @@ paths: in: path required: true responses: + '204': + $ref: '#/responses/emptyResponse' '401': $ref: '#/responses/genericError' '403': $ref: '#/responses/genericError' '500': $ref: '#/responses/genericError' + /health: + get: + description: Check health status of instance + operationId: health + responses: + '204': + $ref: '#/responses/emptyResponse' + '500': + $ref: '#/responses/genericError' '/keys/{set}': get: - description: |- - The subject making the request needs to be assigned to a policy containing: + description: >- + The subject making the request needs to be assigned to a policy + containing: + ``` + { + "resources": ["rn:hydra:keys::"], + "actions": ["get"], + "effect": "allow" + } + ``` consumes: - application/json @@ -407,17 +540,27 @@ paths: '500': $ref: '#/responses/genericError' put: - description: |- - Use this method if you do not want to let Hydra generate the JWKs for you, but instead save your own. + description: >- + Use this method if you do not want to let Hydra generate the JWKs for + you, but instead save your own. + + + The subject making the request needs to be assigned to a policy + containing: - The subject making the request needs to be assigned to a policy containing: ``` + { + "resources": ["rn:hydra:keys:"], + "actions": ["update"], + "effect": "allow" + } + ``` consumes: - application/json @@ -456,15 +599,23 @@ paths: '500': $ref: '#/responses/genericError' post: - description: |- - The subject making the request needs to be assigned to a policy containing: + description: >- + The subject making the request needs to be assigned to a policy + containing: + ``` + { + "resources": ["rn:hydra:keys::"], + "actions": ["create"], + "effect": "allow" + } + ``` consumes: - application/json @@ -503,15 +654,23 @@ paths: '500': $ref: '#/responses/genericError' delete: - description: |- - The subject making the request needs to be assigned to a policy containing: + description: >- + The subject making the request needs to be assigned to a policy + containing: + ``` + { + "resources": ["rn:hydra:keys:"], + "actions": ["delete"], + "effect": "allow" + } + ``` consumes: - application/json @@ -535,6 +694,8 @@ paths: in: path required: true responses: + '204': + $ref: '#/responses/emptyResponse' '401': $ref: '#/responses/genericError' '403': @@ -543,15 +704,23 @@ paths: $ref: '#/responses/genericError' '/keys/{set}/{kid}': get: - description: |- - The subject making the request needs to be assigned to a policy containing: + description: >- + The subject making the request needs to be assigned to a policy + containing: + ``` + { + "resources": ["rn:hydra:keys::"], + "actions": ["get"], + "effect": "allow" + } + ``` consumes: - application/json @@ -592,17 +761,27 @@ paths: '500': $ref: '#/responses/genericError' put: - description: |- - Use this method if you do not want to let Hydra generate the JWKs for you, but instead save your own. + description: >- + Use this method if you do not want to let Hydra generate the JWKs for + you, but instead save your own. + + + The subject making the request needs to be assigned to a policy + containing: - The subject making the request needs to be assigned to a policy containing: ``` + { + "resources": ["rn:hydra:keys::"], + "actions": ["update"], + "effect": "allow" + } + ``` consumes: - application/json @@ -647,15 +826,23 @@ paths: '500': $ref: '#/responses/genericError' delete: - description: |- - The subject making the request needs to be assigned to a policy containing: + description: >- + The subject making the request needs to be assigned to a policy + containing: + ``` + { + "resources": ["rn:hydra:keys::"], + "actions": ["delete"], + "effect": "allow" + } + ``` consumes: - application/json @@ -685,6 +872,8 @@ paths: in: path required: true responses: + '204': + $ref: '#/responses/emptyResponse' '401': $ref: '#/responses/genericError' '403': @@ -693,7 +882,9 @@ paths: $ref: '#/responses/genericError' /oauth2/auth: get: - description: 'For more information, please refer to https://tools.ietf.org/html/rfc6749#section-4' + description: >- + For more information, please refer to + https://tools.ietf.org/html/rfc6749#section-4 consumes: - application/x-www-form-urlencoded schemes: @@ -705,14 +896,16 @@ paths: operationId: oauthAuth responses: '302': - description: "found" + $ref: '#/responses/emptyResponse' '401': $ref: '#/responses/genericError' '500': $ref: '#/responses/genericError' /oauth2/introspect: post: - description: 'For more information, please refer to https://tools.ietf.org/html/rfc7662' + description: >- + For more information, please refer to + https://tools.ietf.org/html/rfc7662 consumes: - application/x-www-form-urlencoded produces: @@ -735,7 +928,9 @@ paths: $ref: '#/responses/genericError' /oauth2/revoke: post: - description: 'For more information, please refer to https://tools.ietf.org/html/rfc7009' + description: >- + For more information, please refer to + https://tools.ietf.org/html/rfc7009 consumes: - application/x-www-form-urlencoded produces: @@ -764,14 +959,16 @@ paths: x-go-name: RefreshToken responses: '200': - description: "ok" + $ref: '#/responses/emptyResponse' '401': $ref: '#/responses/genericError' '500': $ref: '#/responses/genericError' /oauth2/token: post: - description: 'For more information, please refer to https://tools.ietf.org/html/rfc6749#section-4' + description: >- + For more information, please refer to + https://tools.ietf.org/html/rfc6749#section-4 consumes: - application/x-www-form-urlencoded produces: @@ -794,17 +991,27 @@ paths: $ref: '#/responses/genericError' /policies: get: - description: |- - Visit https://github.com/ory/ladon#usage for more information on policy usage. + description: >- + Visit https://github.com/ory/ladon#usage for more information on policy + usage. + + + The subject making the request needs to be assigned to a policy + containing: - The subject making the request needs to be assigned to a policy containing: ``` + { + "resources": ["rn:hydra:policies"], + "actions": ["list"], + "effect": "allow" + } + ``` consumes: - application/json @@ -843,17 +1050,27 @@ paths: '500': $ref: '#/responses/genericError' post: - description: |- - Visit https://github.com/ory/ladon#usage for more information on policy usage. + description: >- + Visit https://github.com/ory/ladon#usage for more information on policy + usage. + + + The subject making the request needs to be assigned to a policy + containing: - The subject making the request needs to be assigned to a policy containing: ``` + { + "resources": ["rn:hydra:policies"], + "actions": ["create"], + "effect": "allow" + } + ``` consumes: - application/json @@ -887,17 +1104,27 @@ paths: $ref: '#/responses/genericError' '/policies/{id}': get: - description: |- - Visit https://github.com/ory/ladon#usage for more information on policy usage. + description: >- + Visit https://github.com/ory/ladon#usage for more information on policy + usage. + + + The subject making the request needs to be assigned to a policy + containing: - The subject making the request needs to be assigned to a policy containing: ``` + { + "resources": ["rn:hydra:policies:"], + "actions": ["get"], + "effect": "allow" + } + ``` consumes: - application/json @@ -933,17 +1160,27 @@ paths: '500': $ref: '#/responses/genericError' put: - description: |- - Visit https://github.com/ory/ladon#usage for more information on policy usage. + description: >- + Visit https://github.com/ory/ladon#usage for more information on policy + usage. + + + The subject making the request needs to be assigned to a policy + containing: - The subject making the request needs to be assigned to a policy containing: ``` + { + "resources": ["rn:hydra:policies"], + "actions": ["update"], + "effect": "allow" + } + ``` consumes: - application/json @@ -983,17 +1220,27 @@ paths: '500': $ref: '#/responses/genericError' delete: - description: |- - Visit https://github.com/ory/ladon#usage for more information on policy usage. + description: >- + Visit https://github.com/ory/ladon#usage for more information on policy + usage. + + + The subject making the request needs to be assigned to a policy + containing: - The subject making the request needs to be assigned to a policy containing: ``` + { + "resources": ["rn:hydra:policies:"], + "actions": ["delete"], + "effect": "allow" + } + ``` consumes: - application/json @@ -1018,6 +1265,8 @@ paths: in: path required: true responses: + '204': + $ref: '#/responses/emptyResponse' '401': $ref: '#/responses/genericError' '403': @@ -1026,19 +1275,32 @@ paths: $ref: '#/responses/genericError' /warden/allowed: post: - description: |- - Checks if an arbitrary subject is allowed to perform an action on a resource. This endpoint requires a subject, - a resource name, an action name and a context.If the subject is not allowed to perform the action on the resource, + description: >- + Checks if an arbitrary subject is allowed to perform an action on a + resource. This endpoint requires a subject, + + a resource name, an action name and a context.If the subject is not + allowed to perform the action on the resource, + this endpoint returns a 200 response with `{ "allowed": false} }`. - The subject making the request needs to be assigned to a policy containing: + + The subject making the request needs to be assigned to a policy + containing: + ``` + { + "resources": ["rn:hydra:warden:allowed"], + "actions": ["decide"], + "effect": "allow" + } + ``` consumes: - application/json @@ -1070,15 +1332,23 @@ paths: $ref: '#/responses/genericError' /warden/groups: get: - description: |- - The subject making the request needs to be assigned to a policy containing: + description: >- + The subject making the request needs to be assigned to a policy + containing: + ``` + { + "resources": ["rn:hydra:warden:groups:"], + "actions": ["get"], + "effect": "allow" + } + ``` consumes: - application/json @@ -1112,15 +1382,23 @@ paths: '500': $ref: '#/responses/genericError' post: - description: |- - The subject making the request needs to be assigned to a policy containing: + description: >- + The subject making the request needs to be assigned to a policy + containing: + ``` + { + "resources": ["rn:hydra:warden:groups"], + "actions": ["create"], + "effect": "allow" + } + ``` consumes: - application/json @@ -1148,15 +1426,23 @@ paths: $ref: '#/responses/genericError' '/warden/groups/{id}': get: - description: |- - The subject making the request needs to be assigned to a policy containing: + description: >- + The subject making the request needs to be assigned to a policy + containing: + ``` + { + "resources": ["rn:hydra:warden:groups:"], + "actions": ["create"], + "effect": "allow" + } + ``` consumes: - application/json @@ -1191,15 +1477,23 @@ paths: '500': $ref: '#/responses/genericError' delete: - description: |- - The subject making the request needs to be assigned to a policy containing: + description: >- + The subject making the request needs to be assigned to a policy + containing: + ``` + { + "resources": ["rn:hydra:warden:groups:"], + "actions": ["delete"], + "effect": "allow" + } + ``` consumes: - application/json @@ -1216,7 +1510,17 @@ paths: security: - oauth2: - hydra.groups + parameters: + - type: integer + format: int64 + x-go-name: ID + description: The id of the group to look up. + name: id + in: path + required: true responses: + '204': + $ref: '#/responses/emptyResponse' '401': $ref: '#/responses/genericError' '403': @@ -1225,15 +1529,23 @@ paths: $ref: '#/responses/genericError' '/warden/groups/{id}/members': post: - description: |- - The subject making the request needs to be assigned to a policy containing: + description: >- + The subject making the request needs to be assigned to a policy + containing: + ``` + { + "resources": ["rn:hydra:warden:groups:"], + "actions": ["members.add"], + "effect": "allow" + } + ``` consumes: - application/json @@ -1263,6 +1575,8 @@ paths: schema: $ref: '#/definitions/membersRequest' responses: + '204': + $ref: '#/responses/emptyResponse' '401': $ref: '#/responses/genericError' '403': @@ -1270,15 +1584,23 @@ paths: '500': $ref: '#/responses/genericError' delete: - description: |- - The subject making the request needs to be assigned to a policy containing: + description: >- + The subject making the request needs to be assigned to a policy + containing: + ``` + { + "resources": ["rn:hydra:warden:groups:"], + "actions": ["members.remove"], + "effect": "allow" + } + ``` consumes: - application/json @@ -1308,6 +1630,8 @@ paths: schema: $ref: '#/definitions/membersRequest' responses: + '204': + $ref: '#/responses/emptyResponse' '401': $ref: '#/responses/genericError' '403': @@ -1316,24 +1640,43 @@ paths: $ref: '#/responses/genericError' /warden/token/allowed: post: - description: |- - Checks if a token is valid and if the token owner is allowed to perform an action on a resource. - This endpoint requires a token, a scope, a resource name, an action name and a context. + description: >- + Checks if a token is valid and if the token owner is allowed to perform + an action on a resource. + + This endpoint requires a token, a scope, a resource name, an action name + and a context. + + + If a token is expired/invalid, has not been granted the requested scope + or the subject is not allowed to + + perform the action on the resource, this endpoint returns a 200 response + with `{ "allowed": false} }`. - If a token is expired/invalid, has not been granted the requested scope or the subject is not allowed to - perform the action on the resource, this endpoint returns a 200 response with `{ "allowed": false} }`. - Extra data set through the `at_ext` claim in the consent response will be included in the response. + Extra data set through the `at_ext` claim in the consent response will + be included in the response. + The `id_ext` claim will never be returned by this endpoint. - The subject making the request needs to be assigned to a policy containing: + + The subject making the request needs to be assigned to a policy + containing: + ``` + { + "resources": ["rn:hydra:warden:token:allowed"], + "actions": ["decide"], + "effect": "allow" + } + ``` consumes: - application/json @@ -1372,7 +1715,9 @@ definitions: type: object properties: aud: - description: Audience is who the token was issued for. This is an OAuth2 app usually. + description: >- + Audience is who the token was issued for. This is an OAuth2 app + usually. type: string x-go-name: Audience exp: @@ -1392,14 +1737,18 @@ definitions: type: string x-go-name: Issuer scopes: - description: GrantedScopes is a list of scopes that the subject authorized when asked for consent. + description: >- + GrantedScopes is a list of scopes that the subject authorized when + asked for consent. type: array items: type: string x-go-name: GrantedScopes sub: - description: |- - Subject is the identity that authorized issuing the token, for example a user or an OAuth2 app. + description: >- + Subject is the identity that authorized issuing the token, for example + a user or an OAuth2 app. + This is usually a uuid but you can choose a urn or some other id too. type: string x-go-name: Subject @@ -1450,7 +1799,7 @@ definitions: type: object additionalProperties: type: object - x-go-package: github.com/ory/fosite/token/jwt + x-go-package: github.com/ory/hydra/vendor/github.com/ory/fosite/token/jwt IDTokenClaims: description: IDTokenClaims represent the claims used in open id connect requests type: object @@ -1474,14 +1823,16 @@ definitions: type: string Subject: type: string - x-go-package: github.com/ory/fosite/token/jwt + x-go-package: github.com/ory/hydra/vendor/github.com/ory/fosite/token/jwt Manager: type: object x-go-package: github.com/ory/hydra/warden/group OAuth2Provider: description: Check fosite.Fosite for an implementation of this interface. type: object - title: OAuth2Provider is an interface that enables you to write OAuth2 handlers with only a few lines of code. + title: >- + OAuth2Provider is an interface that enables you to write OAuth2 handlers + with only a few lines of code. x-go-package: github.com/ory/hydra/vendor/github.com/ory/fosite Session: type: object @@ -1507,26 +1858,43 @@ definitions: title: Store is an interface for custom session stores. x-go-package: github.com/ory/hydra/vendor/github.com/gorilla/sessions URL: - description: |- + description: >- scheme://[userinfo@]host/path[?query][#fragment] + URLs that do not start with a slash after the scheme are interpreted as: + scheme:opaque[?query][#fragment] - Note that the Path field is stored in decoded form: /%47%6f%2f becomes /Go/. - A consequence is that it is impossible to tell which slashes in the Path were - slashes in the raw URL and which were %2f. This distinction is rarely important, + + Note that the Path field is stored in decoded form: /%47%6f%2f becomes + /Go/. + + A consequence is that it is impossible to tell which slashes in the Path + were + + slashes in the raw URL and which were %2f. This distinction is rarely + important, + but when it is, code must not use Path directly. + Go 1.5 introduced the RawPath field to hold the encoded form of Path. + The Parse function sets both Path and RawPath in the URL it returns, + and URL's String method uses RawPath if it is a valid encoding of Path, + by calling the EscapedPath method. + In earlier versions of Go, the more indirect workarounds were that an + HTTP server could consult req.RequestURI and an HTTP client could + construct a URL struct directly and set the Opaque field instead of Path. + These still work as well. type: object title: |- @@ -1576,44 +1944,73 @@ definitions: type: string x-go-name: AuthURL id_token_signing_alg_values_supported: - description: |- - JSON array containing a list of the JWS signing algorithms (alg values) supported by the OP for the ID Token - to encode the Claims in a JWT [JWT]. The algorithm RS256 MUST be included. The value none MAY be supported, - but MUST NOT be used unless the Response Type used returns no ID Token from the Authorization Endpoint + description: >- + JSON array containing a list of the JWS signing algorithms (alg + values) supported by the OP for the ID Token + + to encode the Claims in a JWT [JWT]. The algorithm RS256 MUST be + included. The value none MAY be supported, + + but MUST NOT be used unless the Response Type used returns no ID Token + from the Authorization Endpoint + (such as when using the Authorization Code Flow). type: array items: type: string x-go-name: SigningAlgs issuer: - description: |- - URL using the https scheme with no query or fragment component that the OP asserts as its Issuer Identifier. - If Issuer discovery is supported , this value MUST be identical to the issuer value returned - by WebFinger. This also MUST be identical to the iss Claim value in ID Tokens issued from this Issuer. + description: >- + URL using the https scheme with no query or fragment component that + the OP asserts as its Issuer Identifier. + + If Issuer discovery is supported , this value MUST be identical to the + issuer value returned + + by WebFinger. This also MUST be identical to the iss Claim value in ID + Tokens issued from this Issuer. type: string x-go-name: Issuer jwks_uri: - description: |- - URL of the OP's JSON Web Key Set [JWK] document. This contains the signing key(s) the RP uses to validate - signatures from the OP. The JWK Set MAY also contain the Server's encryption key(s), which are used by RPs - to encrypt requests to the Server. When both signing and encryption keys are made available, a use (Key Use) - parameter value is REQUIRED for all keys in the referenced JWK Set to indicate each key's intended usage. - Although some algorithms allow the same key to be used for both signatures and encryption, doing so is - NOT RECOMMENDED, as it is less secure. The JWK x5c parameter MAY be used to provide X.509 representations of - keys provided. When used, the bare key values MUST still be present and MUST match those in the certificate. + description: >- + URL of the OP's JSON Web Key Set [JWK] document. This contains the + signing key(s) the RP uses to validate + + signatures from the OP. The JWK Set MAY also contain the Server's + encryption key(s), which are used by RPs + + to encrypt requests to the Server. When both signing and encryption + keys are made available, a use (Key Use) + + parameter value is REQUIRED for all keys in the referenced JWK Set to + indicate each key's intended usage. + + Although some algorithms allow the same key to be used for both + signatures and encryption, doing so is + + NOT RECOMMENDED, as it is less secure. The JWK x5c parameter MAY be + used to provide X.509 representations of + + keys provided. When used, the bare key values MUST still be present + and MUST match those in the certificate. type: string x-go-name: JWKsURI response_types_supported: - description: |- - JSON array containing a list of the OAuth 2.0 response_type values that this OP supports. Dynamic OpenID - Providers MUST support the code, id_token, and the token id_token Response Type values. + description: >- + JSON array containing a list of the OAuth 2.0 response_type values + that this OP supports. Dynamic OpenID + + Providers MUST support the code, id_token, and the token id_token + Response Type values. type: array items: type: string x-go-name: ResponseTypes subject_types_supported: - description: |- - JSON array containing a list of the Subject Identifier types that this OP supports. Valid types include + description: >- + JSON array containing a list of the Subject Identifier types that this + OP supports. Valid types include + pairwise and public. type: array items: @@ -1659,7 +2056,9 @@ definitions: - kid properties: alg: - description: 'The algorithm to be used for creating the key. Supports "RS256", "ES521" and "HS256"' + description: >- + The algorithm to be used for creating the key. Supports "RS256", + "ES521" and "HS256" type: string x-go-name: Algorithm kid: @@ -1839,28 +2238,40 @@ definitions: title: Client represents an OAuth 2.0 Client. properties: client_name: - description: |- - Name is the human-readable string name of the client to be presented to the + description: >- + Name is the human-readable string name of the client to be presented + to the + end-user during authorization. type: string x-go-name: Name client_secret: - description: |- - Secret is the client's secret. The secret will be included in the create request as cleartext, and then - never again. The secret is stored using BCrypt so it is impossible to recover it. Tell your users - that they need to write the secret down as it will not be made available again. + description: >- + Secret is the client's secret. The secret will be included in the + create request as cleartext, and then + + never again. The secret is stored using BCrypt so it is impossible to + recover it. Tell your users + + that they need to write the secret down as it will not be made + available again. type: string x-go-name: Secret client_uri: - description: |- - ClientURI is an URL string of a web page providing information about the client. + description: >- + ClientURI is an URL string of a web page providing information about + the client. + If present, the server SHOULD display this URL to the end-user in + a clickable fashion. type: string x-go-name: ClientURI contacts: - description: |- - Contacts is a array of strings representing ways to contact people responsible + description: >- + Contacts is a array of strings representing ways to contact people + responsible + for this client, typically email addresses. type: array items: @@ -1886,27 +2297,37 @@ definitions: type: string x-go-name: Owner policy_uri: - description: |- - PolicyURI is a URL string that points to a human-readable privacy policy document + description: >- + PolicyURI is a URL string that points to a human-readable privacy + policy document + that describes how the deployment organization collects, uses, + retains, and discloses personal data. type: string x-go-name: PolicyURI public: - description: |- - Public is a boolean that identifies this client as public, meaning that it - does not have a secret. It will disable the client_credentials grant type for this client if set. + description: >- + Public is a boolean that identifies this client as public, meaning + that it + + does not have a secret. It will disable the client_credentials grant + type for this client if set. type: boolean x-go-name: Public redirect_uris: - description: 'RedirectURIs is an array of allowed redirect urls for the client, for example: http://mydomain/oauth/callback .' + description: >- + RedirectURIs is an array of allowed redirect urls for the client, for + example: http://mydomain/oauth/callback . type: array items: type: string x-go-name: RedirectURIs response_types: - description: |- - ResponseTypes is an array of the OAuth 2.0 response type strings that the client can + description: >- + ResponseTypes is an array of the OAuth 2.0 response type strings that + the client can + use at the authorization endpoint. type: array pattern: id_token|code|token @@ -1914,18 +2335,25 @@ definitions: type: string x-go-name: ResponseTypes scope: - description: |- - Scope is a string containing a space-separated list of scope values (as + description: >- + Scope is a string containing a space-separated list of scope values + (as + described in Section 3.3 of OAuth 2.0 [RFC6749]) that the client + can use when requesting access tokens. type: string pattern: '([a-zA-Z0-9\.]+\s)+' x-go-name: Scope tos_uri: - description: |- - TermsOfServiceURI is a URL string that points to a human-readable terms of service + description: >- + TermsOfServiceURI is a URL string that points to a human-readable + terms of service + document for the client that describes a contractual relationship + between the end-user and the client that the end-user accepts when + authorizing the client. type: string x-go-name: TermsOfServiceURI @@ -2165,6 +2593,11 @@ responses: type: array items: $ref: '#/definitions/oauthClient' + emptyResponse: + description: The standard error format + headers: + description: + type: string findGroupsByMemberResponse: description: A list of groups the member is belonging to schema: @@ -2290,9 +2723,11 @@ responses: format: int64 x-go-name: IDToken refresh_token: - description: |- + description: >- The refresh token, which can be used to obtain new - access tokens. To retrieve it add the scope "offline" to your access token request. + + access tokens. To retrieve it add the scope "offline" to your access + token request. type: string x-go-name: RefreshToken scope: @@ -2323,7 +2758,9 @@ responses: type: boolean x-go-name: Allowed aud: - description: Audience is who the token was issued for. This is an OAuth2 app usually. + description: >- + Audience is who the token was issued for. This is an OAuth2 app + usually. type: string x-go-name: Audience exp: @@ -2343,21 +2780,25 @@ responses: type: string x-go-name: Issuer scopes: - description: GrantedScopes is a list of scopes that the subject authorized when asked for consent. + description: >- + GrantedScopes is a list of scopes that the subject authorized when + asked for consent. type: array items: type: string x-go-name: GrantedScopes sub: - description: |- - Subject is the identity that authorized issuing the token, for example a user or an OAuth2 app. - This is usually a uuid but you can choose a urn or some other id too. + description: >- + Subject is the identity that authorized issuing the token, for + example a user or an OAuth2 app. + + This is usually a uuid but you can choose a urn or some other id + too. type: string x-go-name: Subject securityDefinitions: oauth2: type: oauth2 - in: header flow: accessCode authorizationUrl: /oauth2/auth tokenUrl: /oauth2/token @@ -2371,4 +2812,6 @@ securityDefinitions: hydra.keys.delete: "A scope required to delete JSON Web Keys" hydra.keys.update: "A scope required to get JSON Web Keys" offline: "A scope required when requesting refresh tokens" + openid: "Request an OpenID Connect ID Token" +x-forwarded-proto: string x-request-id: string diff --git a/health/handler.go b/health/handler.go new file mode 100644 index 00000000000..c1d0a14a28c --- /dev/null +++ b/health/handler.go @@ -0,0 +1,25 @@ +package health + +import ( + "github.com/julienschmidt/httprouter" + "net/http" +) + +type Handler struct { + +} + +func (h *Handler) SetRoutes(r *httprouter.Router) { + r.GET("/health", h.Health) +} + +// swagger:route GET /health health +// +// Check health status of instance +// +// Responses: +// 204: emptyResponse +// 500: genericError +func (h *Handler) Health(rw http.ResponseWriter, r *http.Request, _ httprouter.Params) { + rw.WriteHeader(http.StatusNoContent) +} diff --git a/jwk/handler.go b/jwk/handler.go index 7a1c14871c8..0770a1573d1 100644 --- a/jwk/handler.go +++ b/jwk/handler.go @@ -457,7 +457,7 @@ func (h *Handler) UpdateKey(w http.ResponseWriter, r *http.Request, ps httproute // oauth2: hydra.keys.delete // // Responses: -// 204 +// 204: emptyResponse // 401: genericError // 403: genericError // 500: genericError @@ -507,7 +507,7 @@ func (h *Handler) DeleteKeySet(w http.ResponseWriter, r *http.Request, ps httpro // oauth2: hydra.keys.delete // // Responses: -// 204 +// 204: emptyResponse // 401: genericError // 403: genericError // 500: genericError diff --git a/oauth2/handler.go b/oauth2/handler.go index 539de90a0a9..df7007bee41 100644 --- a/oauth2/handler.go +++ b/oauth2/handler.go @@ -164,7 +164,7 @@ func (h *Handler) WellKnownHandler(w http.ResponseWriter, r *http.Request, _ htt // oauth2: // // Responses: -// 200: +// 200: emptyResponse // 401: genericError // 500: genericError func (h *Handler) RevocationHandler(w http.ResponseWriter, r *http.Request, _ httprouter.Params) { @@ -295,7 +295,7 @@ func (h *Handler) TokenHandler(w http.ResponseWriter, r *http.Request, _ httprou // Schemes: http, https // // Responses: -// 302: +// 302: emptyResponse // 401: genericError // 500: genericError func (h *Handler) AuthHandler(w http.ResponseWriter, r *http.Request, _ httprouter.Params) { diff --git a/policy/handler.go b/policy/handler.go index 8a8bdd91a95..5f0cc5077e8 100644 --- a/policy/handler.go +++ b/policy/handler.go @@ -249,7 +249,7 @@ func (h *Handler) Get(w http.ResponseWriter, r *http.Request, ps httprouter.Para // oauth2: hydra.policies // // Responses: -// 204 +// 204: emptyResponse // 401: genericError // 403: genericError // 500: genericError diff --git a/warden/group/doc.go b/warden/group/doc.go index a349950298a..930c154e169 100644 --- a/warden/group/doc.go +++ b/warden/group/doc.go @@ -15,7 +15,7 @@ type swaggerFindGroupsByMemberParameters struct { Member int `json:"member"` } -// swagger:parameters getGroup +// swagger:parameters getGroup deleteGroup type swaggerGetGroupParameters struct { // The id of the group to look up. // in: path diff --git a/warden/group/handler.go b/warden/group/handler.go index 95e51fb8f49..cb28cb7f8be 100644 --- a/warden/group/handler.go +++ b/warden/group/handler.go @@ -223,7 +223,7 @@ func (h *Handler) GetGroup(w http.ResponseWriter, r *http.Request, ps httprouter // oauth2: hydra.groups // // Responses: -// 204 +// 204: emptyResponse // 401: genericError // 403: genericError // 500: genericError @@ -273,7 +273,7 @@ func (h *Handler) DeleteGroup(w http.ResponseWriter, r *http.Request, ps httprou // oauth2: hydra.groups // // Responses: -// 204 +// 204: emptyResponse // 401: genericError // 403: genericError // 500: genericError @@ -329,7 +329,7 @@ func (h *Handler) AddGroupMembers(w http.ResponseWriter, r *http.Request, ps htt // oauth2: hydra.groups // // Responses: -// 204 +// 204: emptyResponse // 401: genericError // 403: genericError // 500: genericError