Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add missing details for APIML cookie config #3977

Open
wants to merge 7 commits into
base: master
Choose a base branch
from

Conversation

1000TurquoisePogs
Copy link
Member

When adding compatibility in app-server for APIML's customizable cookie name, I needed to look up how it worked.
I found the document does not fully describe "zowe.cookieIdentifier"
It instead referenced a "cookieIdentifier", without stating what that was or where to find it.
I confirmed APIML's code really is referring to "zowe.cookieIdentifier" https://github.com/search?q=repo%3Azowe%2Fapi-layer%20cookieidentifier&type=code which is present in both v2 and v3 https://github.com/zowe/zowe-install-packaging/blob/v3.x/staging/example-zowe.yaml#L317

I updated the document for each version and made clarifications to help explain it.

@1000TurquoisePogs 1000TurquoisePogs added type: bug Something isn't working area: apiml This issue is related to Zowe API Mediation Layer release: V2 Zowe V2 content release: V3 Zowe V3 content review: doc Needs review by Doc Squad member labels Nov 4, 2024
Copy link

github-actions bot commented Nov 4, 2024

😺 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.

1 similar comment
Copy link

github-actions bot commented Nov 4, 2024

😺 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.

Copy link

github-actions bot commented Nov 4, 2024

📁 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.

1 similar comment
Copy link

github-actions bot commented Nov 4, 2024

📁 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.

Copy link

github-actions bot commented Nov 4, 2024

@github-actions github-actions bot temporarily deployed to pull request November 4, 2024 09:47 Inactive
@github-actions github-actions bot temporarily deployed to pull request November 5, 2024 11:02 Inactive
Copy link
Collaborator

@anaxceron anaxceron left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you @1000TurquoisePogs. Made some comments re: clarity, grammar, style.

1. Open the `zowe.yaml` configuration file.
2. Find or add the property `components.gateway.apiml.security.auth.uniqueCookie`, and set it to `true`. A unique cookie name is generated as `apimlAuthenticationToken.cookieIdentifier`.
1. Open the Zowe YAML configuration file.
2. Find or add the property `components.gateway.apiml.security.auth.uniqueCookie`, and set it to `true`.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If someone needs to add this property, will they know where to add it? If not, should we specify the location?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe so, but think about this:
"components.gateway.apiml.security.auth" exists here https://github.com/zowe/zowe-install-packaging/blob/v3.x/staging/example-zowe.yaml#L502-L511
So we're saying to add a sub-attribute called "uniqueCookie"

In many places of the doc, we use this "this.that.thing" format for brevity and every time devs interact with users.
I believe it's well understood in general and by enough exposure by now, but the concept is covered in this note in the YAML reference:
https://docs.zowe.org/v2.18.x/appendix/zowe-yaml-configuration

The only thing I can think to do to make it more apparent is to somehow be able to reference that appendix in every place where we make such YAML references. But, I don't think anyone agreed upon a good way to do that if at all.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@1000TurquoisePogs -- I think we can avoid linking to the appendix everywhere. We could link to the glossary since the definition includes a link to the appendix. I leave it to you, but my suggestion would be creating a link to the glossary term "Zowe configuration file":

  1. Open the Zowe YAML configuration file

3. Find the property `zowe.cookieIdentifier` and set it to any word or number that you wish to identify your Zowe instance.
4. Restart Zowe.

This will set a suffix for the API Gateway's cookie name based upon the value of `zowe.cookieIdentifier`.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the live site and previous versions: Avoid future tense in documentation: "This sets a suffix ... "

Copy link
Member Author

@1000TurquoisePogs 1000TurquoisePogs Nov 6, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok fixed!


**Example:**
If this parameter is set to `true`, and the cookieIdentifier is `1`, the name of the cookie transforms to `apimlAuthenticationToken.1`.
If this property is not set to `true`, the cookie name remains `apimlAuthenticationToken` by default.
If `components.gateway.apiml.security.auth.uniqueCookie` parameter is set to `true` and `zowe.cookieIdentifier` is `1`, the cookie name will be `apimlAuthenticationToken.1`.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the live site and previous versions:

  • Please add a definite article: "If the bbbb parameter is set ... "
  • Avoid future tense: " ... the cookie name is blahblah."

Signed-off-by: 1000TurquoisePogs <[email protected]>
Signed-off-by: 1000TurquoisePogs <[email protected]>
Signed-off-by: 1000TurquoisePogs <[email protected]>
Signed-off-by: 1000TurquoisePogs <[email protected]>
@github-actions github-actions bot temporarily deployed to pull request November 11, 2024 20:17 Inactive
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area: apiml This issue is related to Zowe API Mediation Layer release: V2 Zowe V2 content release: V3 Zowe V3 content review: doc Needs review by Doc Squad member type: bug Something isn't working
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants