adding doc re: base paths #4242
Conversation
Signed-off-by: anaxceron <[email protected]>
anaxceron
added
area: cli
|
😺 Thank you for creating this PR! To publish your content to Zowe Docs, follow these steps.
|
| zowe auth login apiml --host <APIML Host> --port <APIML Port> --cert-file <PEM Public Certificate Path> --cert-key-file <PEM Private Certificate Path> --base-profile <profile_name> | ||
| ``` | ||
|
|
||
| - Use `--base-profile` when issuing commands with API ML **[is "with" correct here?]**: |
There was a problem hiding this comment.
@adam-wolfe - please respond
There was a problem hiding this comment.
This is correct, but I would remove --base-path since that should be specified in a profile.
There was a problem hiding this comment.
For creating v1 profiles from the commandline, those commands should include --base-path as an option. Using --base-path for other commands is only necessary if you are running Zowe CLI without V1 profiles or a team config. Which could be the case for a user running commands using something like Jenkins where everything is scripted.
Signed-off-by: anaxceron <[email protected]>
| @@ -139,24 +236,23 @@ Use the following steps to specify a base path with Zowe V1 profiles: | |||
| ``` | |||
| Commands issued with this profile are routed through the layer to access an appropriate z/OSMF instance. | |||
|
|
|||
|
|
|||
| ## Accessing multiple services with SSO | |||
| ### Accessing multiple services with SSO | |||
|
|
|||
| If multiple services are registered to the API Mediation Layer at your site, Zowe CLI lets you access the services with Single Sign-on (SSO). Log in once to conveniently access all available services. | |||
|
|
|||
| When you are logged in, supply the `--base-path` option on commands for each service. Ensure that you do not provide username, password, host, or port directly on your service commands or profiles. Supplying those options causes the CLI to ignore the token in your base profile and directly access the service. You might need to remove those options from existing profiles to use SSO. | |||
There was a problem hiding this comment.
while you could "supply the --base-path option on commands for each service", it would be much more convenient to set the basePath property for each service profile so you don't have to specify this option on every command.
There was a problem hiding this comment.
Hold on. Not sure how V1 profiles handle this.
There was a problem hiding this comment.
awaiting further instruction on this
There was a problem hiding this comment.
Confirmed that the basePath property is supported in V1 profiles. So, it would make more sense to tell people to put the base path in their service profiles for either V1 profiles or team config depending on what they are using.
Side question: Do we still document V1 profile usage in V3 docs?
|
|
||
| If multiple services are registered to the API Mediation Layer at your site, Zowe CLI lets you access the services with Single Sign-on (SSO). Log in once to conveniently access all available services. | ||
|
|
||
| When you are logged in, supply the `--base-path` option on commands for each service. Ensure that you do not provide username, password, host, or port directly on your service commands or profiles. Supplying those options causes the CLI to ignore the token in your base profile and directly access the service. You might need to remove those options from existing profiles to use SSO. | ||
|
|
||
| For information about registering an API service at your site, see [Developing for API Mediation Layer](../extend/extend-apiml/onboard-overview). | ||
|
|
||
| ## Accessing services through SSO and a service not through API ML | ||
| ### Accessing services through SSO and a service not through API ML | ||
|
|
||
| A scenario might exist where you log in to API ML with SSO, but you also want to access a different service *directly*. | ||
|
|
||
| To access the SSO-enabled services, log in and issue commands with the `--base-path` and `--base-profile` options. The token from your base profile is used for authentication. Remember, your command or service profile must *not* contain username, password, host, or port. |
There was a problem hiding this comment.
Here, we would probably want to tell users that, for services they are accessing through the mediation layer, they should set basePath in their service profile. The --base-profile option is a bit trickier, since we don't support it as a profile property (but --base-profile does work as a command option). However, since profile nesting is not an option for V1 profiles, specifying the --base-profile as a command option may be the best option.
There was a problem hiding this comment.
but wouldn't it be kinder to instruct folks to use commands? I'm wondering if it's more complicated to have someone edit a config file and then still have to use the baseprofile option. I mean, if you're already using one option, wouldn't it be easier to use two? (that's a legit question, not rhetorical)
|
|
||
| A scenario might exist where you log in to API ML with SSO, but you also want to access a different service *directly*. | ||
|
|
||
| To access the SSO-enabled services, log in and issue commands with the `--base-path` and `--base-profile` options. The token from your base profile is used for authentication. Remember, your command or service profile must *not* contain username, password, host, or port. | ||
|
|
||
| To access the other service directly — and circumvent API ML — supply all connection information (username, password, host, and port) on a command or service profile. When you explicitly supply the username and password in a command or service profile, the CLI always uses that connection information instead of the API ML token. | ||
|
|
||
| ## Accessing services through SSO and a service through API ML but not SSO | ||
| ### Accessing services through SSO and a service through API ML but not SSO | ||
|
|
||
| You might want to access multiple services with SSO, but also access a service through API ML that is not SSO-enabled. |
There was a problem hiding this comment.
This comment is for the next line ("To perform SSO for the first ..."). I would suggest that the user puts the basePath in the relevant service profile. The --base-profile option is necessary for dealing with multiple API ML gateways using V1 profiles.
|
|
||
| ### Specifying a base path with Zowe V1 profiles | ||
| #### Specifying a base path with Zowe V1 profiles |
There was a problem hiding this comment.
Do we want to remove V1 profile documentation?
There was a problem hiding this comment.
I really don't know. I'll bring this up as a parking lot to the team in the near future.
Describe your pull request here: Addressing Issue 3361
List the file(s) included in this PR: cli-using-integrating-apiml.md, cli-authentication-mechanisms.md
After creating the PR, follow the instructions in the comments.