From a125f2f0256cff9bb9297c0f6f9f8e5acf4bca3b Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Fri, 22 Dec 2023 14:47:53 +0100 Subject: [PATCH] apply Jakub's comments Signed-off-by: Andrew Jandacek --- docs/user-guide/using-jwt-token-with-apiml.md | 37 +++++++------------ 1 file changed, 14 insertions(+), 23 deletions(-) diff --git a/docs/user-guide/using-jwt-token-with-apiml.md b/docs/user-guide/using-jwt-token-with-apiml.md index 6f23be35d0..312516d7b6 100644 --- a/docs/user-guide/using-jwt-token-with-apiml.md +++ b/docs/user-guide/using-jwt-token-with-apiml.md @@ -13,8 +13,6 @@ This parent article describes how services in the Zowe API ecosystem are expecte By default, JWT tokens are produced by z/OSMF and the API Mediation Layer serves only as a proxy. For information about how to change who and how tokens are produced, see [Authentication Providers within Enable Single Sign On for Clients](../user-guide/api-mediation/configuration-jwt/#saf-as-an-authentication-provider) - ### Token-based Login Flow and Request/Response Format @@ -22,15 +20,12 @@ The following sequence describes how authentication through JWT tokens works: 1. The API client obtains a JWT token by using the POST method on the `/auth/login` endpoint of the API service that requires a valid user ID and password. -2. The API service then calls an *authentication provider* that returns a JWT token that contains the user ID claim in the HTTP cookie named `apimlAuthenticationToken` with attributes `HttpOnly` and `Secure`. - -3. The API client stores the JWT token or cookie and sends the token with every request as a cookie with the name `apimlAuthenticationToken`. +2. The API client stores the JWT token or cookie and sends the token with every request as a cookie with the name `apimlAuthenticationToken`. ## Obtaining a token To obtain a token, call the endpoint with the credentials for either basic authentication or the client certificate. - - The full path for API ML is:```/gateway/auth/login``` @@ -74,8 +69,8 @@ Set-Cookie: apimlAuthenticationToken=eyJhbGciOiJSUzI1NiJ9...; Path=/; Secure; Ht You can send a JWT token with a request in two ways: -* Allow the API client to pass the JWT token as a cookie header -* Pass the JWT token in the `Authorization: Bearer` header +* Allow the API client to pass the JWT token as a cookie header. +* Pass the JWT token in the `Authorization: Bearer` header. :::tip The first option (using a cookie header) is recommended for web browsers with the attributes `Secure` and `HttpOnly`. @@ -85,8 +80,6 @@ Cookies are present on all requests, including those coming from DOM elements, a Cookies are more diffcult to support in non-web applications. Headers, such as `Authorization: Bearer`, can be used in non-web applications. Such headers, however, are difficult to use and secure in a web browser. The web application needs to store these headers and attach these headers to all requests where headers are required. - -Note that the API service needs to support both of them so the API clients can use what makes more sense for them. ::: #### Allow the API client to pass the JWT token as a cookie header @@ -121,22 +114,20 @@ HTTP/1.1 200 The API client does not need to validate tokens. API services must perform token validation themselves. If the API client receives a token from another source and needs to validate the JWT token, or needs to check details in the token, such as user ID expiration, then the client can use the `/auth/query` endpoint provided by the service. -The response is a JSON response with the following fields: +The JSON response contains the following fields: * `creation` * `expiration` * `userId` These fields correspond to `iss`, `exp`, and `sub` JWT token claims. The timestamps are in ISO 8601 format. - -**Example:** +Execute the following curl command to validate the existing JWT token, and to retrieve the contents of the token. ```bash -curl -k --cookie "apimlAuthenticationToken=eyJhbGciOiJSUzI1NiJ9..." -X GET "https://localhost:10080/api/v1/auth/query" +curl -k --cookie "apimlAuthenticationToken={token to query}" -X GET "https://localhost:10080/api/v1/auth/query" ``` -The following output describes the status of the token: - +The following output describes the status of the JWT token: ```http GET /api/v1/auth/query HTTP/1.1 @@ -155,19 +146,19 @@ Content-Type: application/json;charset=UTF-8 ### Refreshing the token -API Clients may want to refresh the existing token to prolong the validity time. +API Clients can refresh the existing token to prolong the validity time. Use the `auth/refresh` endpoint to prolong the validity time of the token. -The auth/refresh endpoint generates a new token for the user based on valid jwt token. The full path of the auth/refresh endpoint appears as the following URL: +The auth/refresh endpoint generates a new token for the user based on the valid JWT token. The full path of the `auth/refresh` endpoint appears as the following URL: ``` https://{gatewayUrl}:{gatewayPort}/gateway/api/v1/auth/refresh ``` -The new token overwrites the old cookie with a Set-Cookie header. As part of the process, the old token gets invalidated and is not usable anymore. +The new token overwrites the old cookie with a Set-Cookie header. As part of the process, the old token gets invalidated and is no longer usable. :::note**Notes:** -- The endpoint is disabled by default. For more information, see Enable JWT token endpoint. +- The endpoint is disabled by default. For more information, see [Enable JWT token endpoint](./api-mediation/configuration-jwt/#enabling-a-jwt-token-refresh-endpoint). - The endpoint is protected by a client certificate. - The refresh request requires the token in one of the following formats: - Cookie named `apimlAuthenticationToken`. @@ -176,12 +167,12 @@ The new token overwrites the old cookie with a Set-Cookie header. As part of the For more information, see the OpenAPI documentation of the API Mediation Layer in the API Catalog. - +The following request receives a valid JWT token and returns the new valid JWT token. As such, the expiration time is reset. ```bash -curl -v -c - -X POST "https://localhost:10080/api/v1/auth/refresh" +curl -v -c - -X --data '{"username":"zowe","password":"zowe"}' POST "https://localhost:10080/api/v1/auth/refresh" ``` -The following output describes the status of the token: +The following output describes the status of the JWT token: ```http POST /api/v1/auth/refresh HTTP/1.1