openapi: 3.0.3
info:
  title: Access Token Customization Web Hook
  description: A hook that is executed just before the authorization grant is created (authorization call, refresh token)
  version: 1.0.0
servers:
  - url: /
paths:
  /v1/customize-access-token:
    post:
      tags:
        - customize-access-token-web-hook
      operationId: customize-access-token
      description: This webhook is meant for Access Token customization that includes requested scopes reduction as well as adding additional custom claims to JWT formatted token.
      security:
        - basicAuth: [ ]
        - bearerAuth: [ ]
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomizeAccessTokenRequest'
      responses:
        200:
          description: Successful response that informs Access Service about scopes to be excluded from the authorization grant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomizeAccessTokenResponse'
        401:
          description: Response to be returned when API credentials are invalid

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    CustomizeAccessTokenRequest:
      type: object
      description: Data representing the user that is requesting the authorization and also scopes that were requested.
      properties:
        user:
          $ref: '#/components/schemas/User'
        client:
          $ref: '#/components/schemas/Client'
        scopes:
          type: array
          description: The scopes that are requested for the authorization grant.
          example:
            - sim_read
            - name
            - openid
            - read
          items:
            type: string
        userClaims:
          type: object
          additionalProperties: true
          description: All available user-related claims.
        contextCustomParams:
          type: object
          nullable: true
          additionalProperties:
            type: array
            items:
              type: string
          description: "Hook context optional custom parameters, i.e. : 'on_behalf_of', 'on_behalf_of_type'"
      required: [ 'client', 'scopes' ]
    User:
      type: object
      properties:
        id:
          type: string
          example: "fb6239f6-2j3j-4jj5-997-092999923h"
          description: The identifier of a user provided by the identity provider.
      required: [ 'id' ]
    Client:
      type: object
      properties:
        id:
          type: string
          example: "ad731534-b319-4760-ac0e-31c872c6fb7c"
          description: The id of the client that the authorization grant has been requested by.
      required: [ 'id' ]
    CustomizeAccessTokenResponse:
      type: object
      description: Scopes that are expected to be removed from the OAuth grant, the returned list can only be a subset of the one communicated in the request.
      properties:
        removeScopes:
          type: array
          description: The list of scopes to be removed from the OAuth grant.<br/>Restrictions<ul><li>if the list is empty scopes will not be reduced</li><li>if list contains scopes that don't exist then these scopes are ignored</li><li>if all requested scopes are removed, the request is rejected</li></ul>
          items:
            type: string
        additionalClaims:
          type: object
          additionalProperties: true
          description: A list of claims that are intended to be included in the resulting JWT formatted Access Token. All the claims should use a custom prefix to prevent collisions with ones defined by the protocol specification (both OAuth and OIDC). Any conflicting claims will be rejected without breaking the flow and an approparite event will be sent.
      example:
        removeScopes:
          - sim_read
          - name
        additionalClaims:
          basicClaim: example value
          complexClaim:
            userDefinedProperty1: userDefinedValue1
            userDefinedProperty2: userDefinedValue2
