Rip/gh677/unify sso documentation (#1404)

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>

docs/.vuepress/pages.json

@@ -142,6 +142,7 @@
           "extend/extend-apiml/onboard-direct-eureka-call.md",
           "extend/extend-apiml/onboard-spring-boot-enabler.md",
           "extend/extend-apiml/onboard-static-definition.md",
+          "extend/extend-apiml/api-mediation-sso.md",
           "extend/extend-apiml/api-mediation-message-service.md",
           "extend/extend-apiml/api-mediation-security.md",
           "extend/extend-apiml/api-mediation-routing.md",

docs/extend/extend-apiml/api-mediation-security.md

@@ -19,10 +19,6 @@
     + [API ML SAF Keyring](#api-ml-saf-keyring)
     + [Discovery Service authentication](#discovery-service-authentication)
     + [Setting ciphers for API ML services](#setting-ciphers-for-api-ml-services)
-  * [Participating in Zowe API ML Single-Sign-On](#participating-in-zowe-api-ml-single-sign-on)
-    + [Zowe API ML client](#zowe-api-ml-client)
-    + [API service accessed via Zowe API ML](#api-service-accessed-via-zowe-api-ml)
-    + [Existing services that cannot be modified](#existing-services-that-cannot-be-modified)
   * [ZAAS Client](#zaas-client)
     + [Pre-requisites](#pre-requisites)
     + [API Documentation](#api-documentation)
@@ -105,7 +101,7 @@ The following range of service types apply to the Zowe™ API ML:
 
 ### Zowe API ML TLS requirements
 
-The API ML TLS requires servers to provide HTTPS ports. Each of the API ML services has the following specific requirements:
+The API ML TLS requires servers to provide HTTPS ports. Each API ML service has the following specific requirements:
 
 - **API Client**
     - The API Client is not a server
@@ -145,7 +141,7 @@ The API ML TLS requires servers to provide HTTPS ports. Each of the API ML servi
 
     - API Gateway handles authentication.
     - There are two authentication endpoints that allow to authenticate the resource by providers
-    - Diagnostic endpoints `/application/**` in API Gateway are protected by basic authentication or Zowe JWT token.
+    - Diagnostic endpoints `/application/**` in API Gateway are protected by basic authentication or Zowe JWT token
 
 - **API Catalog**
 
@@ -157,7 +153,7 @@ The API ML TLS requires servers to provide HTTPS ports. Each of the API ML servi
     - Discovery Service is accessed by API Services
     - This access (reading information and registration) requires protection needs by a client certificate
     - (Optional) Access can be granted to users (administrators)
-    - Diagnostic endpoints `/application/**` in Discovery Service are protected by basic authentication or Zowe JWT token.
+    - Diagnostic endpoints `/application/**` in Discovery Service are protected by basic authentication or Zowe JWT token
 
 - **API Services**
 
@@ -173,14 +169,14 @@ The `/login` endpoint authenticates mainframe user credentials and returns an au
   * Basic access authentication
   * JSON with user credentials
 
-When authentication is successful the response to the request is an empty body and a token is contained in a secure `HttpOnly` cookie named `apimlAuthenticationToken`. When authentication fails, a user gets a 401 status code.
+When authentication is successful, the response to the request is an empty body and a token is contained in a secure `HttpOnly` cookie named `apimlAuthenticationToken`. When authentication fails, a user gets a 401 status code.
 
 The `/query` endpoint validates the token and retrieves the information associated with the token.
 The query request requires the token through one of the following methods:
   * A cookie named `apimlAuthenticationToken`
   * Bearer authentication
 
-When authentication is successful the response to the request is a JSON object which contains information associated with the token. When authentication fails, a user gets a 401 status code.
+When authentication is successful, the response to the request is a JSON object which contains information associated with the token. When authentication fails, a user gets a 401 status code.
 
 The `/ticket` endpoint generates a PassTicket for the user associated with a token.
 
@@ -190,12 +186,21 @@ The ticket request requires the token in one of the following formats:
 - Cookie named apimlAuthenticationToken.
 - Bearer authentication
 
-The request takes one parameter named `applicationName`, the name of the application for which the PassTicket should be generated. This parameter must be supplied.
+The request takes the `applicationName` parameter, which is the name of the application for which the PassTicket should be generated. This parameter must be supplied.
 
 The response is a JSON object, which contains information associated with the ticket.
 
 For more details, see the OpenAPI documentation of the API Mediation Layer in the API Catalog.
 
+#### Supported authentication methods
+The API Mediation Layer provides multiple methods which clients can use to authenticate. When the API ML is run as a part of Zowe, all of the following methods are enabled and supported. All the methods are supported at least to some extent with each authentication provider.
+
+##### Username/Password
+The client can authenticate via Username and password. There are multiple methods which can be used to deliver the credentials. There are more details in the [ZAAS Client documentation](https://docs.zowe.org/stable/extend/extend-apiml/api-mediation-security.html#zaas-client).
+
+##### JWT Token
+When the client authenticates with the API ML, it receives in exchange the JWT token which can be used for further authentication. If z/OSMF is configured as the authentication provider and the client already received a JWT token produced by the z/OSMF, it is possible to reuse this token within the API ML for authentication.
+
 #### Authentication providers
 
 API ML contains the following providers to handle authentication for the API Gateway:
@@ -212,6 +217,15 @@ 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 API Gateway to authenticate directly with the z/OS SAF provider installed on the system. The user needs SAF account in order to authenticate.
+
+Use the following property of API Gateway to enable the SAF Authentication Provider:
+```
+apiml.security.auth.provider: saf
+```
+
 ##### Dummy Authentication Provider
 
 The `Dummy Authentication Provider` implements simple authentication for development purpose using dummy credentials (username:  `user`, password `user`). The `Dummy Authentication Provider` allows API Gateway to run without authenticating with the z/OSMF service.
@@ -350,56 +364,6 @@ The following list shows the default ciphers. API ML services use the following
 
 Only IANA ciphers names are supported. For more information, see [Cipher Suites](https://wiki.mozilla.org/Security/Server_Side_TLS#Cipher_suites) or [List of Ciphers](https://testssl.net/openssl-iana.mapping.html).
 
-## Participating in Zowe API ML Single-Sign-On
-
-As Zowe extender, you can extend Zowe and participate in Zowe Single-Sign-On provided by Zowe API ML.
-
-The Zowe Single-Sign-On is based on a single authentication/identity token that identifies the z/OS user. This token needs to be trusted by extensions in order to be used. Only Zowe API ML and the ZAAS compoment (described above), can issue the authentication token based on valid z/OS credentials.
-
-In the current release of Zowe, only a single z/OS security domain can be used. The current Zowe release also allows for a single technology scope, whereby only a single-sign-on to Zowe Desktop is possible. As such, a second sign-on is necessary to different types of clients, such as Zowe CLI, or web applications outside of Zowe Desktop.
-
-This following section outlines the high-level steps necessary to achieve the sign-on.
-
-There are two main types of components that are used in Zowe SSO via API ML:
-
-* Zowe API ML client
-
-   - This type of compoment is user-facing and can obtain credentials from the user through a user interface (web, CLI, desktop)
-   - The Zowe API ML client calls API services through the API ML
-   - An example of such clients are Zowe CLI or Zowe Desktop. Clients can be web or mobile applications
-
-* An API service accessed through Zowe API ML
-
-   - A service that is registered to API ML and is accessed through the API Gateway
-
-In following sections, you will learn what is necessary to participate SSO for both types.
-
-### Zowe API ML client
-
-* Zowe API ML client needs to obtain an authentication token via the `/login` endpoint of ZAAS described above. This endpoint requires valid credentials.
-* The client should not rely on the token format but use the ZAAS `/query` endpoint to validate the token and get information about it. This is useful when the API client has the token but does not store the associated data such as user ID.
-* The API client needs to provide the authentication token to the API services in the form of a Secure HttpOnly cookie with the name `apimlAuthenticationToken` or in `Authorization: Bearer` HTTP header as described in the [Authenticated Request](https://github.com/zowe/sample-spring-boot-api-service/blob/master/zowe-rest-api-sample-spring/docs/api-client-authentication.md#authenticated-request).
-
-**Note:** Plans for Zowe CLI to be an API ML client in the future, are desribed at [Zowe CLI: Token Authentication, MFA, and SSO](https://medium.com/zowe/zowe-cli-token-authentication-mfa-and-sso-b88bca3efa35).
-
-### API service accessed via Zowe API ML
-
-This section describes the requirements of a service to adopt the Zowe authentication token. Zowe will be able to support services that accept PassTickets in the future.
-
-* The API service must accept the authentication token to the API services in the form of a Secure HttpOnly cookie with the name `apimlAuthenticationToken` or in the `Authorization: Bearer` HTTP header as described in the [Authenticated Request](https://github.com/zowe/sample-spring-boot-api-service/blob/master/zowe-rest-api-sample-spring/docs/api-client-authentication.md#authenticated-request).
-* The API service must validate the token and extract information about the user ID by calling `/query` endpoint of the ZAAS described above. The alternative is validate the signature of the JWT token. The format of the signature and location of the public key is described above. The alternative should be used only when the calling of `/query` endpoint is not feasible.
-* The API service needs to trust the Zowe API gateway that hosts the ZAAS, it needs to have the certificate of the CA that signed the Zowe API Gateway in its truststore.
-
-The REST API of the ZAAS can be easily called from a Java application using [ZAAS Client](#zaas-client) described below.
-
-### Existing services that cannot be modified
-
-If you have a service that cannot be changed to adopt Zowe authentication token, they can still participate in Zowe Single-Sign-On via API ML.
-
-They need to accept PassTicket in the HTTP Authorization header.
-See [Enabling PassTicket creation for API Services that Accept PassTickets](api-mediation-passtickets.md) for more details.
-
-
 ## ZAAS Client
 
 The ZAAS client is a plain Java library that provides authentication through a simple unified interface without the need

docs/extend/extend-apiml/api-mediation-sso.md

@@ -0,0 +1,63 @@
+# Zowe API Mediation Layer Single-Sign-On Overview
+
+You can extend Zowe and utilize Zowe Single-Sign-On (SSO) provided by Zowe API Mediation Layer (API ML) to enhance system security and improve the user experience. 
+
+This article provides an overview of the API ML single-sign-on feature, the principle participants in the SSO process, and links to detailed Zowe SSO documentation. Zowe Single-Sign-On is based on single-user authentication which produces an access token that represents the user in communication with z/OS services accessible through the API Mediation Layer. The access token is issued by the Zowe Authentication and Authorization Service (ZAAS), which is part of API ML. ZAAS issues an access token based on valid z/OS credentials. This token can be validated by any component participating in SSO. 
+
+**Note:** Currently, API ML can only provide SSO in a domain with a single method of security in place.
+
+- [Zowe API ML client](#zowe-api-ml-client)
+- [API service accessed via Zowe API ML](#api-service-accessed-via-zowe-api-ml)
+- [Existing services that cannot be modified](#existing-services-that-cannot-be-modified)
+
+The following diagram describes the interactions between the general participants in the single-sign-on process. 
+
+<img src="../../images/api-mediation/sso-diagram.jpeg" alt="Zowe SSO Explanation" width="700"/>
+
+There are two main types of components that participate in Zowe SSO through API ML:
+
+* Zowe API ML client
+
+   - This type of component is user-facing and can obtain user credentials through a user interface (web, CLI, desktop).
+   - API ML clients can be confidential or public.
+   - A Zowe API ML client calls API services through the API ML.
+   - An example of such clients are Zowe CLI or Zowe Desktop. 
+
+* An API service accessed through Zowe API ML
+
+   - A service that is registered to API ML and is accessed through the API Gateway.
+   - Services are protected by an access token or PassTicket.
+   - The access token or PassTicket can be validated by the called API service.
+
+The following sections describe what is necessary to utilize SSO for both types of components.
+
+### Zowe API ML client
+
+* The Zowe API ML client needs to obtain an access token via the `/login` endpoint of ZAAS by providing z/OS credentials.
+* A client can call the ZAAS `/query` endpoint to validate the token and get information from the token. This is useful when the API client has the token but does not store the associated data such as the user ID.
+* The API client needs to provide the access token to API services in the form of a Secure HttpOnly cookie with the name `apimlAuthenticationToken`, or in the `Authorization: Bearer` HTTP header as described in [Authenticated Request](https://github.com/zowe/sample-spring-boot-api-service/blob/master/zowe-rest-api-sample-spring/docs/api-client-authentication.md#authenticated-request).
+
+### API service accessed via Zowe API ML
+
+This section describes the requirements that an API service needs to satisfy to adopt a Zowe SSO access token. 
+
+* The token received by the Gateway is first validated and then may be passed directly to the service. Alternatively, the Gateway can exchange the token for a PassTicket if the API service is configured to expect a PassTicket.
+* The API service can validate the token and extract information about the user ID by calling the ZAAS `/query` endpoint. 
+* The alternative is to validate the signature of the JWT token using the public key of the token issuer (e.g. the API ML Gateway). The API service needs to have the API ML Gateway certificate along with the full CA certification chain in the API service truststore. 
+
+**Note:** The REST API of ZAAS can easily be called from a Java application using the [ZAAS Client](api-mediation-security.md#zaas-client).
+
+### Existing services that cannot be modified
+
+If you have a service that cannot be changed to adopt the Zowe authentication token, the service can utilize Zowe SSO if the API service is able to handle PassTickets. 
+
+**Note:** For more information, see [Enabling PassTicket creation for API Services that Accept PassTickets](api-mediation-passtickets.md) for more details.
+
+## Further resources
+
+* [Authentication Methods](api-mediation-security.md#Supported-authentication-methods)
+* [User guide for SSO in Zowe CLI ](https://docs.zowe.org/stable/user-guide/cli-usingcli.html#accessing-multiple-services-with-sso)
+* [System requirements for using web tokens for SSO in Zlux and ZSS](https://docs.zowe.org/stable/user-guide/systemrequirements.html#using-web-tokens-for-sso-on-zlux-and-zss)
+* [Certificate configuration for the usage of web tokens for SSO in Zlux and ZSS](https://docs.zowe.org/stable/user-guide/configure-certificates.html#using-web-tokens-for-sso-on-zlux-and-zss) 
+
+