diff --git a/docs/api/components/responses.yaml b/docs/api/components/responses.yaml index 16241dffc0..dcd11c8a83 100644 --- a/docs/api/components/responses.yaml +++ b/docs/api/components/responses.yaml @@ -15,6 +15,12 @@ Not-found: example: error: not_found reason: no such database "invalid-db" +Unauthorized: + description: User does not have access to resource, or resource does not exist + content: + application/json: + schema: + $ref: ./schemas.yaml#/HTTP-Error Conflict: description: Resource already exists under that name content: @@ -33,12 +39,15 @@ Role: application/json: schema: $ref: ./schemas.yaml#/Role -Invalid-CORS: - description: Origin is not in the approved list of allowed origins +Invalid-CORS-LoginOrigin: + description: Value of `Origin` is not in the approved list of allowed origins in `LoginOrigin` of Sync Gateway bootstrap or database configuration. content: application/json: schema: $ref: ./schemas.yaml#/HTTP-Error + example: + error: "Bad Request" + reason: "No CORS" User-session-information: description: Properties associated with a user session content: diff --git a/docs/api/components/schemas.yaml b/docs/api/components/schemas.yaml index 6ac08dac12..2cd7a83bce 100644 --- a/docs/api/components/schemas.yaml +++ b/docs/api/components/schemas.yaml @@ -390,25 +390,42 @@ User-session-information: type: object properties: authentication_handlers: - description: The ways authentication can be established to authenticate as the user. + description: The ways authentication can be established to authenticate as a user. Used for CouchDB compatibility. Always contains "default" and "cookie". type: array - items: - type: string + enum: + - ["default", "cookie"] + default: ["default", "cookie"] ok: + description: Used for CouchDB compatibility. Always true. type: boolean + enum: + - true userCtx: type: object properties: channels: - description: | - A map of the channels the user has access to and the sequence number each channel was created at. - - The key is the channel name and the value is the sequence number. + description: A map of the channels in the default collection that the user is in along with the sequence number the user was granted access. This does not include inherited channels through roles. type: object + additionalProperties: + x-additionalPropertiesName: channelName + type: number + minimum: 1 + description: The sequence number the user was granted access. + title: sequence number + example: + "!": 1 + "channelA": 2 name: description: The name of the user. type: string - nullable: true + minLength: 1 + required: + - channels + - name + required: + - authentication_handlers + - ok + - userCtx title: User Session Information OIDC-callback: type: object @@ -1162,24 +1179,10 @@ Database: type: number default: 1 cors: - description: CORS configuration for this database; if present, overrides server's config. - type: object - properties: - headers: - description: List of allowed headers - type: array - items: - type: string - login_origin: - description: List of allowed login origins - type: array - items: - type: string - origin: - description: 'List of allowed origins, use [''*''] to allow access from everywhere' - type: array - items: - type: string + allOf: + - $ref: "#/CORS" + - type: object + description: CORS configuration for this database; if present, overrides server's config. delta_sync: description: |- Delta sync configuration settings. @@ -2124,26 +2127,10 @@ Startup-config: type: boolean default: true cors: - type: object - properties: - headers: - description: List of allowed headers - type: array - items: - type: string - login_origin: - description: List of allowed login origins - type: array - items: - type: string - max_age: - description: Maximum age of the CORS Options request - type: integer - origin: - description: 'List of allowed origins, use [''*''] to allow access from everywhere' - type: array - items: - type: string + allOf: + - type: object + description: CORS configuration for all databases + - $ref: "#/CORS" enable_advanced_auth_dp: description: |- Whether to enable the DP permissions check feature of admin auth. @@ -3183,3 +3170,42 @@ IndexInitStatus: - last_error - index_status title: IndexInitStatus +CORS: + type: object + properties: + headers: + description: |- + List of allowed headers. These headers will be added the `Access-Control-Allow-Headers` response to a valid CORS request. + + A recommended minimum set of values should be `["Accept-Encoding", "Authorization", "Content-Type", "If-Match"]`. + type: array + items: + type: string + example: + - Accept-Encoding + - Authorization + - Content-Type + - If-Match + login_origin: + description: |- + List of allowed origins to apply to public `/{db}/_session` API. + + To use cors on `/{db}/_session`, the domain must be present in both `login_origin` and `origin`. + + If configured, `Authorization` must be included in headers. + type: array + items: + type: string + example: ["https://example.com"] + max_age: + description: Value for `Access-Control-Maximum-Age`. Uses 0 by default. + type: integer + default: 0 + origin: + description: |- + List of allowed origins for the public API. The request `Origin` header is checked against these values. If successful the `Origin` header is returned in the HTTP response header as `Access-Control-Allow-Origin`. + type: array + items: + type: string + example: ["https://example.com"] + title: Cors Configuration diff --git a/docs/api/paths/admin/db-_facebook.yaml b/docs/api/paths/admin/db-_facebook.yaml index 592be49aa4..ccdb927837 100644 --- a/docs/api/paths/admin/db-_facebook.yaml +++ b/docs/api/paths/admin/db-_facebook.yaml @@ -12,7 +12,7 @@ post: description: |- Creates a new session based on a Facebook user. On a successful session creation, a session cookie is stored to keep the user authenticated for future API calls. - If CORS is enabled, the origin must match an allowed login origin otherwise an error will be returned. + If `Origin` header is passed to this endpoint, the `Origin` header must match both the `cors.login_origin` and `cors.origin` configuration options. requestBody: content: application/json: @@ -28,7 +28,7 @@ post: '200': description: Session created successfully '400': - $ref: ../../components/responses.yaml#/Invalid-CORS + $ref: ../../components/responses.yaml#/Invalid-CORS-LoginOrigin '401': description: Received error from Facebook verifier content: diff --git a/docs/api/paths/admin/db-_google.yaml b/docs/api/paths/admin/db-_google.yaml index 82560cab8e..1f1f0318e8 100644 --- a/docs/api/paths/admin/db-_google.yaml +++ b/docs/api/paths/admin/db-_google.yaml @@ -12,7 +12,7 @@ post: description: |- Creates a new session based on a Google user. On a successful session creation, a session cookie is stored to keep the user authenticated for future API calls. - If CORS is enabled, the origin must match an allowed login origin otherwise an error will be returned. + If `Origin` header is passed to this endpoint, the `Origin` header must match both the `cors.login_origin` and `cors.origin` configuration options. requestBody: content: application/json: @@ -28,7 +28,7 @@ post: '200': description: Session created successfully '400': - $ref: ../../components/responses.yaml#/Invalid-CORS + $ref: ../../components/responses.yaml#/Invalid-CORS-LoginOrigin '401': description: Received error from Google token verifier or invalid application ID in the config content: diff --git a/docs/api/paths/admin/db-_session.yaml b/docs/api/paths/admin/db-_session.yaml index 2eca1dc5c2..4b16c6222c 100644 --- a/docs/api/paths/admin/db-_session.yaml +++ b/docs/api/paths/admin/db-_session.yaml @@ -65,10 +65,17 @@ post: session_id: c5af80a039db4ed9d2b6865576b6999935282689 expires: '2022-01-21T15:24:44Z' cookie_name: SyncGatewaySession - '400': - $ref: ../../components/responses.yaml#/Invalid-CORS + "401": + $ref: ../../components/responses.yaml#/Unauthorized '404': - $ref: ../../components/responses.yaml#/Not-found + description: Return if database does not exist + content: + application/json: + schema: + $ref: ../../components/schemas.yaml#/HTTP-Error + example: + error: not_found + reason: no such database "invalid-db" tags: - Session operationId: post_db-_session diff --git a/docs/api/paths/public/db-_facebook.yaml b/docs/api/paths/public/db-_facebook.yaml index 592be49aa4..ccdb927837 100644 --- a/docs/api/paths/public/db-_facebook.yaml +++ b/docs/api/paths/public/db-_facebook.yaml @@ -12,7 +12,7 @@ post: description: |- Creates a new session based on a Facebook user. On a successful session creation, a session cookie is stored to keep the user authenticated for future API calls. - If CORS is enabled, the origin must match an allowed login origin otherwise an error will be returned. + If `Origin` header is passed to this endpoint, the `Origin` header must match both the `cors.login_origin` and `cors.origin` configuration options. requestBody: content: application/json: @@ -28,7 +28,7 @@ post: '200': description: Session created successfully '400': - $ref: ../../components/responses.yaml#/Invalid-CORS + $ref: ../../components/responses.yaml#/Invalid-CORS-LoginOrigin '401': description: Received error from Facebook verifier content: diff --git a/docs/api/paths/public/db-_google.yaml b/docs/api/paths/public/db-_google.yaml index 82560cab8e..1f1f0318e8 100644 --- a/docs/api/paths/public/db-_google.yaml +++ b/docs/api/paths/public/db-_google.yaml @@ -12,7 +12,7 @@ post: description: |- Creates a new session based on a Google user. On a successful session creation, a session cookie is stored to keep the user authenticated for future API calls. - If CORS is enabled, the origin must match an allowed login origin otherwise an error will be returned. + If `Origin` header is passed to this endpoint, the `Origin` header must match both the `cors.login_origin` and `cors.origin` configuration options. requestBody: content: application/json: @@ -28,7 +28,7 @@ post: '200': description: Session created successfully '400': - $ref: ../../components/responses.yaml#/Invalid-CORS + $ref: ../../components/responses.yaml#/Invalid-CORS-LoginOrigin '401': description: Received error from Google token verifier or invalid application ID in the config content: diff --git a/docs/api/paths/public/db-_session.yaml b/docs/api/paths/public/db-_session.yaml index cb74035354..e0a839d72a 100644 --- a/docs/api/paths/public/db-_session.yaml +++ b/docs/api/paths/public/db-_session.yaml @@ -11,10 +11,10 @@ get: summary: Get information about the current user description: This will get the information about the current user. responses: - '200': + "200": $ref: ../../components/responses.yaml#/User-session-information - '404': - $ref: ../../components/responses.yaml#/Not-found + "401": + $ref: ../../components/responses.yaml#/Unauthorized tags: - Session operationId: get_db-_session @@ -23,69 +23,29 @@ post: description: |- Generates a login session for the user based on the credentials provided in the request body or if that fails (due to invalid credentials or none provided at all), generates the new session for the currently authenticated user instead. On a successful session creation, a session cookie is stored to keep the user authenticated for future API calls. - If CORS is enabled, the origin must match an allowed login origin otherwise an error will be returned. + If `Origin` header is passed to this endpoint, the `Origin` header must match both the `cors.login_origin` and `cors.origin` configuration options. requestBody: - description: The body can depend on if using the Public or Admin APIs. + description: When name and password are included in the request body, the session will be created for the specified user. Otherwise the session will be created for the authenticated user making the request. + required: false content: application/json: schema: type: object + title: "User Credentials" properties: name: - description: User name to generate the session for. + description: User name to generate the session for. Omit this value to generate a session for the authenticated user. type: string password: - description: Password of the user to generate the session for. + description: Password of the user to generate the session for. Omit this value to generate a session for the authenticated user. type: string responses: - '200': - description: Session created successfully. Returned body is dependant on if using Public or Admin APIs - content: - application/json: - schema: - type: object - properties: - authentication_handlers: - description: Used for CouchDB compatability. Always contains "default" and "cookie". - type: array - items: - type: string - enum: - - default - - cookie - ok: - description: Used for CouchDB compatability. Always true. - type: boolean - default: true - userCtx: - type: object - properties: - channels: - description: A map of the channels the user is in along with the sequence number the user was granted access. - type: object - additionalProperties: - type: number - minimum: 1 - description: The sequence number the user was granted access. - title: sequence number - example: - "!": 1 - "channelA": 2 - name: - description: The name of the user. - type: string - minLength: 1 - required: - - channels - - name - required: - - authentication_handlers - - ok - - userCtx - '400': - $ref: ../../components/responses.yaml#/Invalid-CORS - '404': - $ref: ../../components/responses.yaml#/Not-found + "200": + $ref: ../../components/responses.yaml#/User-session-information + "400": + $ref: ../../components/responses.yaml#/Invalid-CORS-LoginOrigin + "401": + $ref: ../../components/responses.yaml#/Unauthorized tags: - Session operationId: post_db-_session @@ -94,14 +54,24 @@ delete: description: |- Invalidates the session for the currently authenticated user and removes their session cookie. - If CORS is enabled, the origin must match an allowed login origin otherwise an error will be returned. + If `Origin` header is passed to this endpoint, the `Origin` header must match both the `cors.login_origin` and `cors.origin` configuration options. responses: - '200': + "200": description: Successfully removed session (logged out) - '400': - description: Bad Request - '404': - $ref: ../../components/responses.yaml#/Not-found + "400": + $ref: ../../components/responses.yaml#/Invalid-CORS-LoginOrigin + "401": + $ref: ../../components/responses.yaml#/Unauthorized + "404": + description: Return if session not found. + content: + application/json: + schema: + $ref: ../../components/schemas.yaml#/HTTP-Error + example: + error: not_found + reason: no session + tags: - Session operationId: delete_db-_session