Security doc org refactor #3978

janan07 · 2024-11-04T11:29:10Z

Describe your pull request here:

List the file(s) included in this PR:

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

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions · 2024-11-04T11:29:22Z

😺 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 · 2024-11-04T11:29:24Z

📁 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 · 2024-11-04T11:29:34Z

🔍 The review label is missing. Add a review: label so we can determine who needs to approve this PR.

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

github-actions · 2024-11-04T11:29:35Z

💾 The release label is missing. Add a release: label so your content is published with the correct major Zowe release.

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

github-actions · 2024-11-04T11:29:37Z

📌 The subject area label is missing. Add an area: label so we know what your content is about.

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

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions · 2024-11-04T15:09:12Z

🚀 Deployed on https://673f3245743ee30b5b8d361d--zowe-docs-master.netlify.app

Signed-off-by: Andrew Jandacek <[email protected]>

…ity-doc-org-refactor' of https://github.com/zowe/docs-site into janan07-security-doc-org-refactor

Signed-off-by: Andrew Jandacek <[email protected]>

1000TurquoisePogs

Loving the use of <details> to hide all the commands because they're quite similar and routine throughout the page.

I'm focusing on the table contents... the contents and how we explain them could guide what this page covers and how.

1000TurquoisePogs · 2024-11-05T10:10:12Z

docs/user-guide/configure-zos-system.md

