From 5202184cc0ff3f842f7a92d5f6f7a2ea7931dc46 Mon Sep 17 00:00:00 2001 From: Ivan Californias Date: Wed, 27 Jul 2022 20:49:53 -0500 Subject: [PATCH 1/2] AG-1442: Add SCIM API docs --- docker-hub/api/latest.yaml | 774 +++++++++++++++++++++++++++++++++++++ 1 file changed, 774 insertions(+) diff --git a/docker-hub/api/latest.yaml b/docker-hub/api/latest.yaml index 4c6d652a06e2..766df2de6a6a 100644 --- a/docker-hub/api/latest.yaml +++ b/docker-hub/api/latest.yaml @@ -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:**
+ 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:**
+ 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. From 4bae2ec02c92a22d7e0be6962d531e2c2121684f Mon Sep 17 00:00:00 2001 From: Ivan Californias Date: Thu, 28 Jul 2022 20:00:31 -0500 Subject: [PATCH 2/2] Update descriptions from PR comments --- .gitignore | 1 + docker-hub/api/latest.yaml | 14 +++++++------- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/.gitignore b/.gitignore index 66fb99c3ff76..16bba78d6d6d 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,7 @@ .jekyll-metadata _site/** .sass-cache/** +.vscode CNAME _kbase/** /vendor diff --git a/docker-hub/api/latest.yaml b/docker-hub/api/latest.yaml index 766df2de6a6a..3332a3c29fd1 100644 --- a/docker-hub/api/latest.yaml +++ b/docker-hub/api/latest.yaml @@ -103,7 +103,8 @@ tags: - name: scim x-displayName: SCIM description: | - Endpoints for SCIM integrations. + SCIM is a provisioning system that lets you manage users within your identity provider (IdP). + For more information, see [System for Cross-domain Identity management](https://docs.docker.com/docker-hub/scim/). x-tagGroups: - name: General tags: @@ -981,13 +982,12 @@ paths: get: summary: List users description: | - Returns paginated users for an organization. Use `startIndex` and - `count` query parameters to receive paginated results. + List users, returns paginated users for an organization. Use `startIndex` + and `count` query parameters to receive paginated results. **Sorting:**
- Sorting allows you to specify the order in which resources are returned - by specifying a combination of `sortBy` and `sortOrder` query - parameters. + Sorting lets you to specify the order of returned resources 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 @@ -1117,7 +1117,7 @@ paths: put: summary: Update a user description: | - Updates a user. This route is used to change the user's name, activate, + Updates a user. Use this route to change the user's name, activate, and deactivate the user. tags: [ scim ] security: