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.

Sign up for GitHub

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

fix SAF resource provider doc #4042

Open
wants to merge 5 commits into
base: docs-staging
Choose a base branch
from
+50 −39
Open

fix SAF resource provider doc #4042

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0ff749d
add doc
taban03 Dec 20, 2024
b1c6758
fix
taban03 Dec 20, 2024
f0d33fe
Merge branch 'docs-staging' into apiml/fix_saf_resource_provider_doc
janan07 Dec 27, 2024
50498d8
langugage refactor
janan07 Dec 27, 2024
4978541
fix typos
janan07 Dec 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 23 additions & 20 deletions docs/user-guide/api-mediation/configuration-saf-resource-checking.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,44 +10,47 @@ API ML can check for the authorization of the user on certain endpoints. Access

Verification of the SAF resource is provided by the following three providers:

- **`endpoint`**
This is the highest priority provider, such as a REST endpoint call (ZSS or similar one). This option is disabled by default. In Zowe, ZSS has the API to check for SAF resource authorization.

- **`native`**
The Native JZOS classes from Java are used to determine SAF resource access. This is the default provider.

The Native JZOS classes from Java are used to determine SAF resource access. This is the default provider.

**Note:** This provider cannot be used off-platform.

- **`endpoint`**
The Endpoint provider relies on APIs such as a REST endpoint call (ZSS or similar one). This option is disabled by default. In Zowe, ZSS provides the API to check for SAF resource authorization.
Copy link
Contributor

Choose a reason for hiding this comment

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

I wonder if it can be considered a breaking change (for anyone relying on the default being endpoint)

Copy link
Contributor

Choose a reason for hiding this comment

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

Add some note or clarification that this is the default from 3.1

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Well in theory the default was still native, as long as they didn't set endpoint.enabled to true.


- **`dummy`**
This is the lowest priority provider. This is the dummy implementation and is defined in a file.

:::note
Verification of the SAF resource uses the first available provider based on the specified priority. The default configuration resolves to the native provider.
Verification of the SAF resource uses the first available provider based on the specified priority. The default configuration resolves to the `native` provider.
:::

You can select a specific provider by specifying the `components.gateway.apiml.security.authorization.provider` key in the `zowe.yaml` file. Use the parameter value to
You can select a specific provider by specifying the `components.gateway.apiml.security.authorization.provider` key in the `zowe.yaml` file.
If no value is assigned to Use the parameter value to
strictly define a provider. If verification is disabled, select the `endpoint` option.
Copy link
Contributor

Choose a reason for hiding this comment

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

I think this needs to be rewritten

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I've fixed that, thanks. I'm just not totally sure about If verification is disabled, select the endpoint option. meaning


1. Open the file `zowe.yaml`.
2. Find or add the property `components.gateway.apiml.security.authorization.provider` and set desired value.
3. Restart Zowe.

**Examples:**
```
components.gateway.apiml.security.authorization.endpoint.url: endpoint
```

To configure the `endpoint` provider, add the following additional property:
`components.gateway.apiml.security.authorization.endpoint.enabled: true`

`components.gateway.apiml.security.authorization.provider: native`

`components.gateway.apiml.security.authorization.provider: dummy`

1. Native:
`components.gateway.apiml.security.authorization.provider: native`
If you leave the property empty, this will be the default value.
2. Endpoint:
`components.gateway.apiml.security.authorization.provider: endpoint`
3. Dummy:
`components.gateway.apiml.security.authorization.provider: dummy`

To use the endpoint provider, customize the URL corresponding to the SAF resource authorization. By default, the ZSS API is configured and used.
To use the endpoint provider, you also need enable the endpoint property and customize the URL corresponding to the SAF resource authorization. By default, the ZSS API is configured and used.

1. Open the file `zowe.yaml`.
2. Find or add the property `components.gateway.apiml.security.authorization.endpoint.url` and set desired value.
The default value for ZSS API is `https://${ZWE_haInstance_hostname}:${GATEWAY_PORT}/zss/api/v1/saf-auth`
2. Find or add the property:
- `components.gateway.apiml.security.authorization.provider: endpoint`
- `components.gateway.apiml.security.authorization.endpoint.enabled: true`
- `components.gateway.apiml.security.authorization.endpoint.url: <endpoint_url>`
In case you're using ZSS, the default value of the ZSS API to set to `components.gateway.apiml.security.authorization.endpoint.url` is https://${ZWE_haInstance_hostname}:${GATEWAY_PORT}/zss/api/v1/saf-auth`
3. Restart Zowe.

## REST endpoint call
Expand Down
Loading