VERIFY TOKEN

Verify that a security token is valid as determined by RACF, and optionally allow the caller to extract or generate security information from this token.

VERIFY TOKEN

Conditions: INVREQ, LENGERR, NOTAUTH

This command is threadsafe.

Description

The VERIFY TOKEN command supports the following types of security tokens:

Basic Authentication Tokens (BASICAUTH): A basic authentication token is a token in the form userid:password. The password might be a password, a passphrase, a PassTicket, or an MFA token. For convenience, when the token is transferred over the web header, it might be passed in Base64 format. For information, see How it works: Passwords and passphrases, How it works: PassTickets , and How it works: Multi-factor authentication (MFA).; The primary purpose of using the VERIFY TOKEN command with a basic authentication token is to generate a JWT in OUTTOKEN. In particular, this allows one-time-use tokens, such as PassTicket and MFA tokens to generate a cryptographically secure, time-limited multi-use token.
JSON Web Tokens (JWT): The VERIFY TOKEN command verifies that a JWT token is valid as determined by RACF. It can also generate a JWT as described in Basic Authentication Tokens (BASICAUTH). For information, see How it works: JSON Web Token (JWT).
Kerberos Tokens (KERBEROS): The VERIFY TOKEN command verifies that a Kerberos token is valid as determined by RACF. The command optionally returns the user ID of a Kerberos principal that is associated with the token. If the Kerberos token indicates that mutual authentication is in use, the command returns a Kerberos output token.
The CICS® region in which the command is run must be authorized by RACF® so that the Kerberos principal for the token can be obtained. For information, see How it works: Kerberos.

The VERIFY TOKEN command verifies whether a token is valid as determined by RACF and optionally outputs security-related information. The command does not depend on the principal facility; therefore, it can be issued in non-terminal environments, for example, to provide authentication for web requests or web services requests. For information about a security failure of this command, see the error messages that are written to destination CSCS.

VERIFY TOKEN requests run on an open TCB if possible. If the VERIFY TOKEN is issued on an open TCB, it runs the request on this TCB. If the VERIFY TOKEN command is not issued on an open TCB, it switches to an open TCB if one is available, otherwise it switches to the Resource Owning (RO) TCB. For best performance, set the MAXOPENTCBS to a high enough value to allow sufficient open TCBs for the workload, and define any programs that use VERIFY TOKEN as threadsafe.

Options

DATATYPE

Specifies the type of data in the TOKEN. CVDA values are as follows:

BIT

Bit data. This is the default value.

BASE64

Base64 encoded character data. The acceptable characters are A-Z a-z 0-9 + / =.

If your character data is not in a US EBCDIC compatible character CCSID, you must convert it. You can use the CONTAINER API to do the conversion.

BASE64 is supported only for TOKENTYPE values of BASICAUTH and KERBEROS.

ENCRYPTKEY(data-area)

This is the 4-byte token to be used to encrypt a returned PassTicket. For Kerberos, if ENCRYPTKEY is specified, TOKEN must be a Kerberos token that is obtained from a Security Token Service that supports message confidentiality.

ESMREASON(data-area)

Returns the reason code, in a fullword binary field, that CICS receives from RACF.

This field is the RACF reason code as follows:

For BASICAUTH and JWT, response and reason codes are documented in RACROUTE VERIFY in the z/OS® Security Server RACF documentation.
For KERBEROS, response and reason codes are documented in GSS-API Subfunction codes in z/OS Security Server RACF Callable Services. For an explanation of a reason code, see R_GenSec Return and reason codes in z/OS Security Server RACF Callable Services and Status codes in z/OS Integrated Security Services Network Authentication Service Administration.

ESMRESP(data-area)

Returns the response code, in a fullword binary field, that CICS receives from RACF.

This field is the RACF return code. See ESMREASON(data-area) for sources of information about the return code.

ISUSERID(data-area)

Returns an 8-byte user ID that is associated with the token.

OUTTOKEN(ptr-ref)

Returns the address in 31-bit task storage of the output token that is obtained from RACF.

OUTTOKENLEN(data-area)

Returns the length of an output token, in a fullword binary field.

TOKEN(data-area)

A security token of the type described in TOKENTYPE.

If TOKEN is a Kerberos token that indicates mutual authentication is in use, you must specify OUTTOKEN and OUTTOKENLEN. In this case, OUTTOKEN returns an output token that is obtained from RACF, and OUTTOKENLEN returns the length of the output token. The calling program should return the output token to the system that supplied the Kerberos token to allow authentication of the CICS region.

If TOKEN is a Kerberos token that does not indicate that mutual authentication is in use, and if OUTTOKEN and OUTTOKENLEN are specified, the values that are returned in these options are zero.

TOKENLEN(data-value)

The length of the token as a fullword binary value.

TOKENTYPE(cvda)

Indicates the type of token. CVDA values are as follows:

BASICAUTH: A basic authentication token in the form userid:password. The password might be a password, a passphrase, a PassTicket, or an MFA token.
Leading and trailing blanks are not supported for either userid or password. The colon is a required separator.
JWT: A JSON Web Token.
KERBEROS: A Kerberos token obtained from a Security Token Service (STS).

Conditions

16 INVREQ

RESP2 values are as follows:

13: The value that is returned by RACF in ESMRESP is not classified by CICS. See the ESM documentation for an explanation of the ESMRESP and ESMREASON values.
18: The CICS external security manager interface is not initialized.
29: RACF is not responding.
31: An invalid CVDA value was specified for TOKENTYPE.
32: A CVDA value other than BASE64 or BIT was specified for DATATYPE.
36: A data type of BASE64 was specified, but TOKEN does not contain BASE64 data.
37: BASE64 is not valid for this DATATYPE.
40: The key distribution center is not started or is terminating.
41: The key distribution center is not responding.
47: RACF does not have a user ID defined for the Kerberos principal that is associated with the token.
50: The data that is specified in TOKEN is not a Kerberos token.
51: The Kerberos token does not support message confidentiality.
52: The Kerberos token indicates that mutual authentication is in use, but OUTTOKEN and OUTTOKENLEN are not specified on the command.
53: This CICS region is not configured to support Kerberos. To enable Kerberos support, specify the SIT parameter KERBEROSUSER with the user ID that is associated with the service principal.
60: The token that is specified in TOKEN is not well formed.
62: An error occurred in ICSF.
63: A token is not generated due to a configuration error.
64: The MFA token is incomplete. Only single tokens are supported.
65: The external security manager (ESM) does not support JWT tokens.
100: IDTDATA class is not active.
103: The JWT is not signed.
104: ICSF is unavailable.
105: An ICSF error has occurred.

22 LENGERR

RESP2 values are as follows:

45: The length of the Kerberos token exceeds the maximum value of 65535.

Default action: terminate the task abnormally.

70 NOTAUTH

RESP2 values are as follows:

20: RACF does not authorize the request to verify the token. See the error messages that are written to destination CSCS.
42: A Kerberos request cannot be completed because the associated ticket expired.
43: The authenticator expired.
61: The token is not accepted.
70: The user ID is revoked.

Default action: terminate the task abnormally.