swagger: '2.0'
info:
  title: Identity Management API
  description: >-
    The Identity Management API provides a means form managing users, groups and OAuth clients.<br>
    The user and group management is based on SCIM (System for Cross-domain Identity Management).<br><br>
    <i>Note:</i> Unless stated otherwise the Identity Management APIs allow each caller only to act within the context of the tenant to which the caller belong's to.</br>

    <i>Note2:</i> UIAM stands for User Identity Access Management, since users and providers are separated in system. Therefore this API documentation is related to users generally.

  version: '3.3.3'
  x-visibility: external
basePath: /api/identitymanagement/v3
tags:
  - name: uiam user
    description: API for Managing Users in a Tenant
  - name: uiam group
    description: API for Managing Roles/Groups & Roles/Group Memberships of Users in a Tenant<br><i>Note:</i> Roles and groups are made available under /Groups.<br>To create the groups in IH, we follow some pattern. Below are the patterns to create the group as per the requirement:<br>Insights Hub user group display name has pattern as mdsp_usergroup:<user group name><br>Custom role's display name has pattern as mdsp_customrole:<role_name><br>Insights Hub core role display name has pattern as mdsp:core:<role_name>

paths:
  /Groups:
    get:
      tags:
        - uiam group
      operationId: listGroups
      summary: List all the groups of a tenant.
      description: List all the groups of a tenant.
      parameters:
        - name: filter
          in: query
          description: "SCIM filter for searching see [here](http://www.simplecloud.info/specs/draft-scim-api-01.html). The available filter attributes are: id, displayname, created or meta.created, lastmodified or meta.lastmodified, version or meta.version"
          required: false
          type: string
        - name: count
          in: query
          description: Number of objects to be returned (defaults to 100)
          type: number
          required: false
          default: 100
        - name: startIndex
          in: query
          type: number
          description: >-
            The starting index of the search results when paginated. Index starts with 1.
          required: false
          default: 1
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ScimGroupSearchResults'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - im_group_auth:
            - 'im.g.r'
    post:
      tags:
        - uiam group
      operationId: createGroup
      summary: Create group
      description: Create a group.
      parameters:
        - in: body
          name: group
          description: Details of group
          required: true
          schema:
            $ref: '#/definitions/ScimGroupPost'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/ScimGroup'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '409':
          description: Conflict
      security:
        - im_group_auth:
            - 'im.g.c'
  /Groups/{id}:
    get:
      tags:
        - uiam group
      operationId: getGroup
      summary: Get group
      description: Get details of a group.<br/>Example path <b>/api/identitymanagement/v3/Groups/68af46d-e9b8-4t04-5a20-7d557f5da8d
      parameters:
        - name: id
          in: path
          description: Id of group
          required: true
          type: string
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ScimGroup'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - im_group_auth:
            - 'im.g.r'
    put:
      tags:
        - uiam group
      operationId: updateGroup
      summary: Update group.
      description: Update details of a group. If any field is left empty or is is omitted, it will be null.<br/>Example path <b>/api/identitymanagement/v3/Groups/68af46d-e9b8-4t04-5a20-7d557f5da8d
      parameters:
        - name: id
          in: path
          description: Id of group
          required: true
          type: string
        - in: body
          name: group
          description: New details
          required: true
          schema:
            $ref: '#/definitions/ScimGroupPost'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ScimGroup'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - im_group_auth:
            - 'im.g.u'
    delete:
      tags:
        - uiam group
      operationId: deleteGroup
      summary: >-
        Delete group
      description: Delete group and every connection to that group, too.<br/>Example path <b>/api/identitymanagement/v3/Groups/68af46d-e9b8-4t04-5a20-7d557f5da8d
      parameters:
        - name: id
          in: path
          description: Id of the group
          required: true
          type: string
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ScimGroup'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - im_group_auth:
            - 'im.g.d'
  /Groups/{id}/members:
    get:
      tags:
        - uiam group
      operationId: listGroupMembers
      summary: >-
        List members of a group
      description: List the members (both users and groups) of a group.<br/>Example path <b>/api/identitymanagement/v3/Groups/68af46d-e9b8-4t04-5a20-7d557f5da8d/members
      parameters:
        - name: id
          in: path
          description: Id of group
          required: true
          type: string
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ScimGroupMemberList'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - im_group_auth:
            - 'im.g.r'
    post:
      tags:
        - uiam group
      operationId: addMemberToGroup
      summary: >-
        Add member to a group
      description: Add new member (either user or group) to an existing group.<br/>Example path <b>/api/identitymanagement/v3/Groups/68af46d-e9b8-4t04-5a20-7d557f5da8d/members
      parameters:
        - name: id
          in: path
          description: Id of group
          required: true
          type: string
        - in: body
          name: member
          description: Details of the new member
          required: true
          schema:
            $ref: '#/definitions/ScimGroupMember'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/ScimGroupMember'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not Found
        '409':
          description: Conflict
      security:
        - im_group_auth:
            - 'im.g.u'
  /Groups/{id}/members/{memberId}:
    delete:
      tags:
        - uiam group
      operationId: removeMemberFromGroup
      summary: Delete member from a group
      description: Delete member (either user or group) from a group.<br/>Example path <b>/api/identitymanagement/v3/Groups/68af46d-e9b8-4t04-5a20-7d557f5da8d/members/e74ff46d-8bb8-4d04-b420-7d557fe86a8d
      parameters:
        - name: id
          in: path
          description: Id of user group
          required: true
          type: string
        - name: memberId
          in: path
          description: Id of member
          required: true
          type: string
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ScimGroupMember'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - im_group_auth:
            - 'im.g.u'
  /Users:
    get:
      tags:
        - uiam user
      operationId: list
      summary: List of users of a tenant.
      description: List of users of a tenant. Please note, in order to request only the list of users (without the information to which group a user belongs) it is recommended to make use of the "attributes" query parameter as follows /Users?attributes=userName,name,meta (this will significantly improve the performance over simply calling /Users).
      parameters:
        - name: filter
          in: query
          description: |
            "SCIM filter for searching see [here](http://www.simplecloud.info/specs/draft-scim-api-01.html). The available filter attributes are: id, username, email or emails.value, givenname, familyname, active, phonenumber, verified, origin, created or meta.created, lastmodified or meta.lastmodified, version or meta.version, groups.display.
            </br>
            <b>Note</b>: <i>groups.display</i> parameter cannot be used in complex filter expression and only <i>eq</i> operator is allowed eg. <i>filter=groups.display eq "MyGroupName"</i>
          required: false
          type: string
        - name: attributes
          in: query
          description: Comma separated list of attribute names to be returned, e.g., userName, name, meta. The attributes parameters does not support the parameter "subtenants".
          required: false
          type: string
        - name: sortBy
          in: query
          description: Sorting field name, like email or id
          required: false
          type: string
        - name: sortOrder
          in: query
          description: Sort order, ascending/descending (defaults to ascending)
          type: string
          required: false
          default: ascending
        - name: count
          in: query
          description: Number of objects to be returned (defaults to 100)
          type: number
          required: false
          default: 100
        - name: startIndex
          in: query
          type: number
          description: The starting index of the search results when paginated. Index starts with 1 (defaults to 1).
          required: false
          default: 1
        - name: subtenant
          in: query
          description: Filter for subtenant users
          type: string
          required: false
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ScimUserResponseSearchResults'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - im_user_auth:
            - 'im.usr.r'
    post:
      tags:
        - uiam user
      operationId: create
      summary: >-
        Create user
      description: >-
        Create a new user in a tenant.<br/><br/>
        <b>Note</b>: The 'subtenants' field is optional. If it is present, the user is considered to be a subtenant user.
      parameters:
        - in: body
          name: user
          description: Details of user
          required: true
          schema:
            $ref: '#/definitions/ScimUserPost'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/ScimUserPostResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
        '409':
          description: Conflict
      security:
        - im_user_auth:
            - 'im.usr.c'
  /Users/{id}:
    get:
      tags:
        - uiam user
      operationId: get
      summary: >-
        Get user
      description: >-
        Get details of a user.<br/>Example path <b>/api/identitymanagement/v3/Users/2f95913-d3d9-4a4a-951a-c21184080cf3
      parameters:
        - name: id
          in: path
          description: Id of user
          required: true
          type: string
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ScimUserResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - im_user_auth:
            - 'im.usr.r'
    put:
      tags:
        - uiam user
      operationId: update
      summary: >-
        Update user
      description: >-
        Update details of user.<br/><br/>
        <b>Note</b>: Username must not be changed. Email address is required and must be equal to the username.<br/>The 'subtenants' field is optional. If it is present, the user is considered to be a subtenant user. Upgrading a subtenant user to a tenant user and vice versa is not allowed.<br/>Example path <b>/api/identitymanagement/v3/Users/2f95913-d3d9-4a4a-951a-c21184080cf3
      parameters:
        - name: id
          in: path
          description: Id of user
          required: true
          type: string
        - in: body
          name: user
          description: New details
          required: true
          schema:
            $ref: '#/definitions/ScimUserPut'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ScimUserResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      security:
        - im_user_auth:
            - 'im.usr.u'
    delete:
      tags:
        - uiam user
      operationId: delete
      summary: >-
        Delete user
      description: >-
        Delete user of tenant.<br/>
        Note that tenant can have user if it purchased at least the <b>simple</b> offering.<br/>Example path <b>/api/identitymanagement/v3/Users/2f95913-d3d9-4a4a-951a-c21184080cf3
      parameters:
        - name: id
          in: path
          description: Id of user
          required: true
          type: string
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ScimUserResponse'
        '401':
          description: Unauthorized
      security:
        - im_user_auth:
            - 'im.usr.d'
  /Users/me:
    get:
      tags:
        - uiam user
      operationId: getUserRoles
      summary: Get list of groups starting with the prefix "mdsp:" in which the user is a member.
      description: Get list of groups starting with the prefix "mdsp:" in which the user is a member.
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/Group'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - im_user_auth:
            - 'im.usr.me'

