AG-1442: Add SCIM API docs

This commit is contained in:
Ivan Californias 2022-07-27 20:49:53 -05:00
parent a34c66dc6d
commit 5202184cc0
1 changed files with 774 additions and 0 deletions

View File

@ -100,6 +100,10 @@ tags:
description: |
The repository endpoints allow you to manage your repository's
configuration like description.
- name: scim
x-displayName: SCIM
description: |
Endpoints for SCIM integrations.
x-tagGroups:
- name: General
tags:
@ -113,6 +117,7 @@ x-tagGroups:
- audit-logs
- org-settings
- repositories
- scim
paths:
/v2/users/login:
post:
@ -875,6 +880,267 @@ paths:
response:
value:
detail: Object not found
/v2/scim/2.0/ServiceProviderConfig:
get:
summary: Get service provider config
description: |
Returns a service provider config for Docker's configuration.
tags: [ scim ]
security:
- bearerSCIMAuth: [ ]
responses:
200:
$ref: '#/components/responses/scim_get_service_provider_config_resp'
401:
$ref: "#/components/responses/scim_unauthorized"
500:
$ref: "#/components/responses/scim_error"
/v2/scim/2.0/ResourceTypes:
get:
summary: List resource types
description: |
Returns all resource types supported for the SCIM configuration.
tags: [ scim ]
security:
- bearerSCIMAuth: [ ]
responses:
200:
$ref: "#/components/responses/scim_get_resource_types_resp"
401:
$ref: "#/components/responses/scim_unauthorized"
500:
$ref: "#/components/responses/scim_error"
/v2/scim/2.0/ResourceTypes/{name}:
get:
summary: Get a resource type
description: |
Returns a resource type by name.
tags: [ scim ]
parameters:
- name: name
in: path
schema:
type: string
example: User
security:
- bearerSCIMAuth: [ ]
responses:
200:
$ref: "#/components/responses/scim_get_resource_type_resp"
401:
$ref: "#/components/responses/scim_unauthorized"
404:
$ref: "#/components/responses/scim_not_found"
500:
$ref: "#/components/responses/scim_error"
/v2/scim/2.0/Schemas:
get:
summary: List schemas
description: |
Returns all schemas supported for the SCIM configuration.
tags: [ scim ]
security:
- bearerSCIMAuth: [ ]
responses:
200:
$ref: "#/components/responses/scim_get_schemas_resp"
401:
$ref: "#/components/responses/scim_unauthorized"
500:
$ref: "#/components/responses/scim_error"
/v2/scim/2.0/Schemas/{id}:
get:
summary: Get a schema
description: |
Returns a schema by ID.
tags: [ scim ]
parameters:
- name: id
in: path
schema:
type: string
example: urn:ietf:params:scim:schemas:core:2.0:User
security:
- bearerSCIMAuth: [ ]
responses:
200:
$ref: "#/components/responses/scim_get_schema_resp"
401:
$ref: "#/components/responses/scim_unauthorized"
404:
$ref: "#/components/responses/scim_not_found"
500:
$ref: "#/components/responses/scim_error"
/v2/scim/2.0/Users:
get:
summary: List users
description: |
Returns paginated users for an organization. Use `startIndex` and
`count` query parameters to receive paginated results.
**Sorting:**<br>
Sorting allows you to specify the order in which resources are returned
by specifying a combination of `sortBy` and `sortOrder` query
parameters.
The `sortBy` parameter specifies the attribute whose value will be used
to order the returned responses. The `sortOrder` parameter defines the
order in which the `sortBy` parameter is applied. Allowed values are
"ascending" and "descending".
**Filtering:**<br>
You can request a subset of resources by specifying the `filter` query
parameter containing a filter expression. Attribute names and attribute
operators used in filters are case insensitive. The filter parameter
must contain at least one valid expression. Each expression must contain
an attribute name followed by an attribute operator and an optional
value.
Supported operators are listed below.
- `eq` equal
- `ne` not equal
- `co` contains
- `sw` starts with
- `and` Logical "and"
- `or` Logical "or"
- `not` "Not" function
- `()` Precedence grouping
tags: [ scim ]
security:
- bearerSCIMAuth: [ ]
parameters:
- name: startIndex
in: query
schema:
type: integer
minimum: 1
description: ""
example: 1
- name: count
in: query
schema:
type: integer
minimum: 1
maximum: 200
description: ""
example: 10
- name: filter
in: query
schema:
type: string
description: ""
example: userName eq "jon.snow@docker.com"
- $ref: "#/components/parameters/scim_attributes"
- name: sortOrder
in: query
schema:
type: string
enum:
- ascending
- descending
- name: sortBy
in: query
schema:
type: string
description: "User attribute to sort by."
example: userName
responses:
200:
$ref: "#/components/responses/scim_get_users_resp"
400:
$ref: "#/components/responses/scim_bad_request"
401:
$ref: "#/components/responses/scim_unauthorized"
403:
$ref: "#/components/responses/scim_forbidden"
404:
$ref: "#/components/responses/scim_not_found"
500:
$ref: "#/components/responses/scim_error"
post:
summary: Create user
description: |
Creates a user. If the user already exists by email, they are assigned
to the organization on the "company" team.
tags: [ scim ]
security:
- bearerSCIMAuth: [ ]
requestBody:
$ref: "#/components/requestBodies/scim_create_user_request"
responses:
201:
$ref: "#/components/responses/scim_create_user_resp"
400:
$ref: "#/components/responses/scim_bad_request"
401:
$ref: "#/components/responses/scim_unauthorized"
403:
$ref: "#/components/responses/scim_forbidden"
404:
$ref: "#/components/responses/scim_not_found"
409:
$ref: "#/components/responses/scim_conflict"
500:
$ref: "#/components/responses/scim_error"
/v2/scim/2.0/Users/{id}:
parameters:
- $ref: "#/components/parameters/scim_user_id"
get:
summary: Get a user
description: |
Returns a user by ID.
tags: [ scim ]
security:
- bearerSCIMAuth: [ ]
responses:
200:
$ref: "#/components/responses/scim_get_user_resp"
400:
$ref: "#/components/responses/scim_bad_request"
401:
$ref: "#/components/responses/scim_unauthorized"
403:
$ref: "#/components/responses/scim_forbidden"
404:
$ref: "#/components/responses/scim_not_found"
500:
$ref: "#/components/responses/scim_error"
put:
summary: Update a user
description: |
Updates a user. This route is used to change the user's name, activate,
and deactivate the user.
tags: [ scim ]
security:
- bearerSCIMAuth: [ ]
requestBody:
$ref: "#/components/requestBodies/scim_update_user_request"
responses:
200:
$ref: "#/components/responses/scim_update_user_resp"
400:
$ref: "#/components/responses/scim_bad_request"
401:
$ref: "#/components/responses/scim_unauthorized"
403:
$ref: "#/components/responses/scim_forbidden"
404:
$ref: "#/components/responses/scim_not_found"
409:
$ref: "#/components/responses/scim_conflict"
500:
$ref: "#/components/responses/scim_error"
servers:
- url: https://hub.docker.com/
components:
@ -903,6 +1169,180 @@ components:
application/json:
schema:
$ref: "#/components/schemas/Error"
scim_bad_request:
description: Bad Request
content:
application/scim+json:
schema:
allOf:
- $ref: "#/components/schemas/scim_error"
- properties:
status:
example: "400"
scimType:
type: string
description: Some types of errors will return this per the
specification.
scim_unauthorized:
description: Unauthorized
content:
application/scim+json:
schema:
allOf:
- $ref: "#/components/schemas/scim_error"
- properties:
status:
example: "401"
scim_forbidden:
description: Forbidden
content:
application/scim+json:
schema:
allOf:
- $ref: "#/components/schemas/scim_error"
- properties:
status:
example: "403"
scim_not_found:
description: Not Found
content:
application/scim+json:
schema:
allOf:
- $ref: "#/components/schemas/scim_error"
- properties:
status:
example: "404"
scim_conflict:
description: Conflict
content:
application/scim+json:
schema:
allOf:
- $ref: "#/components/schemas/scim_error"
- properties:
status:
example: "409"
scim_error:
description: Internal Error
content:
application/scim+json:
schema:
allOf:
- $ref: "#/components/schemas/scim_error"
- properties:
status:
example: "500"
scim_get_service_provider_config_resp:
description: ""
content:
application/scim+json:
schema:
$ref: "#/components/schemas/scim_service_provider_config"
scim_get_resource_types_resp:
description: ""
content:
application/scim+json:
schema:
type: object
properties:
schemas:
type: array
items:
type: string
example: [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ]
totalResults:
type: integer
example: 1
resources:
type: array
items:
$ref: "#/components/schemas/scim_resource_type"
scim_get_resource_type_resp:
description: ""
content:
application/scim+json:
schema:
$ref: "#/components/schemas/scim_resource_type"
scim_get_schemas_resp:
description: ""
content:
application/scim+json:
schema:
type: object
properties:
schemas:
type: array
items:
type: string
example: [ urn:ietf:params:scim:api:messages:2.0:ListResponse ]
totalResults:
type: integer
example: 1
resources:
type: array
items:
$ref: "#/components/schemas/scim_schema"
scim_get_schema_resp:
description: ""
content:
application/scim+json:
schema:
$ref: "#/components/schemas/scim_schema"
scim_get_users_resp:
description: ""
content:
application/scim+json:
schema:
type: object
properties:
schemas:
type: array
items:
type: string
example: [ urn:ietf:params:scim:api:messages:2.0:ListResponse ]
totalResults:
type: integer
example: 1
startIndex:
type: integer
example: 1
itemsPerPage:
type: integer
example: 10
resources:
type: array
items:
$ref: "#/components/schemas/scim_user"
scim_create_user_resp:
description: ""
content:
application/scim+json:
schema:
$ref: "#/components/schemas/scim_user"
scim_get_user_resp:
description: ""
content:
application/scim+json:
schema:
$ref: "#/components/schemas/scim_user"
scim_update_user_resp:
description: ""
content:
application/scim+json:
schema:
$ref: "#/components/schemas/scim_user"
schemas:
UsersLoginRequest:
description: User login details
@ -1619,3 +2059,337 @@ components:
Hello from Docker!
This message shows that your installation appears to be working correctly.
```
scim_error:
type: object
properties:
status:
type: string
description: The status code for the response in string format.
schemas:
type: array
items:
type: string
default: urn:ietf:params:scim:api:messages:2.0:Error
detail:
type: string
description: Details about why the request failed.
scim_service_provider_config:
type: object
properties:
schemas:
type: array
items:
type: string
example: [ "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig" ]
documentationUri:
type: string
example: ""
patch:
properties:
supported:
type: boolean
example: false
bulk:
type: object
properties:
supported:
type: boolean
example: false
maxOperations:
type: integer
maxPayloadSize:
type: integer
filter:
type: object
properties:
supported:
type: boolean
example: true
maxResults:
type: integer
example: 99999
changePassword:
type: object
properties:
supported:
type: boolean
example: false
sort:
type: object
properties:
supported:
type: boolean
example: true
etag:
type: object
properties:
supported:
type: boolean
example: false
authenticationSchemes:
type: object
properties:
name:
type: string
example: OAuth 2.0 Bearer Token
description:
type: string
example: The OAuth 2.0 Bearer Token Authentication scheme. OAuth enables clients to access protected resources by obtaining an access token, which is defined in RFC 6750 as "a string representing an access authorization issued to the client", rather than using the resource owner's credentials directly.
specUri:
type: string
example: "http://tools.ietf.org/html/rfc6750"
type:
type: string
example: oauthbearertoken
scim_resource_type:
type: object
properties:
schemas:
type: array
items:
type: string
example: "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
id:
type: string
example: User
name:
type: string
example: User
description:
type: string
example: User
endpoint:
type: string
example: "/Users"
schema:
type: string
example: "urn:ietf:params:scim:schemas:core:2.0:User"
scim_schema_attribute:
type: object
properties:
name:
type: string
example: userName
type:
enum:
- string
- boolean
- complex
type: string
example: string
multiValued:
type: boolean
example: false
description:
type: string
example: Unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users.
required:
type: boolean
example: true
caseExact:
type: boolean
example: false
mutability:
type: string
example: readWrite
returned:
type: string
example: default
uniqueness:
type: string
example: server
scim_schema_parent_attribute:
allOf:
- $ref: "#/components/schemas/scim_schema_attribute"
- type: object
properties:
subAttributes:
type: array
items:
$ref: "#/components/schemas/scim_schema_attribute"
scim_schema:
type: object
properties:
schemas:
type: array
items:
type: string
example: [ urn:ietf:params:scim:schemas:core:2.0:Schema ]
id:
type: string
example: urn:ietf:params:scim:schemas:core:2.0:User
name:
type: string
example: User
description:
type: string
example: User Account
attributes:
type: array
example: [ ]
items:
$ref: "#/components/schemas/scim_schema_parent_attribute"
scim_email:
type: object
properties:
value:
type: string
example: jon.snow@docker.com
display:
type: string
example: jon.snow@docker.com
primary:
type: boolean
example: true
scim_group:
type: object
properties:
value:
type: string
example: "nightswatch"
display:
type: string
example: "nightswatch"
scim_user_username:
type: string
description: The user's email address. This must be reachable via email.
example: jon.snow@docker.com
scim_user_name:
type: object
properties:
givenName:
type: string
example: Jon
familyName:
type: string
example: Snow
scim_user_display_name:
type: string
description: The username in Docker. Also known as the "Docker ID".
example: jonsnow
scim_user_schemas:
type: array
items:
type: string
example: "urn:ietf:params:scim:schemas:core:2.0:User"
minItems: 1
scim_user_id:
type: string
example: d80f7c79-7730-49d8-9a41-7c42fb622d9c
description: The unique identifier for the user. A v4 UUID.
scim_user:
type: object
properties:
schemas:
$ref: "#/components/schemas/scim_user_schemas"
id:
$ref: "#/components/schemas/scim_user_id"
userName:
$ref: "#/components/schemas/scim_user_username"
name:
$ref: "#/components/schemas/scim_user_name"
displayName:
$ref: "#/components/schemas/scim_user_display_name"
active:
type: boolean
example: true
emails:
type: array
items:
$ref: "#/components/schemas/scim_email"
groups:
type: array
items:
$ref: "#/components/schemas/scim_group"
meta:
type: object
properties:
resourceType:
type: string
example: User
location:
type: string
example: https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c
created:
type: string
description: The creation date for the user as a RFC3339 formatted
string.
example: 2022-05-20T00:54:18Z
lastModified:
type: string
description: The date the user was last modified as a RFC3339
formatted string.
example: 2022-05-20T00:54:18Z
parameters:
scim_attributes:
in: query
name: attributes
schema:
type: string
description: Comma delimited list of attributes to limit to in the
response.
example: userName,displayName
scim_user_id:
name: id
in: path
schema:
type: string
description: The user ID.
example: "d80f7c79-7730-49d8-9a41-7c42fb622d9c"
requestBodies:
scim_create_user_request:
required: true
content:
application/scim+json:
schema:
type: object
required:
- schemas
- userName
properties:
schemas:
$ref: "#/components/schemas/scim_user_schemas"
userName:
$ref: "#/components/schemas/scim_user_username"
name:
$ref: "#/components/schemas/scim_user_name"
scim_update_user_request:
required: true
content:
application/scim+json:
schema:
type: object
required:
- schemas
properties:
schemas:
$ref: "#/components/schemas/scim_user_schemas"
name:
allOf:
- $ref: "#/components/schemas/scim_user_name"
- description: If this is omitted from the request, the
update will skip the update on it. We will only ever
change the name, but not clear it.
enabled:
type: boolean
default: false
description: If this is omitted from the request, it will
default to false resulting in a deactivated user.