-
Notifications
You must be signed in to change notification settings - Fork 133
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
base: master
Are you sure you want to change the base?
Conversation
😺 Thank you for creating this PR! To publish your content to Zowe Docs, follow these required steps.
Need help? Contact the Doc Squad in the #zowe-doc Slack channel. |
1 similar comment
😺 Thank you for creating this PR! To publish your content to Zowe Docs, follow these required steps.
Need help? Contact the Doc Squad in the #zowe-doc Slack channel. |
📁 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
📁 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. |
There was a problem hiding this 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.
docs/user-guide/api-mediation/configuration-unique-cookie-name-for-multiple-zowe-instances.md
Show resolved
Hide resolved
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`. |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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":
- 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`. |
There was a problem hiding this comment.
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 ... "
There was a problem hiding this comment.
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`. |
There was a problem hiding this comment.
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]>
Signed-off-by: 1000TurquoisePogs <[email protected]>
Signed-off-by: 1000TurquoisePogs <[email protected]>
3aab64d
to
7166e1a
Compare
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.