Document cors defaults parms / security overhaul

[janan07]

Describe your pull request here: Document cors defaults parms / security overhaul

List the file(s) included in this PR:

After creating the PR, follow the instructions in the comments.

[github-actions]

😺 Thank you for creating this PR! To publish your content to Zowe Docs, follow these required steps.

• Add the label review: doc.
• Identify your content topic with a label. (Examples: area: apiml, area: cli, area: install and config, etc.)
• Specify the major Zowe release(s) for your content. (Examples: release: V1, release: V2, release: V3)
  • If adding content that needs to be removed from V3 documentation, add the V3 N/A tag.
• Select the master branch if your PR updates content that is on the live site. Select docs-staging if your PR updates content for a future release.
• Notify the Doc Squad about this PR. If you don't know whom should review your content, message the #zowe-doc Slack channel. If you know which Doc Squad writer should approve your content, add that person as a reviewer.

Need help? Contact the Doc Squad in the #zowe-doc Slack channel.

[github-actions]

📁 The PR description is missing the file name(s) for the updated content. List all the files included in this PR so this information displays in our Zowe Docs GitHub Slack channel.

If you have addressed this issue already, refresh this page in your browser to remove this comment.

[github-actions]

📁 The PR description is missing the file name(s) for the updated content. List all the files included in this PR so this information displays in our Zowe Docs GitHub Slack channel.

If you have addressed this issue already, refresh this page in your browser to remove this comment.

[github-actions]

📁 The PR description is missing the file name(s) for the updated content. List all the files included in this PR so this information displays in our Zowe Docs GitHub Slack channel.

If you have addressed this issue already, refresh this page in your browser to remove this comment.

[github-actions]

📁 The PR description is missing the file name(s) for the updated content. List all the files included in this PR so this information displays in our Zowe Docs GitHub Slack channel.

If you have addressed this issue already, refresh this page in your browser to remove this comment.

[github-actions]

🚀 Deployed on https://6a62143144a0451c7e5c79a2--zowe-docs-master.netlify.app

[balhar-jakub]

I believe that the origin remains, only the default changed. So we probably should not remove it.

[pablocarle]

in both cases the request headers do not reach the service, these are response headers though.

if Gateway handles CORS on behalf of the service: if the service provides settings, use them, otherwise global defaults.
if Gateway has CORS handling disabled: global gateway defaults, ignore service requirements.

Allow-Origin: * is not the default nor allowed.

[balhar-jakub]

Just a question, do I read correctly that in case gatewayEnabled is true, the CORS related headers are always stripped

In case it is false, they remain?

[pablocarle]

CORS request headers have to be stripped in every case, in particular Origin header, otherwise the southbound service may not match to gateway's host.
The difference relies on whether gateway will take service's overrides or not

[balhar-jakub]

So to validate I understand the whole piece:

Regardless of whether the corsEnabled is true or false. The API ML strips Access-Control-Allow-* Headers and then the discussion is what happens with respect to addition of CORS headers for the downstream service.

If corsEnabled is false, there are no CORS headers added.

If corsEnabled is true, there are default CORS headers added and that is it unless the service provides the additional headers information

[pablocarle]

Only request headers are stripped, so Origin and Access-Control-Request-* headers (for preflight OPTIONS requests)
Response headers are untouched (Access-Control-Allow-*)
Since request headers are removed, the service always receives a non-CORS request.

The only difference is that with corsEnabled true, Gateway may respond with service-specific response headers instead of the defaults. Enphasis on the "may", since it requires that the service provides the correct metadata values.

[balhar-jakub]

Let me then reiterate my understanding. I will try to show the three options -

1. corsEnabled: false
2. corsEnabled: true, customMetadata.apiml.corsEnabled: true
3. corsEnabled: true, customMetadata.apiml.corsEnabled: false

The flows

1. The Request comes with the headers Origin, Access-Control-Request-Method, Access-Control-Request-Headers
   The API ML strips all these headers from this request
   The API ML calls the downstream service without Access-Control-Request-Method, Access-Control-Request-Headers
   The service may set up Response headers e.g. Access-Control-Allow-*
   If these headers are set up, this is what the API ML returns and it does not touch them.

2. The Request comes with the headers Origin, Access-Control-Request-Method, Access-Control-Request-Headers
   The API ML strips all these headers from this request
   The API ML calls the downstream service with Access-Control-Request-Method, Access-Control-Request-Headers set based on the defaults plus the specific informations provided in customMetadata by service
   The service may set up Response headers e.g. Access-Control-Allow-*
   If these headers are set up, this is what the API ML returns and it does not touch them.

3. The Request comes with the headers Origin, Access-Control-Request-Method, Access-Control-Request-Headers
   The API ML strips all these headers from this request
   The API ML calls the downstream service with Access-Control-Request-Method, Access-Control-Request-Headers set based on the defaults only
   The service may set up Response headers e.g. Access-Control-Allow-*
   If these headers are set up, this is what the API ML returns and it does not touch them.

[pablocarle]

Not exactly.
In all cases CORS is resolved by Gateway, the service does not see a CORS request at all (since the headers were removed)

The actual requests get to the service (with CORS request headers removed). But, before the actual request there is a preflight request that browsers typically do, these are HTTP OPTIONS requests.
The preflight request is resolved by Gateway independently of whether the CORS handling is enabled or not (these requests are never sent to the service) based on the CORS settings

So in the 3 scenarios above I'd update that the Access-Control-Allow-* headers are set by Gateway, not by the service.

[pablocarle]

Another clarifycation, in the scenarios described above, if the request gets to the service, since the CORS headers were removed, it's not expected that the service will set any CORS response headers

[pablocarle]

I think this needs to be updated, the preflight is always handled by gateway, the only difference is whether Gateway will take service-provided overrides (with CORS enabled on Gateway) or use the global defaults (with disabled)
In the first scenario, if the service does not provide overrides, the global defaults are used.
The global defaults can be changed for the Gateway in zowe.yaml.