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: remove replay protection disabling requirement #3788

Merged
merged 9 commits into from
Aug 2, 2024
Merged

fix: remove replay protection disabling requirement #3788

Changes from 3 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
e89f5e1
automatic lint
Jul 31, 2024
3d1c8f8
fix other lint issues
Jul 31, 2024
8c913cb
remove replay protection
Jul 31, 2024
e8a0dec
address review
Jul 31, 2024
7e94730
Merge branch 'master' into reboot/fix/replay-protection
pablocarle Aug 1, 2024
32b993e
add note about re-enabling replay protection for old
Aug 2, 2024
7c7646e
try fix indent
Aug 2, 2024
d61adc4
remove toc in article, fix note
Aug 2, 2024
3cd731e
Merge remote-tracking branch 'origin/master' into reboot/fix/replay-p…
Aug 2, 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
160 changes: 84 additions & 76 deletions docs/user-guide/api-mediation/configuration-extender-passtickets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,33 +5,34 @@ One option for enabling single sign on is by configuring Zowe to use PassTickets
:::info Required Role: security administrator
:::

- [Overview of PassTickets](#overview-of-how-passtickets-are-used)
- [Overview of PassTickets](#overview-of-passtickets)
- [Configuring Zowe to use PassTickets](#configuring-zowe-to-use-passtickets)
- [Enabling PassTicket support](#enabling-passticket-support)
- [Enabling PassTickets with ACF2](#enabling-passtickets-with-acf2)
- [Enable PassTickets with Top Secret](#enabling-passtickets-with-top-secret)
- [Enabling PassTickets with RACF](#enabling-passtickets-with-racf)
- [Configuring security to allow the Zowe API Gateway to generate PassTickets for an API service](#configuring-security-to-allow-zowe-api-gateway-to-generate-passtickets-for-an-api-service)
- [Generating PassTickets using ACF2](#generating-passtickets-using-acf2)
- [Generating PassTickets using Top Secret](#generating-passtickets-using-top-secret)
- [Generating PassTickets using RACF](#generating-passtickets-using-racf)
- [Validating if the PassTicket Application is created](#validating-if-the-passticket-application-is-created)
- [Adding custom HTTP Auth headers to store user ID and PassTicket](#adding-custom-http-auth-headers-to-store-user-id-and-passticket)

## Overview of PassTickets
- [Enabling the use of PassTickets in your External Security Manager (ESM)](#enabling-the-use-of-passtickets-in-your-external-security-manager-esm)
- [Enabling PassTickets with ACF2](#enabling-passtickets-with-acf2)
- [Enabling PassTickets with Top Secret](#enabling-passtickets-with-top-secret)
- [Enabling PassTickets with RACF](#enabling-passtickets-with-racf)
- [Configuring security to allow Zowe API Gateway to generate PassTickets for an API service](#configuring-security-to-allow-zowe-api-gateway-to-generate-passtickets-for-an-api-service)
- [Generating PassTickets using ACF2](#generating-passtickets-using-acf2)
- [Generating PassTickets using Top Secret](#generating-passtickets-using-top-secret)
- [Generating PassTickets using RACF](#generating-passtickets-using-racf)
- [Validating if the PassTicket Application is created](#validating-if-the-passticket-application-is-created)
- [Adding custom HTTP Auth headers to store user ID and PassTicket (Optional)](#adding-custom-http-auth-headers-to-store-user-id-and-passticket-optional)

## Overview of PassTickets

API clients can use various supported methods to access an API service such as a Zowe JWT token or a client certificate even if the API service itself does not support the JWT token or a client certificate. An intermediary for this support can be through the use of PassTickets.

When an API client provides a valid authentication method to API ML, the API Gateway generates a valid PassTicket for any API service that supports PassTickets. A PassTicket is a one-time only password that is generated for a specific user ID.
When an API client provides a valid authentication method to API ML, the API Gateway generates a valid PassTicket for any API service that supports PassTickets. A PassTicket is a one-time only password that is generated for a specific user ID.
The API Gateway uses the PassTicket to access that API service.
The API Gateway provides the user ID and password in the Authorization header of the HTTP requests using the
[Basic authentication scheme](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#Basic_authentication_scheme).
[Basic authentication scheme](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#Basic_authentication_scheme).

## Configuring Zowe to use PassTickets

Configuring Zowe to use PassTickets involves two processes:
* Enabling the use of PassTickets in your External Security Manager (ESM)
* Configuring security to allow the Zowe API Gateway to generate PassTickets for an API service

- Enabling the use of PassTickets in your External Security Manager (ESM)
- Configuring security to allow the Zowe API Gateway to generate PassTickets for an API service

### Enabling the use of PassTickets in your External Security Manager (ESM)

Expand All @@ -40,7 +41,7 @@ This section applies to users who do not already have PassTickets enabled in the
:::tip
To validate if a PassTicket is already defined, use the commands that correspond to your ESM. If the PassTicket is defined, the access of the zoweuser can be determined.

* **Validating an existing PassTicket for ACF2**
- **Validating an existing PassTicket for ACF2**

<details>

Expand All @@ -61,106 +62,111 @@ To validate if a PassTicket is already defined, use the commands that correspond
SET RESOURCE(PTK)
LIST LIKE(IRRPTAUTH-)
```
* **`-`**

- **`-`**
A wildcard symbol that lists all resources

* **`<applid>-`**
- **`<applid>-`**
Lists everything related to specified applid in a resource (in this case, SAF), or specified in a profile (in this case, PTKTDATA)

</details>

* **Validating an existing PassTicket for Top Secret**
- **Validating an existing PassTicket for Top Secret**

<details>

<summary>Click here for details about validating an existing PassTicket for Top Secret.</summary>

In your ESM command line interface or other security environment, execute the following commands:

```
TSS WHOHAS APPL(<applid>)
TSS WHOHAS PTKTDATA(<applid>)
TSS WHOHAS PTKTDATA(IRRPTAUTH.<applid>.)
```

* **`.`**
- **`.`**
A wildcard symbol that lists all resources

* **`IRRPTAUTH.<applid>.`**
- **`IRRPTAUTH.<applid>.`**
Returns everything about the specified applid for IRRPTAUTH

</details>

* **Validating an existing PassTicket for RACF**
- **Validating an existing PassTicket for RACF**

<details>

<summary>Click here for details about validating an existing PassTicket for RACF.</summary>

In your ESM command line interface or other security environment, execute the following commands:

```
```rac
RLIST APPL * ALL
RLIST APPL <applid> ALL
RLIST PTKTDATA <applid> SSIGNON ALL
RLIST PTKTDATA IRRPTAUTH.<applid>.* ALL
```

Ensure that you validate PKTDATA access for APPL.

* **`*`**
- **`*`**
A wildcard symbol that resturns all resources

* **`RLIST PTKTDATA <applid> SSIGNON ALL`**
- **`RLIST PTKTDATA <applid> SSIGNON ALL`**
Validates all applid for PTKDATA class

* **`RLIST PTKTDATA IRRPTAUTH.<applid>.* ALL`**
- **`RLIST PTKTDATA IRRPTAUTH.<applid>.* ALL`**
Validates all applid permissions for PTKDATA class

</details>

:::

Follow these steps to enable PassTicket Support specific to your ESM. Consult with your security administrator to perform the following procedures.
Follow these steps to enable PassTicket Support specific to your ESM. Consult with your security administrator to perform the following procedures.

#### Enabling PassTickets with ACF2

<details>

<summary> Click here for details about configuring Zowe to use PassTickets using ACF2. </summary>

1. In your ESM command line interface or other security environment, define the application session key by entering the following commands, if the session key is not already defined.

1. In your ESM command line interface or other security environment, define the application session key by entering the following commands, if the session key is not already defined.

```
```acf2
SET PROFILE(PTKTDATA) DIV(SSIGNON)
INSERT <applid> SSKEY(<key-description>) MULT-USE
pablocarle marked this conversation as resolved.
Show resolved Hide resolved
F ACF2,REBUILD(PTK),CLASS(P)
```

* **applid**
- **applid**
Specifies the application ID used for PassTicket validation to authenticate connections to the server.

* **MULT-USE**
- **MULT-USE**
This setting lets you reuse the same PassTicket multiple times.

* **key-description**
- **key-description**
Specifies the secured sign-on hexadecimal application key of 16 hexadecimal digits (8-byte or 64-bit key). Each application key must be the same on all systems in the configuration and the values must be kept secret and secured.

2. Complete the PassTicket setup by entering the following commands:
```

```acf2
F ACF2,REBUILD(PTK),CLASS(P)
```

The PassTicket record is now active in the system.

3. Enable the started task user ID to generate PassTickets for the application by entering commands similar to the following:

```
SET RESOURCE(PTK)
RECKEY IRRPTAUTH ADD(applid.userid UID(<userid>) SERVICE(UPDATE,READ) ALLOW)
```
* `<userid>`
Specifies the Zowe server user ID

- `<userid>`
Specifies the Zowe server user ID

You configured Zowe to use PassTickets using ACF2.
You configured Zowe to use PassTickets using ACF2.

</details>

Expand All @@ -172,52 +178,55 @@ You configured Zowe to use PassTickets using ACF2.

Before you begin this procedure, verify that the `PTKTDATA` class and ownership for the PassTicket resource (`IRRPTAUT`) have not already been defined.

1. Update the resource descriptor table (RDT) to define the `PTKTDATA` class by entering the following commands:
1. Update the resource descriptor table (RDT) to define the `PTKTDATA` class by entering the following commands:

:::note
The PTKTDATA resource is not a predefined class.
:::

```
```tss
TSS ADDTO(RDT) RESCLASS(PTKTDATA) RESCODE(n) ACLST(ALL,READ,UPDATE) MAXLEN(37)
```

The PTKTDATA resource is added to the RDT.

:::note
Include `RESCODE(n)` in the range of 101 to 13F to make `PTKTDATA` a prefixed resource class.
:::

2. Assign ownership for the PassTicket resource (`IRRPTAUT`). Execute the following commands:
```
2. Assign ownership for the PassTicket resource (`IRRPTAUT`). Execute the following commands:

```tss
TSS ADDTO(department) PTKTDATA(IRRPTAUT)
```
3. Define PassTicket for application ID _applid_ without replay protection.

```
3. Define PassTicket for application ID _applid_

```tss
TSS ADDTO(NDT) PSTKAPPL(<applid>) SESSKEY(<key-description>) SIGNMULTI
pablocarle marked this conversation as resolved.
Show resolved Hide resolved
```

* **applid**
- **applid**
Specifies the application ID used for PassTicket validation to authenticate connections to the server.

* **key-description**
- **key-description**
Specifies the secured sign-on hexadecimal application key of 16 hexadecimal digits (8-byte or 64-bit key). Each application key must be the same on all systems in the configuration and the values must be kept secret and secured.

4. Permit access to the PassTicket resource defined in the previous step for the LDAP Server by executing the following command:
```

```tss
TSS PERMIT(<stc-userid>) PTKTDATA(IRRPTAUTH.applid) ACCESS(UPDATE)
```

* **stc-userid**
Specifies the ACID that you created when you created LDAP Server started task User IDs. The parameter is "CALDAP" by default.
- **stc-userid**
Specifies the ACID that you created when you created LDAP Server started task User IDs. The parameter is "CALDAP" by default.

You configured Zowe to use PassTickets using Top Secret.

</details>

#### Enabling PassTickets with RACF


<details>

<summary> Click here for details about configuring Zowe to use PassTickets using RACF.</summary>
Expand All @@ -226,48 +235,48 @@ You configured Zowe to use PassTickets using Top Secret.

In your ESM command line interface or other security environment, execute the following command:

```
```racf
SETROPTS CLASSACT(PTKTDATA) RACLIST(PTKTDATA)
```

2. Specify the application ID requiring access through PassTicket for the ZOWE server with the following commands:
```

```racf
RDEFINE APPL <applid> UACC(READ)
SETROPTS CLASSACT(APPL)
SETROPTS GENERIC(PTKTDATA)
```

* ***applid**
A one to 8 character name designated for the application.
- ***applid**
A one to 8 character name designated for the application.

:::note
:::note
This name is usually provided by the site security administrator.
:::

3. Define the profile for the application with the following command:

```racf
RDEFINE PTKTDATA <applid> UACC(NONE) SSIGNON(KEYMASKED(<key-description>))
```
RDEFINE PTKTDATA <applid> UACC(NONE) APPLDATA('NO REPLAY PROTECTION') SSIGNON(KEYMASKED(<key-description>) APPLDATA('NO REPLAY PROTECTION')
```
* **key-description**

- **key-description**
Specifies the secured sign-on hexadecimal application key of 16 hexadecimal digits (8-byte or 64-bit key). Each application key must be the same on all systems in the configuration and the values must be kept secret and secured.

Replace `key-description` with the application name defined previously.

:::caution Important
PassTickets for the API service must have the replay protection switched off. This links a secured sign-on application key with the application.
:::

4. Allow the application ID (_applid_) to use PassTickets:

```
```racf
PERMIT IRRPTAUTH.applid.* CLASS(PTKTDATA) ACCESS(UPDATE) ID(userid)
```

* **userid**
- **userid**
Specifies the value of the LDAP Server started task.

5. Refresh the RACF PTKTDATA definition with the new profile:
```

```racf
SETROPTS RACLIST(PTKTDATA) REFRESH
```

Expand All @@ -281,10 +290,10 @@ As a security administrator, you can issue security commands to allow the Zowe s

Specify the following variables when generating PassTickets for the API service to enable the Zowe started task user ID:

* **applid**
- **applid**
The APPLID value used by the API service for PassTicket support (e.g. `OMVSAPPL`)

* **zowe-user-id**
- **zowe-user-id**
The Zowe started task user ID used during the Zowe installation

In the following examples of ESM configuration, replace these variables with actual values.
Expand All @@ -301,7 +310,7 @@ Grant the Zowe started task user ID permission to generate PassTickets for users

**Example:**

```markup
```acf
ACF
SET RESOURCE(PTK)
RECKEY IRRPTAUTH ADD(<applid>.- UID(<zowe-user-id>) SERVICE(UPDATE,READ) ALLOW)
Expand All @@ -326,7 +335,6 @@ TSS PERMIT(<zowe-user-id>) PTKTDATA(IRRPTAUTH.<applid>.) ACCESS(READ,UPDATE)
TSS REFRESH
```


</details>

#### Generating PassTickets using RACF
Expand All @@ -339,27 +347,27 @@ Grant the Zowe started task user ID permission to generate PassTickets for users

**Example:**

```markup
```racf
PERMIT IRRPTAUTH.<applid>.* CL(PTKTDATA) ID(<zowe-user-id>) ACCESS(UPDATE)
SETROPTS RACLIST(PTKTDATA) REFRESH
```

</details>

### Validating if the PassTicket Application is created

In your ESM command line interface or other security environment, execute the following commands:

```
```racf
RLIST APPL <applid> ALL
RLIST PTKTDATA IRRPTAUTH.<applid>.* ALL
```

* **applid**
- **applid**
The APPLID value used by the API service for PassTicket support

Successful execution of this validation command shows your application and the specific access of the application.


## Adding custom HTTP Auth headers to store user ID and PassTicket (Optional)

If a downstream (southbound) service needs to consume the PassTicket and the user ID from custom headers to participate in the Zowe SSO, you can define the custom HTTP headers names as part of the Gateway configuration.
Expand All @@ -372,4 +380,4 @@ Use the following procedure to add the custom HTTP headers.
3. Find or add the property `components.gateway.apiml.security.auth.passticket.customUserHeader` and set the value which represents the name of the header.
4. Restart Zowe.

Requests through the Gateway towards the southbound service now contain the custom HTTP headers with the PassTicket and the user ID.
Requests through the Gateway towards the southbound service now contain the custom HTTP headers with the PassTicket and the user ID.
Loading