# # 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 - OpenID Connect API. Defines The OpenID Connect Endpoints exposed by AM server. version: 2.10.x title: Gravitee.io - Access Management - OpenID Connect 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}/oidc schemes: - https paths: /.well-known/openid-configuration: get: tags: - OpenID Connect summary: Get OpenID Provider configuration information description: Discovery endpoint used by OpenID Connect Relying Party to discover the End-User's OpenID Provider and obtain information needed to interact with it, including its OAuth 2.0 endpoint locations. produces: - application/json responses: '200': description: The OpenID Provider Metadata values schema: $ref: '#/definitions/OpenIDProviderMetadataResponse' /.well-known/jwks.json: get: tags: - OpenID Connect summary: Get JSON Web Key Set description: JWKS endpoint containing the public keys used by OpenID Connect Relying Party to verify any JWT issued by the authorization server. produces: - application/json responses: '200': description: A JSON object that represents a set of JWKs schema: $ref: '#/definitions/JWKSetResponse' /userinfo: get: tags: - OpenID Connect summary: Get claims about the authenticated End-User description: The UserInfo Endpoint is an OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User. produces: - application/json parameters: - in: header name: Authorization description: To obtain the requested Claims about the End-User, the Client makes a request to the UserInfo Endpoint using an Access Token obtained through OpenID Connect Authentication type: string required: true responses: '400': description: Invalid Request '401': description: Invalid Token '200': description: Claims about the authenticated End-User schema: $ref: '#/definitions/UserInfoResponse' post: tags: - OpenID Connect summary: Get claims about the authenticated End-User description: The UserInfo Endpoint is an OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User. consumes: - application/x-www-form-urlencoded produces: - application/json parameters: - in: formData name: access_token description: To obtain the requested Claims about the End-User, the Client makes a request to the UserInfo Endpoint using an Access Token obtained through OpenID Connect Authentication type: string required: true responses: '400': description: Invalid Request '401': description: Invalid Token '200': description: Claims about the authenticated End-User schema: $ref: '#/definitions/UserInfoResponse' /register: post: tags: - OpenID Connect summary: Register (create) a new client. description: The Dynamic Client Registration (dcr) Endpoint is an OAuth 2.0 Protected Resource through which a new Client registration can be requested. consumes: - application/json produces: - application/json parameters: - in: header name: Authorization description: Bearer token obtained through client crendentials flow with as mandatory scope "dcr_admin". Token required unless open dynamic client registration is enabled. type: string required: false - in: body name: request schema: $ref: '#/definitions/ClientRegistrationRequest' required: true responses: '400': description: Invalid Request '401': description: Invalid Token '403': description: Registration forbidden '201': description: Claims about the registred client schema: $ref: '#/definitions/ClientRegistrationResponse' /register/{client_id}: get: tags: - OpenID Connect summary: Get a registred client. description: See information about a registred client. produces: - application/json parameters: - in: header name: Authorization description: Bearer token obtained on the register process through the registration_access_token property giving access only to one client matching the client_id path parameter. An admin token can be also obtained through the client crendentials flow with as mandatory scope "dcr_admin". type: string required: true - in: path name: client_id type: string required: true description: ID of the client responses: '400': description: Invalid Request '401': description: Invalid Token '403': description: Access forbidden '200': description: Claims about the registred client. schema: $ref: '#/definitions/ClientRegistrationResponse' patch: tags: - OpenID Connect summary: Patch a registred client. description: Update information about a registred client. consumes: - application/json produces: - application/json parameters: - in: header name: Authorization description: Bearer token obtained on the register process through the registration_access_token property giving access only to one client matching the client_id path parameter. An admin token can be also obtained through the client crendentials flow with as mandatory scope "dcr_admin". type: string required: true - in: path name: client_id type: string required: true description: ID of the client - in: body name: request schema: $ref: '#/definitions/ClientRegistrationRequest' required: true responses: '400': description: Invalid Request '401': description: Invalid Token '403': description: Access forbidden '200': description: Claims about the updated client. schema: $ref: '#/definitions/ClientRegistrationResponse' delete: tags: - OpenID Connect summary: Delete a registred client. description: Delete a registred client. parameters: - in: header name: Authorization description: Bearer token obtained on the register process through the registration_access_token property giving access only to one client matching the client_id path parameter. An admin token can be also obtained through the client crendentials flow with as mandatory scope "dcr_admin". type: string required: true - in: path name: client_id type: string required: true description: ID of the client responses: '400': description: Invalid Request '401': description: Invalid Token '403': description: Access forbidden '204': description: Client deleted schema: $ref: '#/definitions/ClientRegistrationResponse' /register/{client_id}/renew_secret: post: tags: - OpenID Connect summary: Renew the client secret of a registred client. description: Renew the client secret of a registred client. produces: - application/json parameters: - in: header name: Authorization description: Bearer token obtained on the register process through the registration_access_token property giving access only to one client matching the client_id path parameter. An admin token can be also obtained through the client crendentials flow with as mandatory scope "dcr_admin". type: string required: true - in: path name: client_id type: string required: true description: ID of the client responses: '400': description: Invalid Request '401': description: Invalid Token '403': description: Access forbidden '200': description: Claims about the updated client. schema: $ref: '#/definitions/ClientRegistrationResponse' securityDefinitions: client_auth: type: basic description: Base64(clientId:clientSecret) definitions: OpenIDProviderMetadataResponse: type: object properties: issuer: type: string description: REQUIRED. URL using the https scheme with no query or fragment component that the OP asserts as its Issuer Identifier authorization_endpoint: type: string description: REQUIRED. URL of the OP's OAuth 2.0 Authorization Endpoint token_endpoint: type: string description: URL of the OP's OAuth 2.0 Token Endpoint userinfo_endpoint: type: string description: RECOMMENDED. URL of the OP's UserInfo Endpoint jwks_uri: type: string description: REQUIRED. URL of the OP's JSON Web Key Set [JWK] document. registration_endpoint: type: string description: RECOMMENDED. URL of the OP's Dynamic Client Registration Endpoint scopes_supported: type: string description: RECOMMENDED. JSON array containing a list of the OAuth 2.0 [RFC6749] scope values that this server supports response_types_supported: type: string description: REQUIRED. JSON array containing a list of the OAuth 2.0 response_type values that this OP supports response_modes_supported: type: string description: OPTIONAL. JSON array containing a list of the OAuth 2.0 response_mode values that this OP supports grant_types_supported: type: string description: OPTIONAL. JSON array containing a list of the OAuth 2.0 Grant Type values that this OP supports acr_values_supported: type: string description: OPTIONAL. JSON array containing a list of the Authentication Context Class References that this OP supports subject_types_supported: type: string description: REQUIRED. JSON array containing a list of the Subject Identifier types that this OP supports id_token_signing_alg_values_supported: type: string description: REQUIRED. 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 id_token_encryption_alg_values_supported: type: string description: OPTIONAL. JSON array containing a list of the JWE encryption algorithms (alg values) supported by the OP for the ID Token to encode the Claims in a JWT id_token_encryption_enc_values_supported: type: string description: OPTIONAL. JSON array containing a list of the JWE encryption algorithms (enc values) supported by the OP for the ID Token to encode the Claims in a JWT userinfo_signing_alg_values_supported: type: string description: OPTIONAL. JSON array containing a list of the JWS signing algorithms (alg values) [JWA] supported by the UserInfo Endpoint to encode the Claims in a JWT userinfo_encryption_alg_values_supported: type: string description: ROPTIONAL. JSON array containing a list of the JWE encryption algorithms (alg values) [JWA] supported by the UserInfo Endpoint to encode the Claims in a JWT userinfo_encryption_enc_values_supported: type: string description: OPTIONAL. JSON array containing a list of the JWE encryption algorithms (enc values) [JWA] supported by the UserInfo Endpoint to encode the Claims in a JWT request_object_signing_alg_values_supported: type: string description: OPTIONAL. JSON array containing a list of the JWS signing algorithms (alg values) supported by the OP for Request Objects request_object_encryption_alg_values_supported: type: string description: OPTIONAL. JSON array containing a list of the JWE encryption algorithms (alg values) supported by the OP for Request Objects request_object_encryption_enc_values_supported: type: string description: OPTIONAL. JSON array containing a list of the JWE encryption algorithms (enc values) supported by the OP for Request Objects token_endpoint_auth_methods_supported: type: string description: OPTIONAL. JSON array containing a list of Client Authentication methods supported by this Token Endpoint token_endpoint_auth_signing_alg_values_supported: type: string description: OPTIONAL. JSON array containing a list of the JWS signing algorithms (alg values) supported by the Token Endpoint for the signature on the JWT display_values_supported: type: string description: OPTIONAL. JSON array containing a list of the display parameter values that the OpenID Provider supports claim_types_supported: type: string description: OPTIONAL. JSON array containing a list of the Claim Types that the OpenID Provider supports claims_supported: type: string description: RECOMMENDED. JSON array containing a list of the Claim Names of the Claims that the OpenID Provider MAY be able to supply values for service_documentation: type: string description: OPTIONAL. URL of a page containing human-readable information that developers might want or need to know when using the OpenID Provider claims_locales_supported: type: string description: OPTIONAL. Languages and scripts supported for values in Claims being returned, represented as a JSON array of BCP47 [RFC5646] language tag values ui_locales_supported: type: string description: OPTIONAL. Languages and scripts supported for the user interface, represented as a JSON array of BCP47 [RFC5646] language tag values claims_parameter_supported: type: boolean description: OPTIONAL. Boolean value specifying whether the OP supports use of the claims parameter, with true indicating support. If omitted, the default value is false request_parameter_supported: type: boolean description: OPTIONAL. Boolean value specifying whether the OP supports use of the request parameter, with true indicating support. If omitted, the default value is false request_uri_parameter_supported: type: boolean description: OPTIONAL. Boolean value specifying whether the OP supports use of the request_uri parameter, with true indicating support. If omitted, the default value is true require_request_uri_registration: type: boolean description: OPTIONAL. Boolean value specifying whether the OP requires any request_uri values used to be pre-registered using the request_uris registration parameter op_policy_uri: type: string description: OPTIONAL. URL that the OpenID Provider provides to the person registering the Client to read about the OP's requirements on how the Relying Party can use the data provided by the OP op_tos_uri: type: boolean description: OPTIONAL. URL that the OpenID Provider provides to the person registering the Client to read about OpenID Provider's terms of service UserInfoResponse: type: object properties: sub: type: string description: Subject - Identifier for the End-User at the Issuer name: type: string description: End-User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User's locale and preferences given_name: type: string description: Given name(s) or first name(s) of the End-User family_name: type: string description: Surname(s) or last name(s) of the End-User middle_name: type: string description: Middle name(s) of the End-User nickname: type: string description: Casual name of the End-User that may or may not be the same as the given_name preferred_username: type: string description: Shorthand name by which the End-User wishes to be referred to at the RP, such as janedoe or j.doe profile: type: string description: URL of the End-User's profile page picture: type: string description: URL of the End-User's profile picture website: type: string description: URL of the End-User's Web page or blog email: type: string description: End-User's preferred e-mail address email_verified: type: boolean description: User at the time the verification was performed gender: type: string description: End-User's gender birthdate: type: string description: End-User's birthday, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format zoneinfo: type: string description: String from zoneinfo [zoneinfo] time zone database representing the End-User's time zone locale: type: string description: End-User's locale, represented as a BCP47 [RFC5646] language tag phone_number: type: string description: End-User's preferred telephone number phone_number_verified: type: boolean description: User at the time the verification was performed address: type: string description: End-User's preferred postal address updated_at: type: integer description: Time the End-User's information was last updated JWKSetResponse: type: object properties: keys: type: array description: The value of the "keys" parameter is an array of JWK values items: $ref: '#/definitions/JWKResponse' JWKResponse: type: object properties: kty: type: string description: The "kty" (key type) parameter identifies the cryptographic algorithm family used with the key, such as "RSA" or "EC" use: type: string description: The "use" (public key use) parameter identifies the intended use of the public key key_ops: type: string description: The "key_ops" (key operations) parameter identifies the operation(s) for which the key is intended to be used alg: type: string description: The "alg" (algorithm) parameter identifies the algorithm intended for use with the key kid: type: string description: The "kid" (key ID) parameter is used to match a specific key x5u: type: string description: The "x5u" (X.509 URL) parameter is a URI [RFC3986] that refers to a resource for an X.509 public key certificate or certificate chain [RFC5280] x5c: type: string description: The "x5c" (X.509 certificate chain) parameter contains a chain of one or more PKIX certificates [RFC5280] x5t: type: string description: The "x5t" (X.509 certificate SHA-1 thumbprint) parameter is a base64url-encoded SHA-1 thumbprint (a.k.a. digest) of the DER encoding of an X.509 certificate [RFC5280] x5t#S256: type: string description: The "x5t#S256" (X.509 certificate SHA-256 thumbprint) parameter is a base64url-encoded SHA-256 thumbprint (a.k.a. digest) of the DER encoding of an X.509 certificate [RFC5280] ClientRegistrationRequest: type: object required: - redirect_uris properties: redirect_uris: type: array description: REQUIRED. Array of Redirection URI values used by the Client. One of these registered Redirection URI values MUST exactly match the redirect_uri parameter value used in each Authorization Request items: type: string response_types: type: array description: JSON array containing a list of the OAuth 2.0 response_type values that the Client is declaring that it will restrict itself to using. If omitted, the default is that the Client will use only the code Response Type. items: type: string grant_types: type: array description: JSON array containing a list of the OAuth 2.0 Grant Types that the Client is declaring that it will restrict itself to using. Values used by OpenID Connect are authorization_code, implicit and refresh_token items: type: string application_type: type: string description: Kind of the application. The default, if omitted, is web. The defined values are native or web. contacts: type: array description: Array of e-mail addresses of people responsible for this Client. This might be used by some providers to enable a Web user interface to modify the Client information. items: type: string client_name: type: string description: Name of the Client to be presented to the End-User. logo_uri: type: string description: URL that references a logo for the Client application. client_uri: type: string description: URL of the home page of the Client. The value of this field MUST point to a valid Web page. policy_uri: type: string description: URL that the Relying Party Client provides to the End-User to read about the how the profile data will be used. tos_uri: type: string description: URL that the Relying Party Client provides to the End-User to read about the Relying Party's terms of service. jwks_uri: type: string description: URL for the Client's JSON Web Key Set [JWK] document. jwks: $ref: '#/definitions/JWKSetResponse' description: Client's JSON Web Key Set [JWK] document, passed by value. The semantics of the jwks parameter are the same as the jwks_uri parameter, other than that the JWK Set is passed by value, rather than by reference. sector_identifier_uri: type: string description: URL using the https scheme to be used in calculating Pseudonymous Identifiers by the OP. The URL references a file with a single JSON array of redirect_uri values. subject_type: type: string description: subject_type requested for responses to this Client. The subject_types_supported Discovery parameter contains a list of the supported subject_type values for this server. Valid types include pairwise and public. id_token_signed_response_alg: type: string description: JWS alg algorithm [JWA] REQUIRED for signing the ID Token issued to this Client. The default, if omitted, is RS256. The public key for validating the signature is provided by retrieving the JWK Set referenced by the jwks_uri element from OpenID Connect Discovery 1.0 [OpenID.Discovery]. id_token_encrypted_response_alg: type: string description: JWE alg algorithm [JWA] REQUIRED for encrypting the ID Token issued to this Client. If this is requested, the response will be signed then encrypted, with the result being a Nested JWT, as defined in [JWT]. The default, if omitted, is that no encryption is performed. id_token_encrypted_response_enc: type: string description: JWE enc algorithm [JWA] REQUIRED for encrypting the ID Token issued to this Client. If id_token_encrypted_response_alg is specified, the default for this value is A128CBC-HS256. When id_token_encrypted_response_enc is included, id_token_encrypted_response_alg MUST also be provided. userinfo_signed_response_alg: type: string description: WS alg algorithm [JWA] REQUIRED for signing UserInfo Responses. If this is specified, the response will be JWT [JWT] serialized, and signed using JWS. The default, if omitted, is for the UserInfo Response to return the Claims as a UTF-8 encoded JSON object using the application/json content-type. userinfo_encrypted_response_alg: type: string description: JWE [JWE] alg algorithm [JWA] REQUIRED for encrypting UserInfo Responses. If both signing and encryption are requested, the response will be signed then encrypted, with the result being a Nested JWT, as defined in [JWT]. The default, if omitted, is that no encryption is performed. userinfo_encrypted_response_enc: type: string description: JWE enc algorithm [JWA] REQUIRED for encrypting UserInfo Responses. If userinfo_encrypted_response_alg is specified, the default for this value is A128CBC-HS256. When userinfo_encrypted_response_enc is included, userinfo_encrypted_response_alg MUST also be provided. request_object_signing_alg: type: string description: JWS [JWS] alg algorithm [JWA] that MUST be used for signing Request Objects sent to the OP. All Request Objects from this Client MUST be rejected, if not signed with this algorithm. Request Objects are described in Section 6.1 of OpenID Connect Core 1.0 [OpenID.Core]. This algorithm MUST be used both when the Request Object is passed by value (using the request parameter) and when it is passed by reference (using the request_uri parameter). Servers SHOULD support RS256. The value none MAY be used. The default, if omitted, is that any algorithm supported by the OP and the RP MAY be used. request_object_encryption_alg: type: string description: JWE [JWE] alg algorithm [JWA] the RP is declaring that it may use for encrypting Request Objects sent to the OP. This parameter SHOULD be included when symmetric encryption will be used, since this signals to the OP that a client_secret value needs to be returned from which the symmetric key will be derived, that might not otherwise be returned. The RP MAY still use other supported encryption algorithms or send unencrypted Request Objects, even when this parameter is present. If both signing and encryption are requested, the Request Object will be signed then encrypted, with the result being a Nested JWT, as defined in [JWT]. The default, if omitted, is that the RP is not declaring whether it might encrypt any Request Objects. request_object_encryption_enc: type: string description: JWE enc algorithm [JWA] the RP is declaring that it may use for encrypting Request Objects sent to the OP. If request_object_encryption_alg is specified, the default for this value is A128CBC-HS256. When request_object_encryption_enc is included, request_object_encryption_alg MUST also be provided. token_endpoint_auth_method: type: string description: Requested Client Authentication method for the Token Endpoint. The options are client_secret_post, client_secret_basic, client_secret_jwt, private_key_jwt, and none, as described in Section 9 of OpenID Connect Core 1.0 [OpenID.Core]. Other authentication methods MAY be defined by extensions. If omitted, the default is client_secret_basic -- the HTTP Basic Authentication Scheme specified in Section 2.3.1 of OAuth 2.0 [RFC6749]. token_endpoint_auth_signing_alg: type: string description: JWS [JWS] alg algorithm [JWA] that MUST be used for signing the JWT [JWT] used to authenticate the Client at the Token Endpoint for the private_key_jwt and client_secret_jwt authentication methods. All Token Requests using these authentication methods from this Client MUST be rejected, if the JWT is not signed with this algorithm. Servers SHOULD support RS256. The value none MUST NOT be used. The default, if omitted, is that any algorithm supported by the OP and the RP MAY be used. default_max_age: type: integer description: Default Maximum Authentication Age. Specifies that the End-User MUST be actively authenticated if the End-User was authenticated longer ago than the specified number of seconds. The max_age request parameter overrides this default value. If omitted, no default Maximum Authentication Age is specified. require_auth_time: type: boolean description: Boolean value specifying whether the auth_time Claim in the ID Token is REQUIRED. It is REQUIRED when the value is true. default_acr_values: type: array description: Default requested Authentication Context Class Reference values. Array of strings that specifies the default acr values that the OP is being requested to use for processing requests from this Client, with the values appearing in order of preference. items: type: string initiate_login_uri: type: string description: URI using the https scheme that a third party can use to initiate a login by the RP, as specified in Section 4 of OpenID Connect Core 1.0 [OpenID.Core]. request_uris: type: array description: Array of request_uri values that are pre-registered by the RP for use at the OP. items: type: string scope: type: array description: String containing a space-separated list of scope values items: type: string software_id: type: string description: A unique identifier string (e.g., a Universally Unique Identifier (UUID)) assigned by the client developer or software publisher used by registration endpoints to identify the client software to be dynamically registered. software_version: type: string description: A version identifier string for the client software identified by "software_id". The value of the "software_version" SHOULD change on any update to the client software identified by the same "software_id". software_statement: type: string description: A software statement containing client metadata values about the client software as claims. This is a string value containing the entire signed JWT. ClientRegistrationResponse: allOf: - $ref: '#/definitions/ClientRegistrationRequest' type: object required: - client_id properties: client_id: type: string description: REQUIRED. Unique Client Identifier. It MUST NOT be currently valid for any other registered Client. client_secret: type: string description: Client Secret. The same Client Secret value MUST NOT be assigned to multiple Clients. This value is used by Confidential Clients to authenticate to the Token Endpoint. registration_access_token: type: string description: Registration Access Token that can be used at the Client Configuration Endpoint to perform subsequent operations upon the Client registration. registration_client_uri: type: string description: Location of the Client Configuration Endpoint where the Registration Access Token can be used to perform subsequent operations upon the resulting Client registration. Implementations MUST either return both a Client Configuration Endpoint and a Registration Access Token or neither of them. client_id_issued_at: type: string description: Time at which the Client Identifier was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. client_secret_expires_at: type: integer format: int64 description: if client_secret is issued. Time at which the client_secret will expire or 0 if it will not expire. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.