This section covers the following topics:
Natural RPC also supports Natural Security in client/server environments, where security may be active on either (or both) sides.
For general information, refer to the Natural Security documentation.
For information on how to control the use of Natural RPC (Remote Procedure) calls in a client/server environment, see Protecting Natural RPC Servers and Services in the Natural Security documentation.
The client must send logon data together with the RPC request. The logon data consist of user ID, password and library.
User ID and password are used to perform the authentication of the client on the Natural RPC server side.
The library is used to perform a Natural Security protected logon to the requested library.
The following applies to Natural RPC clients only. For EntireX RPC clients that access a Natural Security protected Natural RPC server, refer to the EntireX Developer’s Kit documentation.
To send logon data to the Natural RPC server, the Logon option must be used. See Operating a Natural RPC Environment, Using the Logon Option. The logon data parts are established as follows:
The user ID and password:
The user ID and password from the Natural Security logon on the client are used and passed to the Natural RPC server.
If you want to use a different user ID and/or password for the
Natural Security logon on the server side, you may use the application
programming interface USR1071N (see below).
Note:
You may disallow the use of USR1071N in the Natural
RPC restrictions part of the
Session
Parameters restrictions of the Natural Security library
profile.
To specify the user ID and password that are passed to the Natural
RPC server, the client must call application programming interface
USR1071N (see below) before the first RPC request is sent.
The library:
By default, the name of the library to which the client is currently
logged on is used. If you want to pass another library name to the Natural RPC
server, you may use the application programming interface
USR4008N.
If impersonation without password check is active for the Natural RPC
server (field Impersonation described in the section
Components of an RPC Server Profile in the Natural
Security documentation is set to A), the client may
optionally pass an ETID to the Natural RPC server. This ETID will be used by
the Natural RPC server to access Adabase on behalf of the client. To specify an
ETID on the Natural RPC client side, you may use the application programming
interface USR4371N.
The application programming interface USR1071N is provided
in the library SYSEXT. It is used to specify the user ID and
password that are passed to the Natural RPC server.
To make use of USR1071N
Copy the subprogram USR1071N and the program
USR1071P from libray SYSEXT to the library
SYSTEM in the system file FNAT in the server
environment; see Using a Natural
API in the SYSEXT Utility
documentation.
Using a DEFINE
DATA statement, specify the following parameters:
| Parameter | I/O | Format | Description | |
|---|---|---|---|---|
USERID |
I | A08 | User ID to be used. | |
PASSWORD |
I | A08 | Password to validate the user ID. This password is not validated on the client side. | |
MIXEDCASE |
I | A01 | Mixed case option for password (optional). | |
Y |
Allow mixed case password. | |||
N |
Convert passwords to upper case. | |||
In the calling program on the client side, specify the following statement:
FETCH RETURN 'USR1071P' USERID PASSWORD
[MIXEDCASE]
You may alternatively invoke USR1071P from the command
line and enter user ID and password in the displayed window.
For a more detailed description, see the USR1071T text
object in the system library SYSEXT.
Note:
Two samples are provided to call USR1071N:
USR1071P, which is passing just user ID and password, and
USR1071X (extended version), which in addition enables the user to
set/retrieve various data.
The application programming interface USR4371N is provided
in the library SYSEXT. It is used to specify the user ID and the
ETID that are passed to the Natural RPC server.
To make use of USR4371N
1. Copy the subprogram USR4371N and the program
USR4371P from libray SYSEXT to the library
SYSTEM in the system file FNAT in the client
environment; see Using a Natural API
Using a DEFINE
DATA statement, specify the following parameters:
| Parameter | I/O | Format | Description | |
|---|---|---|---|---|
USERID |
I | A08 | User ID to be used. | |
ETID |
I | A08 | ETID to be used. | |
In the calling program on the client side, specify the following statement:
FETCH RETURN 'USR4371P' USERID ETID
Alternatively, you may invoke USR4371P from the command
line, and enter user ID and ETID in the displayed window.
For a more detailed description, see the text object
USR4371T in the system library SYSEXT.
If Natural Security is installed on the server side and
AUTO=ON
is not specified, a Natural logon with user ID and password is required. It is
recommended to use the Natural profile parameter
STACK to
pass the Natural system command LOGON. If
AUTO=ON is specified the contents of
*INIT-USER
is used for an internal logon as usual.
To enforce the Logon option - that is, if you want a server to accept
only requests from clients where the Logon option is set - set the
profile parameter LOGONRQ
to ON for the server. If the Logon option is not enforced, client
request without logon data are accepted and executed in the server library or
one of its steplibs. This allows you to provide public as well as secured
services.
If the client passes logon data, the user ID and password from the client are verified against the corresponding user security profile on the server, and the logon to the requested library and the execution of the subprogram are performed according to the corresponding Natural Security library and user profile definitions on the server.
After the execution of the subprogram, the library used before the
CALLNAT request is updated again on the server. In the case of a
conversational RPC, the first CALLNAT request within the
conversation sets the library ID on the server, and the CLOSE
CONVERSATION statement resets the library ID on the server to the one
used before the conversation was opened.
As part of the Natural RPC
Restrictions in the library profiles of Natural Security,
a server session option Close all databases is provided. It causes
all databases which have been opened by remote subprograms contained in the
library to be closed when a Natural logon/logoff to/from the libraries is
performed. This means that each client uses its own database session.
If the Close all databases option is set, it is also
possible to use a client specific ETID for all Adabas accesses which are
executed by the server for this client. In this case, you should start the
Natural RPC server with ETID=OFF and define an
appropriate ETID in the user profile for each client that needs an ETID,
forexample, by specifying the ETID *USER. Please note that in this
case two clients with the same name cannot issue two concurrent requests with
Adabas calls.
Changing Password
It is possible to change the
Natural Security password on the Natural RPC server via a Natural RPC service
request. For this purpose, the application programming interface
USR2074N is provided in the library SYSEXT.
To make use of USR2074N
Copy the subprogram USR2074N, and optionally program
USR2074P, from libray SYSEXT to the library
SYSTEM or to the steplib library or to any application in the
server environment.
Using a DEFINE
DATA statement, specify the following parameters:
| Parameter | I/O | Format | Description | |
|---|---|---|---|---|
USERID |
I | A08 | User ID to be used. | |
PASSWORD |
I | A08 | Password to validate the user ID. This password is not validated on the client side. | |
NEWPASSWORD |
I | A08 | New password for the user ID. This password is not validated on the client side. | |
NODE-NAME |
I | A192 | Name of the server node to be
addressed.
The node name may have up to 32 characters for physical node names and up to 192 characters for logical node names. See Using EntireX Location Transparency in Operating a Natural RPC Environment. The sample |
|
SERVER-NAME |
I | A192 | Name of the server to be
addressed.
The server name may have up to 32 characters for physical server names and up to 192 characters for logical service names. See Using EntireX Location Transparency in Operating a Natural RPC Environment. The sample |
|
PROTOCOL |
I | A1 | The transport protocol to address the server node. Valid value: | |
B |
EntireX Broker | |||
RC |
O | I2 | Return value: | |
0 |
OK, MESSAGE contains a confirmation
message.
|
|||
1 |
Error from RPC or server node,
MESSAGE contains the error message.
|
|||
2 |
Error from the interface, MESSAGE
contains the error message.
|
|||
3 |
Natural Security error, MESSAGE#
contains the Natural error number and MESSAGE contains
the corresponding message text.
|
|||
MESSAGE# |
O | N4 | Message number returned. | |
MESSAGE |
O | A80 | Message text returned. | |
In the calling program on the client side, specify the following statement:
CALLNAT 'USR2074N' user-id password newpassword
node-name server-name protocol rc message# message
You may alternatively use program USR2074P from library
SYSEXT. Invoke USR2074P from the command line and
enter the required data in the displayed window. In this case, all input except
for the passwords are converted into upper case. For the passwords, you have
the option to enter them in mixed case or not.
Impersonation is an
optional feature on the Natural RPC server side and is only available if the
Natural RPC server runs under Natural Security. The impersonation feature is
controlled by the Security Profiles for Natural RPC
Servers. See the field Impersonation
described under the heading Components of an RPC Server
Profile in the section Protecting Natural RPC Servers and
Services in the Natural Security
documentation.
Impersonation in z/OS batch mode requires the use of the Natural RPC server front-end under z/OS and uses the SAF interface provided by z/OS.
If impersonation is active for the Natural RPC server, a client request
that uses the Logon option is
from the perspective of the operating system executed under the user ID that
the client passes in the LOGON data (called Natural RPC user ID).
Impersonation assumes that access to the operating system on which a Natural
RPC server is running is controlled by an SAF-compliant external security
system. User authentication (verification of the Natural RPC user ID and
password) is performed by this external security system. After successful
authentication, the user's identity is established for the operating system
(that is, an ACEE is created and linked to the TCB under which the current
client request is executed). Any subsequent authorization checks will be
performed based on this identity. This means that all accesses to resources
that are controlled by the SAF compliant external security system are
authorized for this identity. This applies especially to accesses to work files
and to data bases.
Impersonation does not turn off Natural Security. After successful
authentication of the user's identity by the external security system, a
Natural Security logon takes place using the same LOGON data but
without password verification.
To start a Natural RPC server using impersonation, see Starting a Natural Server Using the RPC Server Front-End in Starting a Natural RPC Server.
Note:
Without impersonation, a client request that uses the Logon option
is from the perspective of the operating system executed with the user ID under
which the Natural RPC server has been started.
Proceed as described in the corresponding steps of the Natural for Mainframes installation documentation; see Installing Natural on z/OS.
If you choose to use the recommended APF-authorized
LINKLIST library, you must ensure that the resulting load module
does not exist in the STEPLIB or JOBLIB
concatenation.
DSNRLIThis step applies to Natural for DB2 users only.
ADALNKR instead of ADALNKRefer to Considerations for Mainframe Natural RPC Servers with Replicas in Starting a Natural RPC Server.
BROKER instead of
NATETB23See Provide Access to the EntireX Broker Stub on Mainframe in Setting Up a Natural RPC Environment.
Refer to Set the RPC Server-Specific
Natural Parameters in Setting Up a Natural RPC
Environment. The parameters are either defined in the
Natural parameter module or in the
CMPRMIN dataset. The parameter
PARM= of the JCL EXEC statement is not used
to provide Natural profile parameters.
Define an RPC server profile in Natural Security (NSC) for the server
name that is used by the RPC server (SRVNAME) and activate the
impersonation.
Refer to Security Profiles for Natural RPC Servers in Protecting Natural RPC Servers and Services of the Natural Security documentation.
(This step applies to Natural for DB2 users only.)
If the SAF resource class DSNR is active, you must check
whether you need the following SAF definitions:
RDEFINE DSNR (subsys.RRSAF)
OWNER(DB2owner)
PERMIT subsys.RRSAF CLASS(DSNR)
ID(DB2group) ACCESS(READ)
where subsys is your DB2
subsystem ID.
Each user who wants to access DB2 must be a member of group
DB2group.
For further information, refer to the relevant DB2 documentation of IBM.
NATRPC02(This step applies to Natural for DB2 users only.)
Create the Natural RPC user exit
NATRPC02 with a
call to NATPLAN to set the required DB2 plan.
Make sure that you use a NATPLAN of your current
Natural for DB2 version.
Sample NATRPC02:
DEFINE DATA PARAMETER 1 SUBPROGRAM (A8) BY VALUE END-DEFINE FETCH RETURN 'NATPLAN' 'planname'
Start the Natural RPC server front-end.
Refer to Starting a Natural RPC Server Using the RPC Server Front-End in Starting a Natural RPC Server.
Make sure you have added all required load libaries to your
STEPLIB concatenation. You will especially need the following:
Natural load library
EntireX load library
Adabas load library (if you use the Adabas link routine
ADAUSER)
DB2 load library (if you want to access DB2)
The impersonation is successfully activated if you see the following messages:
In the job log:
RPC0010 Authorized environment for impersonation
established
In the RPC trace file:
M *** Server is running under NSC with
impersonation
The client must send logon data together with the RPC request as it is already done for a standard Natural Security (NSC) protected Natural RPC server. In contrast to a standard Natural RPC server, the user ID must also be a valid SAF user ID and the password must be the corresponding SAF password. User ID and password are validated by the Natural RPC server against the external security system on the z/OS system under which the server is executing. After successful authentication of the client’s identity by the external security system, the user ID is validated by NSC according to the defined rules. The password is ignored. Therefore, it is not required to set the NSC password to your SAF password.
When the field Impersonation described in the section
Components of an
RPC Server Profile in the Natural
Security documentation is set to A, no password is used
to authenticate the client against the external security system. This setting
may be appropriate if the client has already been authenticated by the EntireX
Broker.
Depending on the kind of client, the logon data are set differently:
Turn on the logon option in the
Service Directory
Maintenance function or in the profile parameter DFS.
Alternatively, you can use the
USR2007N to
turn it on.
Refer to Using the Logon Option in Operating a Natural RPC Environment.
Set the SAF user ID and the SAF password, using application
programming interface USR1071P.
If your client runs under Natural Security (NSC) and the user ID
and password of NSC are identical to the SAF user ID and the SAF password, then
USR1071P is not required.
Turn on the Natural logon option according to your application environment.
Set the RPC user ID and the RPC password to the SAF user ID and SAF password according to your application environment.
Impersonation takes place at the start of each non-conversational
CALLNAT and at the start of each conversation.
The authentication of the Natural RPC user ID and password is
performed by the external security system. The password on the
FSEC system file is not used.
After successful authentication, the Natural RPC user ID is established for the operating system (user is impersonated).
After successful impersonation:
A Natural security logon is performed for the Natural RPC user ID without password check.
All work files with a DDNAME that does not start with
CM are opened with the Natural RPC user ID.
All Adabas databases are opened with the Natural RPC user ID (applies to Adabas external security only).
If an ETID is specified in the NSC user profile, this
ETID is used in the Adabas open request.
The DB2 connection is opened with the Natural RPC user ID (applies to Natural for DB2 users only).
At the end of each non-conversational CALLNAT and at the
end of each conversation, the Natural RPC user ID is logged off from the
operating system.
After log off:
All work files with a DDNAME that does not start with
CM are closed.
All Adabas databases are closed.
The following topics are covered below:
Impersonation is an
optional feature on the Natural RPC server side and is only available if the
Natural RPC server runs under Natural Security. The impersonation feature is
controlled by the Security Profiles for Natural RPC
Servers. See the field Impersonation
described under the heading Components of an RPC Server
Profile in the section Protecting Natural RPC Servers and
Services in the Natural Security
documentation.
Impersonation under CICS requires the use of the Natural RPC server front-end under CICS and uses the interface provided by CICS.
If impersonation is active for the Natural RPC server, a client request
that uses the Logon Option is
from the perspective of CICS executed under the user ID that the client passes
in the LOGON data (called Natural RPC user ID).
Impersonation under CICS uses the CICS option to start a CICS task under a
given user ID. After a client request has arrived the Natural RPC server
front-end starts a new CICS task using the USERID() option of the
EXEC CICS START TRANSID() command, where USERID is
the Natural RPC user ID. The User authentication (verification of the Natural
RPC user ID and password) is performed by CICS, typically by using the
underlying external security system. After successful authentication, the
user's identity is established for the CICS task. Any subsequent authorization
checks will be performed based on this identity. This means that all accesses
to resources that are controlled by CICS are authorized for this identity. This
applies especially to accesses to CICS resources and to data bases.
Impersonation does not turn off Natural Security. After successful
authentication of the user's identity by CICS, a Natural Security logon takes
place using the same LOGON data without password
verification.
To start a Natural RPC server using impersonation, see Starting a Natural Server Using the RPC Server Front-End (CICS only) in Starting a Natural RPC Server.
Note:
Without impersonation, a client request that uses the Logon option
is from the perspective of the operating system executed with the user ID under
which the Natural RPC server has been started.
Proceed as described in the corresponding steps of the Natural for Mainframes installation documentation; see Installing the Natural CICS Interface on z/OS.
For further information, refer to the relevant Adabas documentation (applies to Adabas external security users only).
CICSETB instead of
NATETB23See Providing Access to the EntireX Broker Stub on Mainframe in Setting Up a Natural RPC Environment.
Refer to Set the RPC Server-Specific Natural Parameters in Setting Up a Natural RPC Environment.
The parameters are either defined in the Natural parameter module or together with the transaction ID.
Define an RPC Server Profile in Natural Security (NSC) for the server
name that is used by the RPC server (SRVNAME) and activate the
impersonation.
Refer toSecurity Profiles for Natural RPC Servers in Protecting Natural RPC Servers and Services of the Natural Security documentation.
XUSER=YESIf the CICS startup parameter XUSER=YES is specified you
must define surrogate users for each client user:
RDEFINE SURROGATE userid1.DFHSTART
UACC(NONE) OWNER(userid1) PERMIT
userid1.DFHSTART CLASS(SURROGATE)
ID(userid2) ACCESS(READ)
where
userid1 is the user ID of
the client,
userid2 is the user ID under
which the Natural RPC server front-end is started.
For further information, refer to the relevant CICS documentation of IBM.
PROGRAM entry for the RPC
server front-end
Refer to the corresponding step in Installing the Natural CICS Interface on z/OS.
Define a CICS TRANSACTION entry for the transaction ID
that invokes the RPC server front-end.
Refer to the corresponding step in Installing the Natural CICS Interface on z/OS.
DB2TRAN and DB2ENTRY
entry
(This step applies to Natural for DB2 users only.)
Define a DB2TRAN and DB2ENTRY entry for the
transaction ID that invokes the RPC server front-end.
Start the Roll Server for the subsystem used by the Natural RPC server.
(This step applies only if the
NCMDIR
macro parameter ROLLSRV is
set to YES.)
Refer to Starting a Natural RPC Server Using the RPC Server Front-End (CICS only) in Starting a Natural RPC Server.
The impersonation is successfully activated if you see the following message in the RPC trace file:
M *** Server is running under NSC with
impersonation
The client must send logon data together with the RPC request as it is already done for a standard Natural Security (NSC) protected Natural RPC server. In contrast to a standard Natural RPC server, the user ID must also be a valid CICS user ID and the password must be the corresponding password of the external security system. User ID and password are validated by CICS against the external security system on the z/OS system under which CICS is executing. After successful authentication of the client’s identity by the external security system, the user ID is validated by Natural Security according to the defined rules. The password is ignored. Therefore, it is not required to set the NSC password to your SAF password.
When the field Impersonation described in the section
Components of an
RPC Server Profile in the Natural
Security documentation is set to A, no password is used
to validate the client against the external security system. This setting may
be appropriate if the client has already been authenticated by the EntireX
Broker.
Depending on the kind of client, the logon data are set differently:
Turn on the logon option in the Service Directory
Maintenance function or in the profile parameter DFS.
Alternatively, you can use the application programming interface
USR2007N to
turn it on.
Refer to Using the Logon Option in Operating a Natural RPC Environment.
Set the user ID and the password, using application programming
interface USR1071P.
If your client runs under Natural Security (NSC) and the user ID and
password of NSC are identical to the user ID and password on the server side,
then USR1071P is not required.
Turn on the Natural logon option according to your application environment.
Set the RPC user ID and the RPC password according to your application environment.
Impersonation takes place at the start of each non-conversational
CALLNAT and at the start of each conversation.
The authentication of the Natural RPC user ID and password are performed by CICS. The password on the FSEC system file is not used.
After successful authentication, the Natural RPC user ID is established for CICS (user is impersonated).
After successful impersonation:
A Natural security logon is performed for the Natural RPC user ID without password check.
All CICS resources are accessed with the Natural RPC user ID.
All Adabas databases are opened with the Natural RPC user ID (applies to Adabas external security only).
If an ETID is specified in the NSC user profile, this
ETID is used in the Adabas open request.
The DB2 connection is opened with the Natural RPC user ID (applies to Natural for DB2 users only).
At the end of each non-conversational CALLNAT and at the
end of each conversation, the Natural RPC user ID is logged off from CICS.
After log off:
All CICS resources are closed.
All Adabas databases are closed.
The connection to DB2 is closed (applies to Natural for DB2 users only).
Natural RPC fully supports EntireX Security on the client side and on the server side.
To logon to and logoff from the EntireX
Broker, the Natural Application Programming Interface
USR2071N
is provided. To logon to EntireX Broker, you use the logon function of
USR2071N and pass your user ID and password to the selected
EntireX Broker. After a successful logon, the security token returned is saved
by Natural and passed to the EntireX Broker on each subsequent call. The Logon
option is fully transparent to the Natural application.
If EntireX Security is installed or if AUTOLOGON=NO is
specified in the EntireX Broker attribute file, you must invoke
USR2071N with the logon function before the very first remote
CALLNAT execution.
You are recommended to invoke USR2071N with the logoff
function as soon as you no longer intend to use a remote
CALLNAT.
To make use of USR2071N
Copy the subprogram USR2071N from libray
SYSEXT to the library SYSTEM or to the steplib
library or to any application in the server environment.
Using a DEFINE
DATA statement, specify the following parameters:
| Parameter | I/O | Format | Description | |
|---|---|---|---|---|
function |
I | A08 |
Function code; possible values are: |
|
LOGON |
Logon to EntireX Broker | |||
LOGOFF
|
Logoff from EntireX Broker | |||
broker-id |
I | A192 |
Broker ID. The broker-id may have up to 32 characters for physical node names and up to 192 characters for logical node names or logical service names. See Operating a Natural RPC Environment, Using EntireX Location Transparency. Note: The sample |
|
user-id |
I | A32 | User ID. | |
password |
I | A32 | User ID's password. | |
newpassw
|
I | A32 | User ID's new password. | |
rc
|
O | N04 |
Return value: |
|
0 |
OK | |||
1 |
invalid function code | |||
9999 |
EntireX Broker error (see message) | |||
message |
O | A80 | Message text returned by EntireX Broker. | |
In the calling program on the client side, specify the following statement:
CALLNAT 'USR2071N' function broker-id user-id password newpassword rc message
See also the Syntax
Description of the CALLNAT statement.
You may alternatively invoke USR2071P from the command
line and enter user ID and password in the displayed window. In this case, all
input except for the passwords is converted into upper case. For the passwords,
you have the option to enter them in mixed case or not.
LOGON |
An EntireX Broker With Notes:
|
LOGOFF |
An EntireX Broker LOGOFF function is executed to
the broker-id named.
|
If you want to LOGON using a logical node name, you have
to use the LOGBROKER keyword.
BROKER-ID := 'LOGBROKER=my_logical_node,my_set'
If you want to LOGON using a logical service name, you
have to use the LOGSERVICE keyword.
BROKER-ID := 'LOGSERVICE=my_logical_service,my_set'
If an RPC client request is executed on the Natural RPC server side, a
logon to the EntireX Broker, using the Application Programming Interface
USR2071N, must
also be performed before executing the RPC client request. The logon data of
the Natural RPC server itself are not used for RPC client requests.
If the RPC client request is sent to the same EntireX Broker where the
Natural RPC server is registered, the user ID must be different from the value
of the Natural profile parameter
SRVUSER.
If the value of profile parameter
ACIVERS
is 2 or higher, the server will log on to the EntireX Broker at
the session start using the LOGON function. The user ID is the
same as the user ID defined by SRVUSER.
If EntireX Security has been installed and if the EntireX trusted user ID feature is not available, there are two alternative ways to specify the required password:
Setting SRVUSER=*NSC
Using application programming interface USR2072N
These alternatives are described below.
If Natural Security is installed on the server, you can set
profile parameter SRVUSER
to *NSC to specify that the current Natural
Security user ID which was used when the server was started is used for the
LOGON in conjunction with the accompanying Natural Security
password. In this case, the value set for ACIVERS must
be at least 4.
The Application Programming Interface
USR2072N enables you to specify a password which is used for the
LOGON in conjunction with profile parameter
SRVUSER.
To make use of USR2072N
Copy the subprogram USR2072N and optionally program
USR2072P from libray SYSEXT to the library
SYSTEM or to the steplib library or to any application in the
server environment.
Using a DEFINE
DATA statement, specify the following parameter:
| Parameter | I/O | Format | Description |
|---|---|---|---|
password |
I | A32 | User ID's password. |
In the calling program on the client side, specify the following statement:
CALLNAT 'USR2072' password
See also the Syntax
Description of the CALLNAT statement.
The calling program must be executed before the Natural RPC server
has started its initialization. To accomplish this, put the name of the calling
program on the Natural stack when starting the server. For this purpose, you
may also use the program USR2072P from library
SYSEXT. In this case, the password is converted into upper case by
default. You have the option to enter the password in mixed case by passing the
mixed case option Y as second parameter.
STACK=(LOGON server-library;USR2072P password [Y])