swagger: '2.0'
info:
  version: '1.0.0'
  title: Dynamic Client Registration API (DCR)
  description: >-
    This API mechanisms for dynamically registering clients with authorization servers. This API covers registration
    of OpenID Connect (OIDC) clients.

    Registration requests send a set of desired client metadata values to the authorization server. The resulting
    registration responses return a client identifier to use at the authorization server and the client metadata
    values registered for the client. The client can then use this registration information to communicate with the
    authorization server using the OAuth 2.0 protocol.


    **Conformance**

    This API is fairly conformant to the OpenID Connect Dynamic Client Registration 1.0 specification, see [OpenID Connect Dynamic Client Registration 1.0 incorporating errata set 1](https://openid.net/specs/openid-connect-registration-1_0.html).

    iWelcome supports only the Protected Dynamic Client Registration and does not support _Open_ Dynamic Client Registration: when registering a client a valid access_token is required having appropriate authorisation.


    It does not support the full set of client metadata. The following are not supported:
      * policy_uri
      * tos_uri
      * id_token_encrypted_response_alg
      * id_token_encrypted_response_enc
      * request_object_signing_alg
      * request_object_encryption_alg
      * request_object_encryption_enc
      * token_endpoint_auth_signing_alg
      * require_auth_time
      * default_acr_values
      * initiate_login_uri
      * request_uris

    This API is fairly conformant to the RFC's for OAuth client registration: [RFC-7591](https://tools.ietf.org/html/rfc7591) and [RFC-7592](https://tools.ietf.org/html/rfc7592). 
    Updating a registered client (using a PUT method on the registration endpoint) is not supported.
    The schema for registered clients does not support the following attributes:

      * tos_uri
      * policy_uri
      * software_id
      * software_version
      * client_id_issued_at
      * Furthermore 'scope' is called 'scopes' and takes the form of a json-array rather than a space-separated string.

      Furthermore, iWelcome does support client registration of public clients and confidential clients.

    **iWelcome extension**

    iWelcome has extended the schema for clients:
      * default_scopes

    iWelcome has added an additional endpoint to delete a client, resulting in two 'delete endpoints':
      * the 'self delete' endpoint as per RFC-7592, which requires the registration access token
      * an 'admin delete' endpoint which allows to delete any OAuth client. Obviously this endpoint needs to be used with care.


    **API-security**

    All endpoints in this api are protected endpoints; they require a valid OAuth access_token. More specifically:
      * the POST on registration requires the access_token to have scope dynamic-client-registration
      * the GET requires the registration_access_token
      * the (self) DELETE requires the registration_access_token
      * the (Admin) DELETE requires the access_token to have scope dynamic-client-registration.

    **Performance considerations**

    The number of OAuth clients that are registered may impact the performance of iWelcome's support for the various OAuth and OIDC endpoints. iWelcome currently does not guarantee any performance when more than 200 OAuth clients are registered either via client

host: www.iwelcome.com
basePath: /
schemes:
  - https
produces:
  - application/json
securityDefinitions:
  OAuth2:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://example-domain-uri.com/auth/oauth2.0/v1/authorize'
    tokenUrl: 'https://example-domain-uri.com/auth/oauth2.0/v1/token'
    scopes:
      dynamic-client-registration: Scope needed in order to register a new oauth2 client and delete one.
paths:
  '/auth/oauth2.0/v1/connect/register':
    post:
      security:
        - OAuth2: [ 'dynamic-client-registration' ]
      tags:
        - OIDC Client
      summary: >-
        Register an application as a client to iWelcome as an OP (OpenID Provider) (a.k.a. OAuth Authorisation Server).
      description: >-
        The client registration endpoint is an OAuth 2.0 endpoint defined in OpenID Connect Dynamic Client Registration 1.0
        specification that is designed to allow a client to be registered with the authorization server.
        iWelcome's initial implementation supports a limited set of client metadata. iWelcome ignores any client
        metadata sent by the client that it does not understand.

        **Security**

        The client registration endpoint is protected by a transport-layer security mechanism.
        The client registration endpoint is a protected endpoint; clients need to provide a valid access_token.
        The access_token needs to have a scope 'dynamic-client-registration'.
      operationId: registerClient
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: Authorization
          in: header
          description: Bearer <access_token>
          required: true
          type: string
        - in: body
          name: clientRequest
          description: The client payload
          required: true
          schema:
            $ref: '#/definitions/ClientRegistrationRequest'
      responses:
        '201':
          description: Successfully created a new client.
          schema:
            $ref: '#/definitions/ClientRegistrationResponse'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: No valid access token was provided
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: The access token doesn't have scope 'dynamic-client-registration'.
          schema:
            $ref: '#/definitions/ErrorResponse'
    get:
      tags:
        - OIDC Client
      summary: Get details for an OIDC client
      description: >-
        To read the current configuration of the client on the authorization
        server, the client makes an HTTP GET request to the client
        configuration endpoint, authenticating with its registration access
        token.
      operationId: getClient
      produces:
        - application/json
      parameters:
        - name: Authorization
          in: header
          description: Bearer <access_token>
          required: true
          type: string
        - in: query
          name: client_id
          description: The client id
          required: true
          type: string
      responses:
        '200':
          description: Successfully retrived client.
          schema:
            $ref: '#/definitions/ClientInfoResponse'
        '400':
          description: Bad requesst
          schema:
            $ref: '#/definitions/ErrorResponse'
  '/auth/oauth2.0/v1/connect/register/{client_id}':
    delete:
      tags:
        - OIDC Client
      summary: Unregister an OIDC client
      description: >-
        To deprovision itself on the authorization server, the client makes an HTTP DELETE request to the client
        configuration endpoint.  This request is authenticated by the registration access token issued to the client
      operationId: unregisterClient
      parameters:
        - name: Authorization
          in: header
          description: Bearer <registration_access_token>
          required: true
          type: string
        - in: path
          name: client_id
          description: The client id
          required: true
          type: string
      responses:
        '204':
          description: If the client has been successfully deprovisioned.
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'
  '/auth/oauth2.0/v1/connect/clients/{client_id}':
    delete:
      security:
        - OAuth2: [ 'dynamic-client-registration' ]
      tags:
        - Oauth2 Client Admin
      summary: Delete an OIDC client
      description: >-
        Admin endpoint for deprovisioning a client on the authorization server. An admin makes an HTTP DELETE request to the client configuration endpoint.

        **Security**

        The client registration endpoint is protected by a transport-layer security mechanism.
        The client registration endpoint is a protected endpoint; clients need to provide a valid access_token.
        The access_token needs to have a scope 'dynamic-client-registration' to be authorised to delete
      operationId: deleteClient
      parameters:
        - name: Authorization
          in: header
          description: Bearer <access_token>
          required: true
          type: string
        - in: path
          name: client_id
          description: The client id
          required: true
          type: string
      responses:
        '204':
          description: If the client has been successfully deprovisioned.
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'
definitions:
  ClientRegistrationRequest:
    type: object
    properties:
      application_type:
        $ref: '#/definitions/ApplicationType'
      client_id:
        $ref: '#/definitions/ClientId'
      client_name:
        $ref: '#/definitions/ClientName'
      client_type:
        $ref: '#/definitions/ClientType'
      code_challenge_method:
        $ref: '#/definitions/CodeChallengeMethod'
      contacts:
        type: array
        items:
          $ref: '#/definitions/Contact'
      default_scopes:
        type: array
        items:
          $ref: '#/definitions/DefaultScope'
      default_max_age:
        $ref: '#/definitions/DefaultMaxAge'
      grant_types:
        type: array
        items:
          $ref: '#/definitions/GrantType'
      id_token_signed_response_alg:
        $ref: '#/definitions/IdTokenSignedResponseAlg'
      logo_uri:
        $ref: '#/definitions/LogoUri'
      jwks:
        $ref: '#/definitions/Jwks'
      jwks_uri:
        $ref: '#/definitions/JwksUri'
      response_types:
        type: array
        items:
          $ref: '#/definitions/ResponseType'
      redirect_uris:
        type: array
        items:
          $ref: '#/definitions/RedirectUri'
      post_logout_redirect_uris:
        type: array
        items:
          $ref: '#/definitions/PostLogoutRedirectUri'
      default_post_logout_redirect_uri:
        $ref: '#/definitions/DefaultPostLogoutRedirectUri'
      scopes:
        type: array
        items:
          $ref: '#/definitions/SingleScope'
      subject_type:
        $ref: '#/definitions/SubjectType'
      sector_identifier_uri:
        $ref: '#/definitions/SectorIdentifierUri'
      token_endpoint_auth_method:
        $ref: '#/definitions/TokenEndpointAuthMethod'
      x509:
        $ref: '#/definitions/X509Certificate'
  ClientInfoResponse:
    type: object
    properties:
      application_type:
        $ref: '#/definitions/ApplicationType'
      client_id:
        $ref: '#/definitions/ClientId'
      client_name:
        $ref: '#/definitions/ClientName'
      client_type:
        $ref: '#/definitions/ClientType'
      client_secret:
        $ref: '#/definitions/ClientSecret'
      client_secret_expires_at:
        $ref: '#/definitions/ClientSecretExpiresAt'
      code_challenge_method:
        $ref: '#/definitions/CodeChallengeMethod'
      contacts:
        type: array
        items:
          $ref: '#/definitions/Contact'
      default_scopes:
        type: array
        items:
          $ref: '#/definitions/DefaultScope'
      default_max_age:
        $ref: '#/definitions/DefaultMaxAge'
      id_token_signed_response_alg:
        $ref: '#/definitions/IdTokenSignedResponseAlg'
      jwks:
        $ref: '#/definitions/Jwks'
      jwks_uri:
        $ref: '#/definitions/JwksUri'
      response_types:
        type: array
        items:
          $ref: '#/definitions/ResponseType'
      redirect_uris:
        type: array
        items:
          $ref: '#/definitions/RedirectUri'
      post_logout_redirect_uris:
        type: array
        items:
          $ref: '#/definitions/PostLogoutRedirectUri'
      default_post_logout_redirect_uri:
        $ref: '#/definitions/DefaultPostLogoutRedirectUri'
      logo_uri:
        $ref: '#/definitions/LogoUri'
      scopes:
        type: array
        items:
          $ref: '#/definitions/SingleScope'
      subject_type:
        $ref: '#/definitions/SubjectType'
      token_endpoint_auth_method:
        $ref: '#/definitions/TokenEndpointAuthMethod'
      x509:
        $ref: '#/definitions/X509Certificate'
  ClientRegistrationResponse:
    type: object
    properties:
      application_type:
        $ref: '#/definitions/ApplicationType'
      client_id:
        $ref: '#/definitions/ClientId'
      client_name:
        $ref: '#/definitions/ClientName'
      client_type:
        $ref: '#/definitions/ClientType'
      client_secret:
        $ref: '#/definitions/ClientSecret'
      code_challenge_method:
        $ref: '#/definitions/CodeChallengeMethod'
      client_secret_expires_at:
        $ref: '#/definitions/ClientSecretExpiresAt'
      contacts:
        type: array
        items:
          $ref: '#/definitions/Contact'
      default_scopes:
        type: array
        items:
          $ref: '#/definitions/DefaultScope'
      default_max_age:
        $ref: '#/definitions/DefaultMaxAge'
      id_token_signed_response_alg:
        $ref: '#/definitions/IdTokenSignedResponseAlg'
      jwks:
        $ref: '#/definitions/Jwks'
      jwks_uri:
        $ref: '#/definitions/JwksUri'
      registration_access_token:
        $ref: '#/definitions/RegistrationAccessToken'
      registration_client_uri:
        $ref: '#/definitions/RegistrationClientUri'
      redirect_uris:
        type: array
        items:
          $ref: '#/definitions/RedirectUri'
      post_logout_redirect_uris:
        type: array
        items:
          $ref: '#/definitions/PostLogoutRedirectUri'
      default_post_logout_redirect_uri:
        $ref: '#/definitions/DefaultPostLogoutRedirectUri'
      logo_uri:
        $ref: '#/definitions/LogoUri'
      response_types:
        type: array
        items:
          $ref: '#/definitions/ResponseType'
      scopes:
        type: array
        items:
          $ref: '#/definitions/SingleScope'
      subject_type:
        $ref: '#/definitions/SubjectType'
      token_endpoint_auth_method:
        $ref: '#/definitions/TokenEndpointAuthMethod'
      x509:
        $ref: '#/definitions/X509Certificate'
  ApplicationType:
    type: string
    enum:
      - web
      - native
    description: >-
      OPTIONAL. Kind of the application. The default, if omitted, is web. The defined value is web or native.
      Web Clients using the OAuth Implicit Grant Type MUST only register URLs using the https scheme as redirect_uris,
      they MUST NOT use localhost as the hostname. The Authorization Server MUST verify that all the registered redirect_uris
      conform to these constraints. This prevents sharing a Client ID across different types of Clients.
      A native application is a public client installed and executed on the device used by the resource owner. Protocol data and
      credentials are accessible to the resource owner.
  ClientId:
    type: string
    description: >-
      OPTIONAL. Unique Client Identifier. It MUST NOT be currently valid for any other registered Client.
  ClientName:
    type: string
    description: >-
      OPTIONAL. Human-readable string name of the client to be presented to the end-user during authorization.
      If omitted, iWelcome returns the raw "client_id" as a value for the "client_name". It is RECOMMENDED that clients
      always send this field.
  ClientType:
    type: string
    enum:
      - Confidential
      - Public
    description: >-
      Type of OAuth 2.0 client. Confidential clients can keep their password secret, and are typically web
      apps or other server-based clients. Public clients run the risk of exposing their password to a host or user agent,
      such as rich browser applications or desktop clients. If omitted, Confidential type is specified.
  ClientSecret:
    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, as described in Section 2.3.1 of OAuth 2.0, and for
      the derivation of symmetric encryption key values, as described in Section 10.2 of OpenID Connect Core 1.0
      [OpenID.Core]. It is not needed for Clients selecting a token_endpoint_auth_method of private_key_jwt unless
      symmetric encryption will be used.
  ClientSecretExpiresAt:
    type: integer
    description: >-
      OPTIONAL. 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.
  ClientUri:
    type: string
    description: >-
      OPTIONAL. URL of the home page of the Client. The value of this field MUST point to a valid Web page. If present,
      the server SHOULD display this URL to the End-User in a followable fashion. If desired, representation of this
      Claim in different languages and scripts is represented as described in Section 2.1.
  Contact:
    type: string
    description: >-
      OPTIONAL. String representing way to contact people responsible for this client, typically email address.
      The authorization server MAY make this contact address available to end-users for support requests for the client.
    example: "mary@example.org"
  DefaultMaxAge:
    type: integer
    default: 1
    description:
      OPTIONAL. 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.
  DefaultScope:
    type: string
    description: >-
      OPTIONAL. iWelcome assigns the default scopes to access tokens requested by the associated client_id.
  GrantType:
    type: string
    enum:
      - authorization_code
      - refresh_token
    description: >-
      OPTIONAL. OAuth 2.0 grant type that the client can use at the token endpoint.If the token endpoint is used in the
      grant type, the value of this parameter MUST be the same as the value of the "grant_type" parameter passed to the token
      endpoint defined in the grant type definition. Authorization servers MAY allow for other values as defined in
      the grant type extension process described in OAuth 2.0, Section 4.5. If omitted, the default behavior is that the
      client will use only the "authorization_code" Grant Type.
  IdTokenSignedResponseAlg:
    type: string
    description: >-
      OPTIONAL. JWS alg algorithm [JWA] REQUIRED for signing the ID Token issued to this Client. The value none MUST NOT
      be used as the ID Token alg value unless the Client uses only Response Types that return no ID Token from the
      Authorization Endpoint (such as when only using the Authorization Code Flow). 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].
  JwksUri:
    type: string
    description: >-
      OPTIONAL. URL for the Client's JSON Web Key Set [JWK] document. If the Client signs requests to the Server, it
      contains the signing key(s) the Server uses to validate signatures from the Client. The JWK Set MAY also contain
      the Client's encryption keys(s), which are used by the Server to encrypt responses to the Client. 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.
  Jwks:
    type: string
    description: >-
      OPTIONAL. 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. This
      parameter is intended only to be used by Clients that, for some reason, are unable to use the jwks_uri parameter,
      for instance, by native applications that might not have a location to host the contents of the JWK Set. If a
      Client can use jwks_uri, it MUST NOT use jwks. One significant downside of jwks is that it does not enable key
      rotation (which jwks_uri does, as described in Section 10 of OpenID Connect Core 1.0 [OpenID.Core]). The jwks_uri
      and jwks parameters MUST NOT be used together.
  LogoUri:
    type: string
    description: >-
      OPTIONAL. URL that references a logo for the Client application. If present, the server SHOULD display this image
      to the End-User during approval. The value of this field MUST point to a valid image file. If desired,
      representation of this Claim in different languages and scripts is represented as described in Section 2.1.:
  RedirectUri:
    type: string
    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, with the matching performed as
      described in Section 6.2.1 of [RFC3986] (Simple String Comparison).
    example: "https://client.example.org/callback1"
  PostLogoutRedirectUri:
    type: string
    description: >-
      OPTIONAL. URL supplied by the RP to which it MAY request that the End-User's
      User Agent be redirected using the post_logout_redirect_uri parameter after a logout has been performed.
    example: "https://client.example.org/callback1"
  DefaultPostLogoutRedirectUri:
    type: string
    description: >-
      Indicates where the browser is redirected by default if post_logout_redirect_uri query does not match any of the Post logout redirect uris.
      iWelcome redirects to the configured default.
    example: "https://client.example.org/callback1"
  ResponseType:
    type: string
    enum:
      - code
      - token
      - id_token
      - code token
      - token id_token
      - code id_token
      - code token id_token
      - none
    description: >-
      OPTIONAL. 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.
  RegistrationClientUri:
    type: string
    description: >-
      OPTIONAL. 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.
  RegistrationAccessToken:
    type: string
    description: >-
      OPTIONAL. Registration access token that can be used at the client configuration endpoint to perform subsequent
      operations
      upon the client registration, such as deleting the client.
  SectorIdentifierUri:
    type: string
    description: >-
      OPTIONAL. 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. Please see Section 5. Providers that use
      pairwise sub (subject) values SHOULD utilize the sector_identifier_uri value provided in the Subject Identifier
      calculation for pairwise identifiers.
  SingleScope:
    type: string
    description: >-
      Array containing a list of scope values (as described in Section 3.3 of OAuth 2.0 [RFC6749]) that the client
      can use when requesting access tokens. The semantics of values in this list are service specific. If omitted,
      an authorization server MAY register a client with a default set of scopes.
    example: "authorisation1"
  SubjectType:
    type: string
    enum:
      - public
    description: >-
      OPTIONAL. 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 public.
  TokenEndpointAuthMethod:
    type: string
    enum:
      - client_secret_post
      - client_secret_basic
      - none
      - private_key_jwt
    description: >-
      OPTIONAL. Requested Client Authentication method for the Token Endpoint. The options are client_secret_post,
      client_secret_basic, client_secret_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].
  TokenEndpointAuthSigningAlg:
    type: string
    description: >-
      OPTIONAL. 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.
  CodeChallengeMethod:
    type: string
    description: >-
      OPTIONAL. String describing if client enforces PKCE (Proof of Key for Code Exchange).
      Possible values are:
        none: - PKCE is not enforced upon the client
        any:  - PKCE is enforced but method is selected based on parameter in the request. This mode can be used to be compliant with RFC7636,
               that indicates "plain" to be the default if method is not provided in request.
        S256: - PKCE is enforced with 'S256' method
      If not set, by default it is set to S256.
  X509Certificate:
    type: string
    description: A Base64 encoded X509 certificate, containing the public key, represented as a UTF-8 PEM file, of the key pair for signing the Client Bearer JWT.
  ErrorResponse:
    type: object
    properties:
      error:
        type: string
        description: Error code
      error_description:
        type: string
        description: Additional text description of the error for debugging
    description: >-
      This specification defines the following error codes:
        - invalid_redirect_uri:
         The value of one or more redirect_uris is invalid.
        - invalid_client_metadata: The value of one of the Client Metadata fields is invalid and the server has rejected
         this request. Note that an Authorization Server MAY choose to substitute a valid value for any requested
         parameter of a Client's Metadata.