# # Copyright (C) 2015 The Gravitee team (http://gravitee.io) # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # swagger: '2.0' info: description: >- Gravitee.io - Access Management - OAuth 2.0 API. Defines The OAuth 2.0 Authorization Framework Endpoints exposed by AM server. version: 3.0.x title: Gravitee.io - Access Management - OAuth 2.0 API contact: email: contact@graviteesource.com license: name: Apache 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0.html' host: auth.gravitee.io basePath: /{domain}/oauth schemes: - https paths: /authorize: get: tags: - OAuth 2.0 summary: Get authorization from the resource owner description: The authorization endpoint is used to interact with the resource owner and obtain an authorization grant. parameters: - in: query name: response_type description: The client informs the authorization server of the desired grant type flow using the response_type parameter required: true type: string enum: [code, token, id_token, code token, code id_token, code id_token token, id_token token] - in: query name: client_id description: The client identifier required: true type: string - in: query name: redirect_uri description: After completing its interaction with the resource owner, the authorization server directs the resource owner's user-agent back to the client required: false type: string - in: query name: scope description: The scope of the access request. For OpenID Connect, scopes can be used to request that specific sets of information be made available as Claim Values. required: false type: string - in: query name: state description: RECOMMENDED. An opaque value used by the client to maintain state between the request and callback required: false type: string - in: query name: nonce description: String value used to associate a Client session with an ID Token, and to mitigate replay attacks (Authorization Code Flow) required: false type: string - in: query name: prompt description: Space delimited, case sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for reauthentication and consent type: string enum: [none, login, consent, select_account] - in: query name: max_age description: Maximum Authentication Age. Specifies the allowable elapsed time in seconds since the last time the End-User was actively authenticated by the OP. If the elapsed time is greater than this value, the OP MUST attempt to actively re-authenticate the End-User type: integer - in: query name: claims description: This parameter is used to request that specific Claims be returned. The value is a JSON object listing the requested Claims. required: false type: string responses: '302': description: If the resource owner grants the access request, the authorization server issues an authorization code or token (for Implicit/Hybrid Flow) and delivers it to the client by adding the following parameters to the query component of the redirection URI using the "application/x-www-form-urlencoded" format. /token: post: tags: - OAuth 2.0 summary: Get an access token description: The token endpoint is used by the client to obtain an access token by presenting its authorization grant or refresh token. The token endpoint is used with every authorization grant except for the implicit grant type (since an access token is issued directly). consumes: - application/x-www-form-urlencoded produces: - application/json parameters: - in: formData name: grant_type description: Grant type used to request for an access token required: true type: string enum: [client_credentials, password, authorization_code, refresh_token, urn:ietf:params:oauth:grant-type:jwt-bearer] - in: formData name: scope description: The scope of the access request required: false type: string - in: formData name: code description: The authorization code received from the authorization server (Authorization Code Flow) required: true type: string - in: formData name: redirect_uri description: REQUIRED, if the "redirect_uri" parameter was included in the authorization request, and their values MUST be identical (Authorization Code Flow) required: false type: string - in: formData name: username description: The resource owner username (Resource Owner Password Flow) required: true type: string - in: formData name: password description: The resource owner password (Resource Owner Password Flow) required: true type: string - in: formData name: refresh_token description: The refresh token issued to the client (Refresh Token Flow) required: true type: string responses: '400': description: Invalid Request '401': description: Invalid Client '200': description: The authorization server issues an access token and optional refresh token schema: $ref: '#/definitions/AccessToken' security: - client_auth: [] /introspect: post: tags: - OAuth 2.0 summary: Check token validity description: The token intropsection endpoint defines a method for a protected resource to query an OAuth 2.0 authorization server to determine the active state of an OAuth 2.0 token and to determine meta-information about this token. consumes: - application/x-www-form-urlencoded produces: - application/json parameters: - in: formData name: token description: The string value of the token. For access tokens, this is the "access_token" value returned from the token endpoint defined in OAuth 2.0. required: true type: string - in: formData name: token_type_hint description: A hint about the type of the token submitted for introspection (only access_token is handle) required: false type: string enum: [access_token, refresh_token] responses: '401': description: Invalid client '200': description: Introspection Response schema: $ref: '#/definitions/IntrospectionResponse' security: - client_auth: [] /check_token: post: tags: - OAuth 2.0 summary: Check token validity description: The token intropsection endpoint defines a method for a protected resource to query an OAuth 2.0 authorization server to determine the active state of an OAuth 2.0 token and to determine meta-information about this token. consumes: - application/x-www-form-urlencoded produces: - application/json parameters: - in: formData name: token description: The string value of the token. For access tokens, this is the "access_token" value returned from the token endpoint defined in OAuth 2.0. required: true type: string responses: '401': description: Invalid client or Invalid token '200': description: Check Token Response schema: $ref: '#/definitions/AccessToken' security: - client_auth: [] deprecated: true /revoke: post: tags: - OAuth 2.0 summary: Revoke token description: The revocation endpoint allows clients to notify the authorization server that a previously obtained refresh or access token is no longer needed. consumes: - application/x-www-form-urlencoded parameters: - in: formData name: token description: The token that the client wants to get revoked required: true type: string - in: formData name: token_type_hint description: A hint about the type of the token submitted for revocation required: false type: string enum: [access_token, refresh_token] responses: '200': description: The authorization server responds with HTTP status code 200 if the token has been revoked successfully or if the client submitted an invalid token. '400': description: Invalid request '401': description: Invalid client security: - client_auth: [] securityDefinitions: client_auth: type: basic description: Base64(clientId:clientSecret) definitions: AccessToken: type: object properties: access_token: type: string description: REQUIRED. The access token issued by the authorization server token_type: type: string description: REQUIRED. The type of the token issued (default bearer) expires_in: type: integer description: RECOMMENDED. The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated. If omitted, the authorization server SHOULD provide the expiration time via other means or document the default value. refresh_token: type: string description: OPTIONAL. The refresh token, which can be used to obtain new access tokens using the same authorization grant scope: type: string description: OPTIONAL, if identical to the scope requested by the client; otherwise, REQUIRED id_token: type: string description: OPTIONAL, OpenID Connect ID Token additional_parameters: type: object description: Additional ininital Token/Authorize query parameters added to the Access Token IntrospectionResponse: type: object properties: active: type: boolean description: REQUIRED. Boolean indicator of whether or not the presented token is currently active scope: type: string description: OPTIONAL. A JSON string containing a space-separated list of scopes associated with this token client_id: type: string description: OPTIONAL. Client identifier for the OAuth 2.0 client that requested this token username: type: string description: OPTIONAL. Human-readable identifier for the resource owner who authorized this token token_type: type: string description: OPTIONAL. Type of the token exp: type: integer description: OPTIONAL. Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this token will expire iat: type: integer description: OPTIONAL. Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this token was originally issued nbf: type: integer description: OPTIONAL. Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this token is not to be used before sub: type: string description: OPTIONAL. Subject of the token, as defined in JWT [RFC7519]. Usually a machine-readable identifier of the resource owner who authorized this token aud: type: string description: OPTIONAL. Service-specific string identifier or list of string identifiers representing the intended audience for this token iss: type: string description: OPTIONAL. String representing the issuer of this token jti: type: string description: OPTIONAL. String identifier for the token