VERIFY TOKEN
Verify that a security token is valid as determined by an external security manager (ESM), and optionally allow the caller to extract or generate security information from this token.
Description
- Basic Authentication Tokens (BASICAUTH)
- JSON Web Tokens (JWT)
- Kerberos Tokens (KERBEROS)
The VERIFY TOKEN command verifies whether a token is valid as determined by an external security manager 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 more information about a security failure of this command, see the error messages that are written to destination CSCS.
- Support for 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 base 64 format. 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. - Support for JSON Web Tokens (JWT)
- The VERIFY TOKEN command verifies that a JWT token is valid as determined by
the external security manager. It can also generate a JWT as described in Support for Basic Authentication Tokens (BASICAUTH).
CICS® supports only signed JWTs. A JWT is in the form described by JSON Web Token (JWT) Specification RFC 7519. If the external security manager is RACF®, for CICS to support JWTs, you must create profiles in the IDTDATA class, as described in Support for JWT using RACF.
- Support for Kerberos Tokens (KERBEROS)
- The VERIFY TOKEN command verifies that a Kerberos token is valid as
determined by an external security manager. The command optionally returns the user ID of a Kerberos
principal that is associated with the token. If the Kerberos token indicates mutual
authentication is in use, the command returns a Kerberos output token.
If the external security manager is RACF, 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 more information, see Configuring RACF for Kerberos.
If ENCRYPTKEY is specified, TOKEN must be a Kerberos token that is obtained from a Security Token Service that supports message confidentiality.
If TOKEN is a Kerberos token that indicates mutual authentication is in use, OUTTOKEN and OUTTOKENLEN options must be specified. In this case, OUTTOKEN returns an output token that is obtained from an external security manager such as z/OS® Security Server, 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 mutual authentication is in use, and if OUTTOKEN and OUTTOKENLEN are specified, the values returned in these options are zero.
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 BASICAUTH and KERBEROS.
- ENCRYPTKEY(data-area)
- This is the 4-byte token to be used to encrypt a returned PassTicket.
- ESMREASON(data-area)
- Returns the
reason code, in a fullword binary field, that CICS receives
from the external security manager. If the external security manager is RACF, this field is the RACF reason code as follows:
- For BASICAUTH and JWT, response and reason codes are documented in the topic about the RACROUTE VERIFY command in the z/OS Security Server RACF documentation.
- For KERBEROS, response and reason codes are documented in . See 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 the external security manager.
If the external security manager is RACF, this field is the RACF return code.
See ESMREASON and follow the documentation links for information about ESMRESP values.
- 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 an external security manager.
- 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.
- 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.Leading and trailing blanks are not supported for either userid or password. The colon is a required separator. The password can be a password, a passphrase, an MFA token, or a PassTicket.
- JWT
- A JSON Web Token.
- KERBEROS
- A Kerberos token obtained from a Secure Token Server (STS).
Conditions
- 16 INVREQ
- RESP2
values are as follows:
- 13
- The value that is returned by the external security manager 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
- The external security manager 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
- The external security manager 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 mutual authentication is in use, but OUTTOKEN and OUTTOKENLEN have not been 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 associated with the service principal.
- 60
- The token specified in TOKEN is not well formed.
- 62
- An error has occurred in ICSF.
- 63
- A token has not been generated due to a configuration error.
- 64
- The MFA token is incomplete. Only single tokens are supported.
- 65
- The external security manager (ESM) doesn’t support JWTs.
- 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.
- 70 NOTAUTH
- RESP2 values
are as follows:
- 20
-
The external security manager 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.