swagger: '2.0'
info:
title: Identity Management API
description: >-
The Identity Management API provides a means form managing users, groups and OAuth clients.
The user and group management is based on SCIM (System for Cross-domain Identity Management).
Note: 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.
Note2: 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.1.2'
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
Note: Roles and groups are made available under /Groups.
Reserved displayNames: starting with "mdspiam:subtenant:"
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).
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/{groupId}:
get:
tags:
- uiam group
operationId: getGroup
summary: Get group
description: Get details of a group.
Example path /api/identitymanagement/v3/Groups/68af46d-e9b8-4t04-5a20-7d557f5da8d
parameters:
- name: groupId
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.
Example path /api/identitymanagement/v3/Groups/68af46d-e9b8-4t04-5a20-7d557f5da8d
parameters:
- name: groupId
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.
Example path /api/identitymanagement/v3/Groups/68af46d-e9b8-4t04-5a20-7d557f5da8d
parameters:
- name: groupId
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/{groupId}/members:
get:
tags:
- uiam group
operationId: listGroupMembers
summary: >-
List members of a group
description: List the members (both users and groups) of a group.
Example path /api/identitymanagement/v3/Groups/68af46d-e9b8-4t04-5a20-7d557f5da8d/members
parameters:
- name: groupId
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.
Example path /api/identitymanagement/v3/Groups/68af46d-e9b8-4t04-5a20-7d557f5da8d/members
parameters:
- name: groupId
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/{groupId}/members/{memberId}:
delete:
tags:
- uiam group
operationId: removeMemberFromGroup
summary: Delete member from a group
description: Delete member (either user or group) from a group.
Example path /api/identitymanagement/v3/Groups/68af46d-e9b8-4t04-5a20-7d557f5da8d/members/e74ff46d-8bb8-4d04-b420-7d557fe86a8d
parameters:
- name: groupId
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).
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.
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/{userId}:
get:
tags:
- uiam user
operationId: get
summary: >-
Get user
description: >-
Get details of a user.
Example path /api/identitymanagement/v3/Users/2f95913-d3d9-4a4a-951a-c21184080cf3
parameters:
- name: userId
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.
Note: Username must not be changed. Email address is required and must be equal to the username.
Example path /api/identitymanagement/v3/Users/2f95913-d3d9-4a4a-951a-c21184080cf3
parameters:
- name: userId
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.
Note that tenant can have user if it purchased at least the simple offering.
Example path /api/identitymanagement/v3/Users/2f95913-d3d9-4a4a-951a-c21184080cf3
parameters:
- name: userId
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
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:
type: string
description: The e-mail address of the user.
example: johndoe@example.com
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:
type: string
description: The e-mail address of the user.
example: johndoe@example.com
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