Issue with docs.zowe.org/stable/extend/extend-apiml/authentication-for-apiml-services

[dkelosky]

Description

Can we provide info to our users on how to make the decision on which provider to use? For example, if you have z/OSMF, and want to access it's APIs via the API ML, you should use provider zosmf. If you are configuring for a system or sysplex where z/OSMF does not run, you need to use provider saf.

Obviously not that exact wording but perhaps something similar could instruct users how to chose rather than what the choices are?

Pages to Update

https://docs.zowe.org/stable/extend/extend-apiml/authentication-for-apiml-services#authentication-providers

Screenshots

Expected behavior

Additional context

[balhar-jakub]

I agree, but I would argue that this whole section, belongs under Advanced API ML Configuration, it doesn't concern Extenders at all, am I correct?

In the text bellow I also added a proposal for the text to be added on when to use which.

Maybe the dummy provider for quick start for development could belong into an article in Extending on Quick Start API ML for development.

Authentication providers

API ML contains the following providers to handle authentication for the API Gateway:

• z/OSMF Authentication Provider
• SAF Authentication Provider
• Dummy Authentication Provider

z/OSMF Authentication Provider should be used in most cases. The z/OSMF is part of the z/OS and as such is the best option for providing the authentication API.

The SAF Authentication provider should be used when z/OSMF isn't available. In that case API Gateway acts as the authentication service. The provided credentials are validated directly by API Gateway via SAF APIs.

z/OSMF Authentication Provider

The z/OSMF Authentication Provider allows the API Gateway to authenticate with the z/OSMF service. The user needs z/OSMF access in order to authenticate.

Use the following properties of the API Gateway to enable the z/OSMF Authentication Provider:

apiml.security.auth.provider: zosmf
apiml.security.auth.zosmfServiceId: zosmf  # Replace me with the correct z/OSMF service id

SAF Authentication Provider

The SAF Authentication Provider allows the API Gateway to authenticate directly with the z/OS SAF provider that is installed on the system. The user needs a SAF account to authenticate.

Use the following property of the API Gateway to enable the SAF Authentication Provider:

apiml.security.auth.provider: saf

Note: To provide your own implementation of the SAF IDT provider, see the Implement new SAF provider guidelines.

Dummy Authentication Provider

The Dummy Authentication Provider implements simple authentication for development purposes using dummy credentials (username: user, password user). The Dummy Authentication Provider makes it possible for the API Gateway to run without authenticating with the z/OSMF service.

Use the following property of API Gateway to enable the Dummy Authentication Provider:

apiml.security.auth.provider: dummy

[dkelosky]

I agree, but I would argue that this whole section, belongs under Advanced API ML Configuration, it doesn't concern Extenders at all, am I correct?

Good point, I agree.

I think the proposed changes and way you describe the guidance is very helpful as it describe "how" to choose a provider. Thanks!

[janan07]

This has been addressed in #3500

[balhar-jakub]

Part of it was, the second part is to move it under Advanced Configuration and that part is still missing.

First we need to create new Page - Authentication Providers for API Mediation Layer and move the content there and then in the current place we need to link to the new location so that it's available for those who go to the current location.

Second we need to remove the Dummy one from this document and move it to
Extend

• Quick start of API ML for development - Needs to be written.
  • General configuration for the API Mediation Layer - Needs to be created or repurposed from API Layer docs in the repository

[janan07]

This issue has been addressed with PR#3523

[balhar-jakub]

As such I am closing the issue