SIGNON TOKEN

Validate a security token and sign on to a terminal with the user ID extracted from the token.

SIGNON TOKEN

Conditions: INVREQ, LENGERR, NOTAUTH

This command is threadsafe.

Description

The SIGNON TOKEN command enables your application to validate a Kerberos security token, as determined by an external security manager (ESM), and associate a new user ID with the current terminal. When you use the SIGNON TOKEN command, the following applies:

The sign-on operation is terminal related only. Sign-on has no meaning if the transaction does not have a terminal as its principal facility.
When you issue an EXEC CICS® SIGNON TOKEN command, CICS modifies the state of the terminal that is the principal facility of the transaction that issues the command.
Sign-on does not affect the user ID and security capabilities currently in effect for the transaction issuing the command. This is because:
- A transaction's user ID and security capabilities are established at transaction-attach time. It is not possible to modify these subsequently during the life of the transaction.
- All actions performed by a transaction (whether to a local or remote resource, or to a connected system) take place in the security context established at the time the transaction was attached.
The SIGNON TOKEN command uses the z/OS® Security Server to verify that the token is a valid Kerberos token and that it can be used by the CICS region.
If the ESM 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.
There is no implied sign-off with the SIGNON TOKEN command. If your application program attempts to associate a new user with a terminal that already has a signed-on user ID, CICS returns an INVREQ (Resp2=9) error response.

For more information about how CICS uses the USERID and GROUPID, see Verifying CICS users.

For more information about a security failure of this command, see the error messages that are written to destination CSCS.

Options

If an optional input field contains all blanks, it is ignored.

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.

ESMREASON(data-area)

Returns the reason code, in a fullword binary field, that CICS receives from the external security manager.

If the ESM is RACF, this field is the RACF reason code.

The ESM does not always return response and reason codes to CICS. Make sure that you check the EIBRESP and EIBRESP2 values that are returned by this command in addition to checking the ESMRESP and ESMREASON values.

ESMRESP(data-area)

Returns the response code, in a fullword binary field, that CICS receives from the external security manager.

If the ESM is RACF, this field is the RACF return code.

GROUPID(data-value)

Assigns, to a RACF user group, the user that is being signed on. This overrides, for this session only, the default group name specified for the user in the RACF database.

LANGUAGECODE(data-value)

Specifies the national language that the user being signed on wants CICS to use. You specify the language as a standard 3-character IBM® code. This is an alternative to the 1-character code that you specify on the NATLANG option.

See National language codes for possible values of the code.

Note: CICS messages are supported only in UK English, Simplified Chinese, and Japanese. If any other language other than those three is specified, English is used by default.

LANGINUSE(data-area)

The LANGINUSE option allows an application program to receive the national language chosen by the sign-on process. The language is identified as a standard three-character IBM code, instead of the one-character code used by NATLANGINUSE. It is an alternative to the existing NATLANGINUSE option.

See National language codes for possible values of the code.

NATLANG(data-value)

Specifies a 1-character field identifying the national language the user wants to use during the signed-on session.

See National language codes for possible values of the code.

Note: CICS messages are supported only in UK English, Simplified Chinese, and Japanese. If any other language other than those three is specified, English is used by default.

NATLANGINUSE(data-area)

Specifies a one-character code for the national language used during the signed-on session. The current implementation always returns the character E (U.S. English), which corresponds to the language supplied in the NATLANG option. NATLANGINUSE corresponds to the following (in order of decreasing priority):

The language supplied in the NATLANG option of the SIGNON TOKEN command.
The language associated with the user. This is specified in the ESM language segment.
The language associated with the definition of the terminal.
The language associated with the default USERID for the CICS region.
The default language specified in the system initialization parameters.

See National language codes for possible values of the code.

TOKEN(data-area)

A token that has been obtained from a Security Token Service (STS).

TOKENLEN(data-value)

The length of the token as a fullword binary value.

TOKENTYPE(cvda)

Indicates the type of token.

KERBEROS: The token is a Kerberos token.

Conditions

16 INVREQ

RESP2 values:

9: The terminal is already signed on.
10: No terminal is associated with this task.
11: This task's terminal has preset security.
12: The response from CICS security modules is unrecognized.
13: There is an unknown return code in ESMRESP from the external security manager (ESM), or the ESM is not active, or has failed in an unexpected way.
14: The required national language is not available.
15: Signon was attempted using transaction routing without using the CRTE transaction.
18: The CICS ESM interface is not initialized (SEC=NO specified as a System initialization parameter).
25: The terminal is of an invalid type.
26: An error occurred during SNSCOPE checking. The limit of MVS™ ENQ requests was reached.
27: The ESM is not active.
28: The required national language is invalid.
29: The user is already signed on. This relates to the sign-on scope checking.
30: The ESM is not responding.
31: A CVDA value other than KERBEROS 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.
40: The key distribution center is not started or is terminating.
41: The key distribution center is not responding.
47: The ESM does not have a user ID defined for the Kerberos principal that is associated with the token.
50: The data specified in TOKEN is not a Kerberos token
200: Command not allowed for a distributed program link server program.

Default action: terminate the task abnormally.

22 LENGERR

RESP2 values:

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

70 NOTAUTH

RESP2 values:

16: The USERID is not authorized to use this terminal.
17: The USERID is not authorized to use the application.
19: The USERID is revoked.
20: The USERID's access to the specified group has been revoked.
21: The sign-on failed during SECLABEL checking.
22: The sign-on failed because the ESM is not currently accepting sign-on.
23: The GROUPID is not known to the ESM.
24: The USERID is not contained in the GROUPID.
40: The ESM does not authorize the request to verify the token. Error messages are written to destination CSCS.
42: A Kerberos request cannot be completed because the associated ticket has expired.
43: The authenticator has expired.

Default action: terminate the task abnormally.