+| --- | --- | --- |
+| Set the names for the different z/OS UNIX address spaces for the Zowe runtime components. <br/>**Important:** This configuration step is required. | All components | [Configure address space job naming](#configure-address-space-job-naming) |
+| To use Zowe desktop. This step generates random numbers for zssServer that the Zowe desktop uses. | Application Framework | [Configure an ICSF cryptographic services environment](#configure-an-icsf-cryptographic-services-environment) |
+| To allow users to log on to the Zowe desktop through impersonation. |  | [Configure security environment switching](#configure-security-environment-switching) |


Application Framework

1000TurquoisePogs · 2024-11-05T10:20:54Z

docs/user-guide/configure-zos-system.md

+| To use Zowe desktop. This step generates random numbers for zssServer that the Zowe desktop uses. | Application Framework | [Configure an ICSF cryptographic services environment](#configure-an-icsf-cryptographic-services-environment) |
+| To allow users to log on to the Zowe desktop through impersonation. |  | [Configure security environment switching](#configure-security-environment-switching) |
+| Required for TSS only. A TSS FACILITY needs to be defined and assigned to the `ZWESLSTC` started task. |  | [Configure multi-user address space for TSS only](#configure-multi-user-address-space-for-tss-only) |
+| Required if you have not run `ZWESECUR` and are manually creating the user ID and groups in your z/OS environment. |  | [Configure user IDs and groups for the Zowe started tasks](#configure-user-ids-and-groups-for-the-zowe-started-tasks) |


All mention of "ZWESECUR" in this table should be rethought.

ZWESECUR is not the recommended job to run anymore.

It was also ever only one of now 4 ways to perform its actions (zwe, jcl, zosmf workflow, install wizard)

Because the operations of ZWESECUR are instructed to be done within a prior doc page, care should be taken not to present this as something that needs to be done again.

You may wish to reword all "Required if you have not run ZWESECUR" entries to
"Required. Tasks are done within zwe, workflow, install wizard or jcl-based security setup.

Or

"Required. Tasks are done within Zowe runtime configuration"

Or to call them out in a separate table or list by saying "The following tasks are needed by Zowe, and are normally handled during Zowe runtime configuration. Read each link to learn more about the tasks performed by that configuration"

1000TurquoisePogs · 2024-11-05T10:22:05Z

docs/user-guide/configure-zos-system.md

+| Required if you have not run `ZWESECUR` and are configuring your z/OS environment manually. This step describes how to configure the cross memory server for SAF to guard against access by non-privileged clients. | Application Framework | [Configure the cross memory server for SAF](#configure-the-cross-memory-server-for-saf) |
+| Required for API Mediation Layer to map a client certificate to a z/OS identity. | API ML | [Configure main Zowe server to use client certificate identity mapping](#configure-main-zowe-server-to-use-client-certificate-identity-mapping) |
+| Required for API ML to map the association between a z/OS user ID and a distributed user identity. | API ML | [Configure main Zowe server to use distributed identity mapping](#configure-main-zowe-server-to-use-distributed-identity-mapping) |
+| To configure SAF Identity tokens on z/OS so that they can be used by Zowe components like zss or API Mediation Layer. |  | [Configure signed SAF Identity tokens IDT](#configure-signed-saf-identity-tokens-idt) |


Meaning it is optional.
Our text in each box calls out "Required" a little differently for each but Maybe better to make a row of checkboxes for Required/Optional?

1000TurquoisePogs · 2024-11-05T10:23:02Z

docs/user-guide/configure-zos-system.md

+| Required for API Mediation Layer to map a client certificate to a z/OS identity. | API ML | [Configure main Zowe server to use client certificate identity mapping](#configure-main-zowe-server-to-use-client-certificate-identity-mapping) |
+| Required for API ML to map the association between a z/OS user ID and a distributed user identity. | API ML | [Configure main Zowe server to use distributed identity mapping](#configure-main-zowe-server-to-use-distributed-identity-mapping) |
+| To configure SAF Identity tokens on z/OS so that they can be used by Zowe components like zss or API Mediation Layer. |  | [Configure signed SAF Identity tokens IDT](#configure-signed-saf-identity-tokens-idt) |
+| Required for API Mediation Layer to issue SMF records. | API ML | [Configure the main Zowe server to issue SMF records](api-mediation/api-mediation-smf.md#configure-the-main-zowe-server-to-issue-smf-records) |


Wording could mislead here. This action is required if you want to use an optional feature.
Thus it is optional.

Signed-off-by: Andrew Jandacek <[email protected]>

…nfiguring security / limit content duplication Signed-off-by: Andrew Jandacek <[email protected]>

Signed-off-by: Andrew Jandacek <[email protected]>

arxioly · 2024-11-19T13:35:31Z

docs/user-guide/assign-security-permissions-to-users.md

+```
+RLIST FACILITY BPX.JOBNAME AUTHUSER
+```
+
+2. Activate the facility class, permit `BPX.JOBNAME`, and refresh facility class:
+```
+SETROPTS CLASSACT(FACILITY) RACLIST(FACILITY)
+PERMIT BPX.JOBNAME CLASS(FACILITY) ID(ZWESVUSR) ACCESS(READ)
+SETROPTS RACLIST(FACILITY) REFRESH
+```


It's only RACF commands here, shouldn't be also provided commands for other ESMs?

arxioly · 2024-11-19T13:56:13Z

docs/user-guide/configure-zos-system.md

+| To use Single Sign-On (SSO) | All components | [Single Sign-On (SSO)](#single-sign-on-sso) |
+| To use OIDC Authentication with API Mediation Layer | API ML | [API Mediation Layer OIDC Authentication](#api-mediation-layer-oidc-authentication) |
+
+### Configure address space job naming


This sub-article is complete duplication of same sub-article in docs/user-guide/assign-security-permissions-to-users.md. Is it some need in it? Can we maybe to have a link to here from assign-security-permissions-to-users.md?

I'm sorry, I don't follow your point here. Can you explain which sections are duplicates?

"Configure address space job naming" in both docs/user-guide/configure-zos-system.md and ocs/user-guide/assign-security-permissions-to-users.md

Thanks. Sorry. You are correct. I didn't see the duplication. I've corrected this.

arxioly · 2024-11-20T14:01:39Z

docs/user-guide/zwe-init-subcommand-overview.md

+- [Initializing Zowe custom data sets (`zwe init mvs`)](#initializing-zowe-custom-data-sets-zwe-init-mvs)
+- [Procedure to initialize Zowe custom data sets](#procedure-to-initialize-zowe-custom-data-sets)
+- [Initializing Zowe security configurations (`zwe init security`)](#initializing-zowe-security-configurations-zwe-init-security)
+- [Performing APF authorization of load libraries (`zwe init apfauth`)](#performing-apf-authorization-of-load-libraries-zwe-init-apfauth)
+- [Configuring Zowe to use TLS certificates (`zwe init certificate`)](#configuring-zowe-to-use-tls-certificates-zwe-init-certificate)
+- [Installing Zowe main started tasks (`zwe init stc`)](#installing-zowe-main-started-tasks-zwe-init-stc)
+- [(Deprecated) Creating VSAM caching service datasets (`zwe init vsam`)](#deprecated-creating-vsam-caching-service-datasets-zwe-init-vsam)
+- [Next steps](#next-steps)


Is it TOC or list of commands? Because the sentence above refers to the list of subcommands:

Some of the following zwe init subcommands...

If this is intended to be TOC, I would add some indentations to follow the structure:

Suggested change

- [Initializing Zowe custom data sets (`zwe init mvs`)](#initializing-zowe-custom-data-sets-zwe-init-mvs)

- [Procedure to initialize Zowe custom data sets](#procedure-to-initialize-zowe-custom-data-sets)

- [Initializing Zowe security configurations (`zwe init security`)](#initializing-zowe-security-configurations-zwe-init-security)

- [Performing APF authorization of load libraries (`zwe init apfauth`)](#performing-apf-authorization-of-load-libraries-zwe-init-apfauth)

- [Configuring Zowe to use TLS certificates (`zwe init certificate`)](#configuring-zowe-to-use-tls-certificates-zwe-init-certificate)

- [Installing Zowe main started tasks (`zwe init stc`)](#installing-zowe-main-started-tasks-zwe-init-stc)

- [(Deprecated) Creating VSAM caching service datasets (`zwe init vsam`)](#deprecated-creating-vsam-caching-service-datasets-zwe-init-vsam)

- [Next steps](#next-steps)

- [Initializing Zowe custom data sets (`zwe init mvs`)](#initializing-zowe-custom-data-sets-zwe-init-mvs)

- [Procedure to initialize Zowe custom data sets](#procedure-to-initialize-zowe-custom-data-sets)

- [Initializing Zowe security configurations (`zwe init security`)](#initializing-zowe-security-configurations-zwe-init-security)

- [Performing APF authorization of load libraries (`zwe init apfauth`)](#performing-apf-authorization-of-load-libraries-zwe-init-apfauth)

- [Configuring Zowe to use TLS certificates (`zwe init certificate`)](#configuring-zowe-to-use-tls-certificates-zwe-init-certificate)

- [Installing Zowe main started tasks (`zwe init stc`)](#installing-zowe-main-started-tasks-zwe-init-stc)

- [(Deprecated) Creating VSAM caching service datasets (`zwe init vsam`)](#deprecated-creating-vsam-caching-service-datasets-zwe-init-vsam)

- [Next steps](#next-steps)

I addressed this comment with the removal of the non init command section headers.

…curity permissions Signed-off-by: Andrew Jandacek <[email protected]>

Signed-off-by: Andrew Jandacek <[email protected]>

…o parent topic configuring-security Signed-off-by: Andrew Jandacek <[email protected]>

janan07 added 3 commits November 1, 2024 16:49

initial refactor with title change and collapsable ESM commands

eea5467

Signed-off-by: Andrew Jandacek <[email protected]>

initial component listing for security customization

55335a7

Signed-off-by: Andrew Jandacek <[email protected]>

readd Configure address space job naming

8f637e9

Signed-off-by: Andrew Jandacek <[email protected]>

janan07 requested a review from balhar-jakub November 4, 2024 11:29

1000TurquoisePogs self-requested a review November 4, 2024 11:44

janan07 added 5 commits November 4, 2024 14:04

formatting

d7cb4e9

Signed-off-by: Andrew Jandacek <[email protected]>

formatting

e50bbd0

Signed-off-by: Andrew Jandacek <[email protected]>

formatting

118ec2f

Signed-off-by: Andrew Jandacek <[email protected]>

remove summary for ACF2

1faea93

Signed-off-by: Andrew Jandacek <[email protected]>

Merge branch 'master' into janan07-security-doc-org-refactor

ac265e8

github-actions bot temporarily deployed to pull request November 4, 2024 15:09 Inactive

janan07 added 2 commits November 4, 2024 16:09

re add ACF2 collapsable content

ef69d93

Signed-off-by: Andrew Jandacek <[email protected]>

Merge branches 'janan07-security-doc-org-refactor' and 'janan07-secur…

8302558

…ity-doc-org-refactor' of https://github.com/zowe/docs-site into janan07-security-doc-org-refactor

github-actions bot temporarily deployed to pull request November 4, 2024 15:23 Inactive

fix note at the bottom of systemrequirements-zos

8affbc3

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request November 4, 2024 15:46 Inactive

1000TurquoisePogs reviewed Nov 5, 2024

View reviewed changes

address Sean's comments

afcda3e

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request November 5, 2024 13:01 Inactive

add link to zwe init security

f0077ec

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request November 5, 2024 14:33 Inactive

fix typo and add roles

1839c4b

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request November 5, 2024 15:23 Inactive

shuffle content from initializing Zowe security configuration into Co…

9b9f049

…nfiguring security / limit content duplication Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request November 18, 2024 16:30 Inactive

janan07 added 2 commits November 18, 2024 17:37

fix formatting

be6eb4d

Signed-off-by: Andrew Jandacek <[email protected]>

Merge branch 'master' into janan07-security-doc-org-refactor

9447c99

github-actions bot temporarily deployed to pull request November 18, 2024 16:49 Inactive

janan07 added 2 commits November 19, 2024 10:51

improve formatting/consistency

63b44d1

Signed-off-by: Andrew Jandacek <[email protected]>

formatting

881d562

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request November 19, 2024 10:00 Inactive

Merge branch 'master' into janan07-security-doc-org-refactor

eea0316

github-actions bot temporarily deployed to pull request November 19, 2024 13:00 Inactive

fix link

8495cbf

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request November 19, 2024 13:34 Inactive

arxioly reviewed Nov 19, 2024

View reviewed changes

Merge branch 'master' into janan07-security-doc-org-refactor

af094fe

github-actions bot temporarily deployed to pull request November 20, 2024 11:13 Inactive

arxioly reviewed Nov 20, 2024

View reviewed changes

Merge branch 'master' into janan07-security-doc-org-refactor

3b4aa51

github-actions bot temporarily deployed to pull request November 21, 2024 09:44 Inactive

remove duplication of COnfiguring address space naming from assign se…

7c061b7

…curity permissions Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request November 21, 2024 09:51 Inactive

reformat init commands and remove items that are not applicable

81677bb

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request November 21, 2024 10:11 Inactive

fix link

62b388c

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request November 21, 2024 10:38 Inactive

arxioly approved these changes Nov 21, 2024

View reviewed changes

remove initialize-security-configuration.md. COntent has been moved t…

2342ac8

…o parent topic configuring-security Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request November 21, 2024 13:15 Inactive

janan07 merged commit 78801a9 into master Nov 21, 2024
3 of 4 checks passed

janan07 deleted the janan07-security-doc-org-refactor branch November 21, 2024 13:28

janan07 restored the janan07-security-doc-org-refactor branch November 22, 2024 14:37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Security doc org refactor #3978

Security doc org refactor #3978

janan07 commented Nov 4, 2024

github-actions bot commented Nov 4, 2024

github-actions bot commented Nov 4, 2024

github-actions bot commented Nov 4, 2024

github-actions bot commented Nov 4, 2024

github-actions bot commented Nov 4, 2024

github-actions bot commented Nov 4, 2024 •

edited

Loading

1000TurquoisePogs left a comment •

edited

Loading

1000TurquoisePogs Nov 5, 2024

1000TurquoisePogs Nov 5, 2024 •

edited

Loading

1000TurquoisePogs Nov 5, 2024

1000TurquoisePogs Nov 5, 2024

arxioly Nov 19, 2024

arxioly Nov 19, 2024

janan07 Nov 20, 2024

arxioly Nov 20, 2024

janan07 Nov 21, 2024

arxioly Nov 20, 2024 •

edited

Loading

janan07 Nov 21, 2024

Security doc org refactor #3978

Security doc org refactor #3978

Conversation

janan07 commented Nov 4, 2024

github-actions bot commented Nov 4, 2024

github-actions bot commented Nov 4, 2024

github-actions bot commented Nov 4, 2024

github-actions bot commented Nov 4, 2024

github-actions bot commented Nov 4, 2024

github-actions bot commented Nov 4, 2024 • edited Loading

1000TurquoisePogs left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

1000TurquoisePogs Nov 5, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

arxioly Nov 20, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Nov 4, 2024 •

edited

Loading

1000TurquoisePogs left a comment •

edited

Loading

1000TurquoisePogs Nov 5, 2024 •

edited

Loading

arxioly Nov 20, 2024 •

edited

Loading