definitions:
  Email:
    type: object
    required:
      - value
    properties:
      value:
        type: string
        description: The email address.
        example: johndoe@example.com
  Group:
    type: object
    required:
      - display
    properties:
      display:
        type: string
        example: mdsp:core:StandardUser
      type:
        type: string
        enum:
          - DIRECT
          - INDIRECT
        example: DIRECT
      value:
        type: string
        example: 85300c9f-9616-4596-ac1c-1ca837426d7e
  NameRequest:
    type: object
    required:
      - familyName
      - givenName
    properties:
      familyName:
        type: string
        example: Doe
      givenName:
        type: string
        example: John
  UserName:
    type: string
    format: email
    maxLength: 60
    pattern: '^[a-zA-Z0-9._%+&*-]+(?:\.[a-zA-Z0-9_+&*-]+)*@(?:[a-zA-Z0-9-]+\.)+[a-zA-Z]{2,7}$'
    description: The e-mail address of the user.
    example: johndoe@example.com
  NameResponse:
    type: object
    properties:
      familyName:
        type: string
        example: Doe
      givenName:
        type: string
        example: John
  ScimGroupPost:
    type: object
    required:
      - displayName
    properties:
      description:
        type: string
        example: Very amazing group for amazing people
        description: Human readable description of the group, displayed e.g. when approving scopes
      displayName:
        type: string
        example: AmazingGroup
        description: The identifier specified upon creation of the group, unique within the identity zone
      members:
        type: array
        description: If given members array is empty, all members will be deleted.
        items:
          $ref: '#/definitions/ScimGroupMember'
  ScimGroup:
    type: object
    properties:
      id:
        type: string
        example: 68af46d-e9b8-4t04-5a20-7d557f5da8d
        description: The globally unique group ID
      description:
        type: string
        example: Very amazing group for amazing people
        description: Human readable description of the group, displayed e.g. when approving scopes
      displayName:
        type: string
        example: AmazingGroup
        description: The identifier specified upon creation of the group, unique within the identity zone
      members:
        type: array
        items:
          $ref: '#/definitions/ScimGroupMember'
      meta:
        $ref: '#/definitions/ScimMeta'
  ScimGroupMember:
    type: object
    required:
      - type
      - value
    properties:
      type:
        type: string
        enum:
          - USER
          - GROUP
        description: Either "USER" or "GROUP"
        example: USER
      value:
        type: string
        description: Globally unique identifier of the member, either a user ID or another group ID
        example: e74ff46d-8bb8-4d04-b420-7d557fe86a8d
  ScimMeta:
    type: object
    properties:
      created:
        type: string
        format: date-time
        example: "2018-02-08T15:20:43.000Z"
      lastModified:
        type: string
        format: date-time
        example: "2018-02-08T15:20:43.000Z"
      version:
        type: integer
        format: int32
        example: 0
  ScimUserPut:
    type: object
    required:
      - userName
      - name
      - emails
    description: 'Name object can be null. Example: "name": {}. Name attributes are fetched from WebKey during authentication.'
    properties:
      active:
        type: boolean
        description: 'False means a soft delete.'
      name:
        $ref: '#/definitions/NameRequest'
      userName:
        $ref: '#/definitions/UserName'
      emails:
        type: array
        items:
          $ref: '#/definitions/Email'
      subtenants:
        type: array
        items:
          $ref: '#/definitions/SubtenantId'
  ScimUserPost:
    type: object
    required:
      - userName
    properties:
      active:
        type: boolean
        description: 'False means a soft delete.'
      name:
        $ref: '#/definitions/NameRequest'
      userName:
        $ref: '#/definitions/UserName'
      subtenants:
        type: array
        items:
          $ref: '#/definitions/SubtenantId'
  ScimUserResponse:
    type: object
    properties:
      schemas:
        type: array
        items:
          type: string
          example: urn:scim:schemas:core:1.0
      id:
        example: 2f95913-d3d9-4a4a-951a-c21184080cf3
        type: string
      userName:
        type: string
        description: The e-mail address of the user.
        example: johndoe@example.com
      name:
        $ref: '#/definitions/NameResponse'
      groups:
        type: array
        items:
          $ref: '#/definitions/Group'
      emails:
        type: array
        items:
          $ref: '#/definitions/Email'
      active:
        type: boolean
      meta:
        $ref: '#/definitions/ScimMeta'
      subtenants:
        type: array
        items:
          $ref: '#/definitions/SubtenantId'
  ScimUserPostResponse:
    type: object
    properties:
      schemas:
        type: array
        items:
          type: string
          example: urn:scim:schemas:core:1.0
      id:
        example: 2f95913-d3d9-4a4a-951a-c21184080cf3
        type: string
      userName:
        type: string
        description: The e-mail address of the user.
        example: johndoe@example.com
      name:
        $ref: '#/definitions/NameResponse'
      groups:
        type: array
        items:
          $ref: '#/definitions/Group'
        example: []
      emails:
        type: array
        items:
          $ref: '#/definitions/Email'
      active:
        type: boolean
      meta:
        $ref: '#/definitions/ScimMeta'
      subtenants:
        type: array
        items:
          $ref: '#/definitions/SubtenantId'
  ScimGroupMemberList:
    type: array
    items:
      $ref: '#/definitions/ScimGroupMember'
  ScimGroupSearchResults:
    type: object
    properties:
      itemsPerPage:
        type: integer
        format: int32
        example: 100
      resources:
        type: array
        items:
          $ref: '#/definitions/ScimGroup'
      schemas:
        type: array
        items:
          type: string
          example: "urn:scim:schemas:core:1.0"
      startIndex:
        type: integer
        format: int32
        example: 1
      totalResults:
        type: integer
        format: int32
        example: 1
  ScimUserResponseSearchResults:
    type: object
    properties:
      itemsPerPage:
        type: integer
        format: int32
        example: 100
      resources:
        type: array
        items:
          $ref: '#/definitions/ScimUserResponse'
      schemas:
        type: array
        items:
          type: string
      startIndex:
        type: integer
        format: int32
        example: 1
      totalResults:
        type: integer
        format: int32
        example: 1
  SubtenantId:
    type: object
    example:
      id: octopus
    required:
      - id
    properties:
      id:
        type: string
        example: octopus
        description: The ID / name of the subtenant.

securityDefinitions:
  im_user_auth:
    type: oauth2
    flow: accessCode
    description: User controller based scopes
    authorizationUrl: http://UAA_DOMAIN/oauth/authorize
    tokenUrl: http://UAA_DOMAIN/oauth/token
    scopes:
      im.usr.c: Create user
      im.usr.r: See details of user; List users
      im.usr.u: Update details of user
      im.usr.d: Delete user
      im.usr.me: See the assigened roles of the user
  im_group_auth:
    type: oauth2
    flow: accessCode
    description: Group controller based scopes
    authorizationUrl: http://UAA_DOMAIN/oauth/authorize
    tokenUrl: http://UAA_DOMAIN/oauth/token
    scopes:
      im.g.c: UserUaa - Create group
      im.g.r: UserUaa - See details of group; UserUaa - List groups; UserUaa - List members of group
      im.g.u: UserUaa - Update details of group; UserUaa - Add member to group; UserUaa - Remove member of group
      im.g.d: UserUaa - Delete group
