Configuring Zowe Application Framework
Configuring Zowe Application Framework
After you install Zowe™, you can optionally configure the Zowe Application Framework as a Mediation Layer client, configure connections for the terminal application plug-ins, or modify the Zowe Application Server and Zowe System Services (ZSS) configuration, as needed.
#
Configuring the framework as a Mediation Layer clientFor simpler Zowe administration and better security, you can install an instance of the Zowe Application Framework as an API Mediation Layer client.
This configuration is simpler to administer because the framework servers are accessible externally through a single port. It is more secure because you can implement stricter browser security policies for accessing cross-origin content.
You must use SSL certificates to configure the Zowe Application Server to communicate with the SSL-enabled Mediation Layer. Those certificates were created during the Zowe installation process, and are located in the $ROOT_DIR/components/app-server/share/zlux-app-server/defaults/serverConfig
directory.
#
Enabling the Application Server to register with the Mediation LayerWhen you install Zowe v1.8.0 or later, the Application Server automatically registers with the Mediation Layer.
For earlier releases, you must register the Application Server with the Mediation Layer manually. Refer to previous release documentation for more information.
#
Accessing the Application ServerTo access the Application Server through the Mediation Layer, use the Mediation Layer gateway server hostname and port. For example, when accessed directly, this is Zowe Desktop URL: https://<appservername_port>/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html
The port number for the Zowe Desktop is the value of the ZOWE_ZLUX_SERVER_HTTPS_PORT
variable in the instance.env
file in the instance directory, see Creating and configuring the Zowe instance directory.
When accessed through the API Mediation Layer, this is the Zowe Desktop URL:
https://<gwsname_port>/ui/v1/zlux/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html
The port number for the API Mediation Layer is the value of the GATEWAY_PORT
variable in the instance.env
file in the instance directory.
#
Setting up terminal application plug-insFollow these optional steps to configure the default connection to open for the terminal application plug-ins.
#
Setting up the TN3270 mainframe terminal application plug-in_defaultTN3270.json
is a file in tn3270-ng2/
, which is deployed during setup. Within this file, you can specify the following parameters to configure the terminal connection:
"host": <hostname> "port": <port> "security": { type: <"telnet" or "tls"> }
#
Setting up the VT Terminal application plug-in_defaultVT.json
is a file in vt-ng2/
, which is deployed during setup. Within this file, you can specify the following parameters to configure the terminal connection:
"host":<hostname> "port":<port> "security": { type: <"telnet" or "ssh"> }
#
Configuration fileThe Zowe App Server and ZSS rely on many required or optional parameters to run, which includes setting up networking, deployment directories, plugin locations, and more.
For convenience, the Zowe Application Server and ZSS read from a JSON file with a common structure. ZSS reads this file directly as a startup argument, while the Zowe Application Server (as defined in the zlux-server-framework
repository) accepts several parameters. The parameters are intended to be read from a JSON file through an implementer of the server, such as the example in the zlux-app-server
repository (the lib/zluxServer.js
file). The file accepts a JSON file that specifies most, if not all, of the parameters needed. Other parameters can be provided through flags, if needed.
For an instance, the configuration file is located at and can be edited at $INSTANCE_DIR/workspace/app-server/serverConfig/server.json
. The defaults from which that file is generated are located at $ROOT_DIR/components/app-server/share/zlux-app-server/defaults/serverConfig/server.json
Note: All examples are based on the zlux-app-server repository defaults.
#
Network configurationNote: The following attributes are to be defined in the server's JSON configuration file.
The App Server can be accessed over HTTP and/or HTTPS, provided it has been configured for either.
#
HTTPTo configure the server for HTTP, complete these steps:
Define an attribute http within the top-level node attribute.
Define port within http. Where port is an integer parameter for the TCP port on which the server will listen. Specify 80 or a value between 1024-65535.
#
HTTPSFor HTTPS, specify the following parameters:
Define an attribute https within the top-level node attribute.
Define the following within https:
- port: An integer parameter for the TCP port on which the server will listen. Specify 443 or a value between 1024-65535.
- certificates: An array of strings, which are paths to PEM format HTTPS certificate files.
- keys: An array of strings, which are paths to PEM format HTTPS key files.
- pfx: A string, which is a path to a PFX file which must contain certificates, keys, and optionally Certificate Authorities.
- certificateAuthorities (Optional): An array of strings, which are paths to certificate authorities files.
- certificateRevocationLists (Optional): An array of strings, which are paths to certificate revocation list (CRL) files.
Note: When using HTTPS, you must specify pfx, or both certificates and keys.
#
Network exampleIn the example configuration, both HTTP and HTTPS are specified:
"node": { "https": { "ipAddresses": ["0.0.0.0"], "port": 8544, //pfx (string), keys, certificates, certificateAuthorities, and certificateRevocationLists are all valid here. "keys": ["../defaults/serverConfig/server.key"], "certificates": ["../defaults/serverConfig/server.cert"] }, "http": { "ipAddresses": ["0.0.0.0"], "port": 8543 } }
#
Configuration DirectoriesWhen running, the App Server will access the server's settings and read or modify the contents of its resource storage. All of this data is stored within a heirarchy of folders which correspond to scopes:
- Product: The contents of this folder are not meant to be modified, but used as defaults for a product.
- Site: The contents of this folder are intended to be shared across multiple App Server instances, perhaps on a network drive.
- Instance: This folder represents the broadest scope of data within the given App Server instance.
- Group: Multiple users can be associated into one group, so that settings are shared among them.
- User: When authenticated, users have their own settings and storage for the Apps that they use.
These directories dictate where the Configuration Dataservice will store content.
#
Directories example// All paths relative to zlux-app-server/lib// In real installations, these values will be configured during the install. "productDir":"../defaults", "siteDir":"/home/myuser/.zowe/workspace/app-server/site", "instanceDir":"/home/myuser/.zowe/workspace/app-server", "groupsDir":"/home/myuser/.zowe/workspace/app-server/groups", "usersDir":"/home/myuser/.zowe/workspace/app-server/users",
#
Old defaultsPrior to Zowe release 1.8.0, the location of the configuration directories were initialized to be within the zlux-app-server
folder unless otherwise customized. 1.8.0 has backwards compatibility for the existence of these directories, but they can and should be migrated to take advantage of future enhancements.
Folder | New Location | Old Location | Note |
---|---|---|---|
productDir | zlux-app-server/defaults | zlux-app-server/deploy/product | Official installs place zlux-app-server within <ROOT_DIR>/components/app-server/share |
siteDir | <INSTANCE_DIR>/workspace/app-server/site | zlux-app-server/deploy/site | INSTANCE_DIR is ~/.zowe if not otherwise defined. Site is placed within instance due to lack of SITE_DIR as of 1.8 |
instanceDir | <INSTANCE_DIR>/workspace/app-server | zlux-app-server/deploy/instance | |
groupsDir | <INSTANCE_DIR>/workspace/app-server/groups | zlux-app-server/deploy/instance/groups | |
usersDir | <INSTANCE_DIR>/workspace/app-server/users | zlux-app-server/deploy/instance/users | |
pluginsDir | <INSTANCE_DIR>/workspace/app-server/plugins | zlux-app-server/deploy/instance/ZLUX/plugins | Defaults located at zlux-app-server/defaults/plugins, previously at zlux-app-server/plugins |
#
Application plug-in configurationThis topic describes application plug-ins that are defined in advance.
In the configuration file, you can specify a directory that contains JSON files, which tell the server what application plug-in to include and where to find it on disk. The backend of these application plug-ins use the server's plug-in structure, so much of the server-side references to application plug-ins use the term plug-in.
To include application plug-ins, define the location of the plug-ins directory in the configuration file, through the top-level attribute pluginsDir.
Note: In this example, the directory for these JSON files is the Application Server defaults. However, in an instance of Zowe it is best to provide a folder unique to that instance - usually $INSTANCE_DIR/workspace/app-server/plugins
.
#
Plug-ins directory example// All paths relative to zlux-app-server/lib// In real installations, these values will be configured during the install process.//... "pluginsDir":"../defaults/plugins",
#
Logging configurationFor more information, see Logging Utility.
#
ZSS configurationRunning ZSS requires a JSON configuration file that is similar or the same as the one used for the Zowe Application Server. The attributes that are needed for ZSS, at minimum, are:productDir, siteDir, instanceDir, groupsDir, usersDir, pluginsDir and agent.http.port. All of these attributes have the same meaning as described above for the server, but if the Zowe Application Server and ZSS are not run from the same location, then these directories can be different.
Attributes that control ZSS are in the agent object. For example, agent.http.port is the TCP port that ZSS will listen on to be contacted by the App Server. Define this in the configuration file as a value between 1024-65535. Similarly, if specified, agent.http.ipAddresses will be used to determine which IP addresses the server should bind to. Only the first value of the array is used. It can either be a hostname or an ipv4 address.
Example of the agent body:
"agent": { "host": "localhost", "http": { "ipAddresses": ["127.0.0.1"], "port": 8542 } }
#
Connecting App Server to ZSSWhen running the App Server, simply specify a few flags to declare which ZSS instance the App Server will proxy ZSS requests to:
- -h: Declares the host where ZSS can be found. Use as "-h \<hostname>"
- -P: Declares the port at which ZSS is listening. Use as "-P \<port>"
#
Configuring ZSS for HTTPSTo secure ZSS communication, you can use Application Transparent Transport Layer Security (AT-TLS) to enable Hyper Text Transfer Protocol Secure (HTTPS) communication with ZSS.
Before you begin, you must have a basic knowledge of your security product, e.g. RACF, and AT-TLS, and you must have Policy Agent configured. For more information on AT-TLS and Policy Agent, see the z/OS Knowledge Center.
You must have the authority to alter security definitions related to certificate management, and you must be authorized to work with and update the Policy Agent.
To configure HTTPS communication between ZSS and the Zowe App Server, you need a key ring which contains the ZSS server certificate and its Certificate Authority (CA) certificate. You can use an internal CA to create the ZSS server certificate, or you can buy the ZSS server certificate from a well-known commercial Certificate Authority. Next you define an AT-TLS rule which points to the key ring used by the ZSS server. Then you copy the CA certificate to the Zowe App Server key store and update the Zowe App Server configuration file.
Note: Bracketed values below (including the brackets) are variables. Replace them with values relevant to your organization. Always use the same value when substituting a variable that occurs multiple times.
#
Creating certificates and key ring for the ZSS server using RACFIn this step you will create a root CA certificate and a ZSS server certificate signed by the CA certificate. Next you create a key ring owned by the ZSS server with the certificates attached.
Key variables:
Variable | Value |
---|---|
[ca_common_name] | |
[ca_label] | |
[server_userid] | |
[server_common_name] | |
[server_label] | |
[ring_name] | |
[output_dataset_name] |
Note:
[server_userid]
must be the ZSS server user ID.[server_common_name]
must be the ZSS server host name.
Enter the following RACF command to generate a CA certificate:
RACDCERT CERTAUTH GENCERT + SUBJECTSDN(CN('[ca_common_name]') + OU('[organizational_unit]') + O('[organization_name]') + L('[locality]') SP('[state_or_province]') C('[country]')) + KEYUSAGE(CERTSIGN) + WITHLABEL('[ca_label]') + NOTAFTER(DATE([yyyy/mm/dd])) + SIZE(2048)
Enter the follow RACF command to generate a server certificate signed by the CA certificate:
RACDCERT ID('[server_userid]') GENCERT + SUBJECTSDN(CN('[common_name]') + OU('[organizational_unit]') + O('[organization_name]') + L('[locality]') SP('[state_or_province]') C('[country]')) + KEYUSAGE(HANDSHAKE) + WITHLABEL('[server_label]') + NOTAFTER(DATE([yyyy/mm/dd])) + SIZE(2048) + SIGNWITH(CERTAUTH LABEL('[ca_label]'))
Enter the following RACF commands to create a key ring and connect the certificates to the key ring:
RACDCERT ID([server_userid]) ADDRING([ring_name])RACDCERT ID([server_userid]) CONNECT(ID([server_userid]) + LABEL('[server_label]') RING([ring_name]) DEFAULT)RACDCERT ID([server_userid]) CONNECT(CERTAUTH + LABEL('[ca_label]') RING([ring_name]))
Enter the following RACF command to refresh the DIGTRING and DIGTCERT classes to activate your changes:
SETROPTS RACLIST(DIGTRING,DIGTCERT) REFRESH
Enter the following RACF commands to verify your changes:
RACDCERT ID([server_userid]) LISTRING([ring_name])RACDCERT ID([server_userid]) LISTCHAIN(LABEL(‘[server_label])’)
Enter the following RACF commands to allow the ZSS server to use the certificates. Only issue the RDEFINE commands if the profiles do not yet exist.
RDEFINE FACILITY IRR.DIGTCERT.LIST UACC(NONE)RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ACCESS(READ) + ID([server_userid])PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ACCESS(READ) + ID([server_userid])SETROPTS RACLIST(FACILITY) REFRESH
Note: These sample commands use the FACILTY class to manage certificate related authorizations. You can also use the RDATALIB class, which offers granular control over the authorizations.
- Enter the following RACF command to export the CA certificate to a dataset so it can be imported by the Zowe App Server:
RACDCERT CERTAUTH EXPORT(LABEL('[ca_label]')) + DSN('[output_dataset_name]') FORMAT(CERTB64)
#
Defining the AT-TLS ruleTo define the AT-TLS rule, use the sample below to specify values in your AT-TLS Policy Agent Configuration file:
TTLSRule ATTLS1~ZSS{ LocalAddr All RemoteAddr All LocalPortRange [zss_port] Jobname * Userid * Direction Inbound Priority 255 TTLSGroupActionRef gAct1~ZSS TTLSEnvironmentActionRef eAct1~ZSS TTLSConnectionActionRef cAct1~ZSS}TTLSGroupAction gAct1~ZSS{ TTLSEnabled On Trace 1}TTLSEnvironmentAction eAct1~ZSS{ HandshakeRole Server EnvironmentUserInstance 0 TTLSKeyringParmsRef key~ZSS Trace 1}TTLSConnectionAction cAct1~ZSS{ HandshakeRole Server TTLSCipherParmsRef cipherZSS TTLSConnectionAdvancedParmsRef cAdv1~ZSS Trace 1}TTLSConnectionAdvancedParms cAdv1~ZSS{ SSLv3 Off TLSv1 Off TLSv1.1 Off TLSv1.2 On CertificateLabel [personal_label]}TTLSKeyringParms key~ZSS{ Keyring [ring_name]}TTLSCipherParms cipher~ZSS{ V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 V3CipherSuites TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 V3CipherSuites TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 V3CipherSuites TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 V3CipherSuites TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384}
#
Configuring the Zowe App Server for HTTPS communication with ZSSCopy the CA certificate to the ZSS server. Then in the Zowe App Server configuration file, specify the location of the certificate, and add a parameter to specify that ZSS uses AT-TLS.
- Enter the following command to copy the CA certificate to the correct location in UNIX System Services (USS):
cp "//'[output_dataset_name]'" 'zlux-app-server/deploy/instance/ZLUX/serverConfig/[ca_cert]'
- In the
[INSTANCE_DIR]/workspace/app-server/serverConfig
directory, open theserver.json
file. - In the node.https.certificateAuthorities object, add the CA certificate file path, for example:
"certificateAuthorities": ["[INSTANCE_DIR]/workspace/app-server/serverConfig/[ca_cert]"]
- In the agent.http object add the key-value pair
"attls": true
, for example:
"agent": { "host": "localhost", "http": { "ipAddresses": ["127.0.0.1"], "port": 8542, "attls": true }}
#
Installing additional ZSS instancesAfter you install Zowe, you can install and configure additional instances of ZSS on the same z/OS server. You might want to do this to test different ZSS versions.
The following steps assume you have installed a Zowe runtime instance (which includes ZSS), and that you are installing a second runtime instance to install an additional ZSS.
To stop the installed Zowe runtime, in SDSF enter the following command:
/C ${ZOWE_PREFIX}${ZOWE_INSTANCE}SV
Where ZOWE_PREFIX and ZOWE_INSTANCE are specified in your configuration (and default to ZWE and 1)
Install a new Zowe runtime by following steps in Installing Zowe on z/OS.
Note: In the
zowe-install.yaml
configuration file, specify ports that are not used by the first Zowe runtime.To restart the first Zowe runtime, in SDSF enter the following command:
/S ZWESVSTC,SRVRPATH='$ZOWE_ROOT_DIR'
Where
'$ZOWE_ROOT_DIR'
is the first Zowe runtime root directory. By default the command starts the most recently installed runtime unless you specify the root directory of the runtime that you want to start.To specify a name for the new ZSS instance, follow these steps:
Copy the PROCLIB member JCL named ZWESISTC that was installed with the new runtime.
Rename the copy to uniquely identify it as the JCL that starts the new ZSS, for example ZWESIS02.
Edit the JCL, and in the
NAME
parameter specify a unique name for the cross-memory server, for example://ZWESIS02 PROC NAME='ZWESIS_MYSRV',MEM=00,RGN=0M
Where
ZWESIS_MYSRV
is the unique name of the new ZSS.
To start the new ZSS, in SDSF enter the following command:
/S ZWESIS02
Make sure that the TSO user ID that runs the first ZSS started task also runs the new ZSS started task. The default ID is ZWESVUSR.
In the new ZSS
server.json
configuration file, add a"privilegedServerName"
parameter and specify the new ZSS name, for example:"productDir":"../defaults",// All paths relative to zlux-app-server/bin// In real installations, these values will be configured during the install."productDir":"../defaults","siteDir":"../deploy/site","instanceDir":"../deploy/instance","groupsDir":"../deploy/instance/groups","usersDir":"../deploy/instance/users","pluginsDir":"../defaults/plugins","privilegedServerName":"ZWESIS_MYSRV","dataserviceAuthentication": { ... }
Note: The instance location of
server.json
is$INSTANCE_DIR/workspace/app-server/serverConfig/server.json
, and the defaults are stored in$ROOT_DIR/components/app-server/share/zlux-app-server/defaults/serverConfig/server.json
To start the new Zowe runtime, in SDSF enter the following command:
/S ZWESVSTC,INSTANCE='$ZOWE_INSTANCE_DIR'
To verify that the new cross-memory server is being used, check for the following messages in the
ZWESVSTC
server job log:ZIS status - Ok (name='ZWESIS_MYSRV ', cmsRC=0, description='Ok', clientVersion=2)
#
Controlling access to applicationsYou can control which applications are accessible (visible) to all Zowe desktop users, and which are accessible only to individual users. For example, you can make an application that is under development only visible to the team working on it.
You control access by editing JSON files that list the apps. One file lists the apps all users can see, and you can create a file for each user. When a user logs into the desktop, Zowe determines the apps that user can see by concatenating their list with the all users list.
You can also control access to the JSON files. The files are accessible directly on the file system, and since they are within the configuration dataservice directories, they are also accessible via REST API. We recommend that only Zowe administrators be allowed to access the file system locations, and you control that by setting the directories and their contents to have file permissions on z/OS that only allow the Zowe admin group read & write access. You control who can read and edit the JSON files through the REST API by controlling who can access the configuration dataservice objects URLs that serve the JSON files.
#
Controlling application access for all usersOpen the Zowe Application Server configuration JSON file. By default, the file is in the following location:
$ROOT_DIR/components/app-server/share/zlux-app-server/defaults/serverConfig/server.json
To enable RBAC, in the
dataserviceAuthentication
object add the object:"rbac": true
Navigate to the following location:
$ROOT_DIR/components/app-server/share/zlux-app-server/defaults/ZLUX/pluginStorage/org.zowe.zlux.bootstrap/plugins
Copy the
allowedPlugins.json
file and paste it in the following location:.zowe/workspace/app-server/ZLUX/pluginStorage/org.zowe.zlux.bootstrap
Open the copied
allowedPlugins.json
file and perform either of the following steps:- To an application unavailable, delete it from the list of objects.
- To make an application available, copy an existing plugin object and specify the application's values in the new object. Identifier and version attributes are required.
#
Controlling application access for individual usersOpen the Zowe Application Server configuration JSON file. By default, the file is in the following location:
$ROOT_DIR/components/app-server/share/zlux-app-server/defaults/serverConfig/server.json
To enable RBAC, in the
dataserviceAuthentication
object add the object:"rbac": true
In the user's ID directory path, in the
\pluginStorage
directory, create\org.zowe.zlux.bootstrap\plugins
directories. For example:.zowe\workspace\app-server\users\TS6320\ZLUX\pluginStorage\org.zowe.zlux.bootstrap\plugins
In the
/plugins
directory, create anallowedPlugins.json
file. You can use the defaultallowedPlugins.json
file as a template by copying it from the following location:$ROOT_DIR/components/app-server/share/zlux-app-server/defaults/ZLUX/pluginStorage/org.zowe.zlux.bootstrap/plugins
Open the
allowedPlugins.json
file and specify applications that user can access. For example:{ "allowedPlugins": [ { "identifier": "org.zowe.appA", "versions": [ "*" ] }, { "identifier": "org.zowe.appB", "versions": [ "*" ] },}
Notes:
- Identifier and version attributes are required.
- When a user logs in to the desktop, Zowe determines which apps they can see by concatenating the list of apps available to all users with the apps available to the individual user.
#
Controlling access to dataservicesTo apply role-based access control (RBAC) to dataservice endpoints, you must enable RBAC for Zowe, and then use a z/OS security product such as RACF to map roles and authorities to the endpoints. After you apply RBAC, Zowe checks authorities before allowing access to the endpoints.
You can apply access control to Zowe endpoints and to your application endpoints. Zowe provides endpoints for a set of configuration dataservices and a set of core dataservices. Applications can use configuration endpoints to store and their own configuration and other data. Administrators can use core endpoints to get status information from the Application Framework and ZSS servers. Any dataservice added as part of an application plugin is a service dataservice.
#
Defining the RACF ZOWE classIf you use RACF security, take the following steps define the ZOWE class to the CDT class:
- Make sure that the CDT class is active and RACLISTed.
- In TSO, issue the following command:If you receive the following message, ignore it:
RDEFINE CDT ZOWE UACC(NONE)CDTINFO( DEFAULTUACC(NONE) FIRST(ALPHA) OTHER(ALPHA,NATIONAL,NUMERIC,SPECIAL) MAXLENGTH(246) POSIT(607) RACLIST(DISALLOWED))
"Warning: The POSIT value is not within the recommended ranges for installation use. The valid ranges are 19-56 and 128-527."
- In TSO, issue the following command to refresh the CDT class:
SETROPTS RACLIST(CDT) REFRESH
- In TSO, issue the following command to activate the ZOWE class:
SETROPTS CLASSACT(ZOWE)
For more information RACF security administration, see the IBM Knowledge Center at https://www.ibm.com/support/knowledgecenter/.
#
Enabling RBACBy default, RBAC is disabled and all authenticated Zowe users can access all dataservices. To enable RBAC, follow these steps:
Open the Zowe Application Server configuration JSON file. In the a server instance, the configuration file is
$INSTANCE_DIR/workspace/app-server/serverConfig/server.json
.In the
dataserviceAuthentication
object, add"rbac": true
.
#
Creating authorization profilesFor users to access endpoints after you enable RBAC, in the ZOWE class you must create System Authorization Facility (SAF) profiles for each endpoint and give users READ access to those profiles.
Endpoints are identified by URIs in the following format:
/<product>/plugins/<plugin_id>/services/<service>/<version>/<path>
For example:
/ZLUX/plugins/org.zowe.foo/services/baz/_current/users/fred
Where the path is /users/fred
.
SAF profiles have the following format:
<product>.<instance_id>.<service>.<pluginid_with_underscores>.<service>.<HTTP_method>.<url_with_forward_slashes_replaced_by_periods>
For example, to issue a POST request to the dataservice endpoint documented above, users must have READ access to the following profile:
ZLUX.DEFAULT.SVC.ORG_ZOWE_FOO.BAZ.POST.USERS.FRED
For configuration dataservice endpoint profiles use the service code CFG
. For core dataservice endpoints use COR
. For all other dataservice endpoints use SVC
.
#
Creating generic authorization profilesSome endpoints can generate an unlimited number of URIs. For example, an endpoint that performs a DELETE action on any file would generate a different URI for each file, and users can create an unlimited number of files. To apply RBAC to this type of endpoint you must create a generic profile, for example:
ZLUX.DEFAULT.COR.ORG_ZOWE_FOO.BAZ.DELETE.**
You can create generic profile names using wildcards, such as asterisks (*). For information on generic profile naming, see IBM documentation.
#
Configuring basic authorizationThe following are recommended for basic authorization:
- To give administrators access to everything in Zowe, create the following profile and give them UPDATE access to it:
ZLUX.**
- To give non-administrators basic access to the site and product, create the following profile and give them READ access to it:
ZLUX.*.ORG_ZOWE_*
- To prevent non-administrators from configuring endpoints at the product and instance levels, create the following profile and do not give them access to it:
ZLUX.DEFAULT.CFG.**
- To give non-administrators all access to user, create the following profile and give them UPDATE access to it:
ZLUX.DEFAULT.CFG.*.*.USER.**
#
Endpoint URL length limitationsSAF profiles cannot contain more than 246 characters. If the path section of an endpoint URL is long enough that the profile name exceeds the limit, the path is trimmed to only include elements that do not exceed the limit. To avoid this issue, we recommend that appliction developers maintain relatively short endpoint URL paths.
For information on endpoint URLs, see Dataservice endpoint URL lengths and RBAC
#
Multi-factor authentication configurationMulti-factor authentication is an optional feature for Zowe.
As of Zowe version 1.8.0, the Zowe App Framework, Desktop, and all apps present in the SMP/E or convenience builds support out-of-band MFA by entering an MFA assigned token or passcode into password field of the Desktop login screen, or by accessing the app-server /auth
REST API endpoint.
For a list of compatible MFA products, see Known compatible MFA products
#
Session duration and expirationAfter successful authentication, a Zowe Desktop session is created by authentication plugins.
The duration of the session is determined by the plugin used. Some plugins are capable of renewing the session prior to expiration, while others may have a fixed session length.
Zowe is bundled with a few of these plugins:
apiml-auth: Calls the Zowe API Mediation Layer from the app-server for authentication. By default, the Mediation Layer calls z/OSMF to answer the authentication request. The session created mirrors the z/OSMF session.
zosmf-auth: Calls z/OSMF auth from the app-server to answer the authentication request. The created z/OSMF session is valid for about 8 hours.
zss-auth: Calls Zowe ZSS from the app-server to answer the authentication request. The created ZSS session is valid for 1 hour, but is renewable on request prior to expiration. In the Desktop, the session is automatically renewed if the user is detected as active. If the user is detected as idle, the session will expire.
When a session expires, the credentials used for the initial login are likely to be invalid for re-use, since MFA credentials are often one-time-use or time-based.
In the Desktop, Apps that you opened prior to expiration will remain open so that your work can resume after entering new credentials.
#
ConfigurationWhen you use the default Zowe SMP/E or convenience build configuration, you do not need to change Zowe to get started with MFA.
To configure Zowe for MFA with a configuration other than the default, take the following steps:
Choose an App Server security plugin that is compatible with MFA. The apiml-auth, zss-auth, and zosmf-auth plugins are all compatible.
Locate the App Server's configuration file in
$INSTANCE_DIR/workspace/app-server/serverConfig/server.json
Edit the configuration file to modify the section
dataserviceAuthentication
.Set
defaultAuthentication
to the same category as the plugin of choice, for example:- apiml-auth: "apiml"
- zosmf-auth: "zosmf"
- zss-auth: "zss"
Define the plugins to use in the configuration file by adding a section for the chosen category within
dataserviceAuthentication.implementationDefaults
as an object with the attributeplugins
, which is an array of plugin ID strings, where the plugins each have the following IDs:- apiml-auth: "org.zowe.zlux.auth.apiml"
- zosmf-auth: "org.zowe.zlux.auth.zosmf"
- zss-auth: "org.zowe.zlux.auth.zss"
The following is an example configuration for zss-auth
, as seen in a default installation of Zowe:
"dataserviceAuthentication": { "defaultAuthentication": "zss", "implementationDefaults": { "zss": { "plugins": [ "org.zowe.zlux.auth.zss" ] } }}
#
Enabling tracingTo obtain more information about how a server is working, you can enable tracing within the server.json
file.
For example:
"logLevels": { "_zsf.routing": 0, "_zsf.install": 0, "_zss.traceLevel": 0, "_zss.fileTrace": 1}
Specify the following settings inside the logLevels object.
All settings are optional.
#
Zowe Application Server tracingTo determine how the Zowe Application Server (zlux-app-server
) is working, you can assign a logging level to one or more of the pre-defined logger names in the server.json
file.
The log prefix for the Zowe Application Server is _zsf, which is used by the server framework. (Applications and plug-ins that are attached to the server do not use the _zsf prefix.)
The following are the logger names that you can specify:
_zsf.bootstrap Logging that pertains to the startup of the server.
_zsf.auth Logging for network calls that must be checked for authentication and authorization purposes.
_zsf.static
Logging of the serving of static files (such as images) from an application's /web
folder.
_zsf.child Logging of child processes, if any.
_zsf.utils Logging for miscellaneous utilities that the server relies upon.
_zsf.proxy Logging for proxies that are set up in the server.
_zsf.install Logging for the installation of plug-ins.
_zsf.apiml Logging for communication with the api mediation layer.
_zsf.routing Logging for dispatching network requests to plug-in dataservices.
_zsf.network Logging for the HTTPS server status (connection, ports, IP, and so on)
#
Log levelsThe log levels are:
- SEVERE = 0,
- WARNING = 1,
- INFO = 2,
- FINE = 3,
- FINER = 4,
- FINEST = 5
FINE, FINER, and FINEST are log levels for debugging, with increasing verbosity.
#
Enabling tracing for ZSSTo increase logging for ZSS, you can assign a logging level (an integer value greater than zero) to one or more of the pre-defined logger names in the server.json
file.
A higher value specifies greater verbosity.
The log prefix for ZSS is _zss. The following are the logger names that you can specify:
_zss.traceLevel: Controls general server logging verbosity.
_zss.fileTrace: Logs file serving behavior (if file serving is enabled).
_zss.socketTrace: Logs general TCP Socket behavior.
_zss.httpParseTrace: Logs parsing of HTTP messages.
_zss.httpDispatchTrace: Logs dispatching of HTTP messages to dataservices.
_zss.httpHeadersTrace: Logs parsing and setting of HTTP headers.
_zss.httpSocketTrace: Logs TCP socket behavior for HTTP.
_zss.httpCloseConversationTrace: Logs HTTP behavior for when an HTTP conversation ends.
_zss.httpAuthTrace: Logs behavior for session security.
When you are finished specifying the settings, save the server.json
file.
#
Zowe Application Framework loggingThe Zowe Application Framework log files contain processing messages and statistics. The log files are generated in the following default locations:
- Zowe Application Server:
$INSTANCE_DIR/logs/appServer-yyyy-mm-dd-hh-mm.log
- ZSS:
$INSTANCE_DIR/logs/zssServer-yyyy-mm-dd-hh-mm.log
The logs are timestamped in the format yyyy-mm-dd-hh-mm and older logs are deleted when a new log is created at server startup.
#
Controlling the logging locationThe log information is written to a file and to the screen. (On Windows, logs are written to a file only.)
#
ZLUX_NODE_LOG_DIR and ZSS_LOG_DIR environment variablesTo control where the information is logged, use the environment variable ZLUX_NODE_LOG_DIR, for the Zowe Application Server, and ZSS_LOG_DIR, for ZSS. While these variables are intended to specify a directory, if you specify a location that is a file name, Zowe will write the logs to the specified file instead (for example: /dev/null
to disable logging).
When you specify the environment variables ZLUX_NODE_LOG_DIR and ZSS_LOG_DIR and you specify directories rather than files, Zowe will timestamp the logs and delete the older logs that exceed the ZLUX_NODE_LOGS_TO_KEEP threshold.
#
ZLUX_NODE_LOG_FILE and ZSS_LOG_FILE environment variablesIf you set the log file name for the Zowe Application Server by setting the ZLUX_NODE_LOG_FILE environment variable, or if you set the log file for ZSS by setting the ZSS_LOG_FILE environment variable, there will only be one log file, and it will be overwritten each time the server is launched.
Note: When you set the ZLUX_NODE_LOG_FILE or ZSS_LOG_FILE environment variables, Zowe will not override the log names, set a timestamp, or delete the logs.
If the directory or file cannot be created, the server will run (but it might not perform logging properly).
#
Retaining logsBy default, the last five logs are retained. To specify a different number of logs to retain, set ZLUX_NODE_LOGS_TO_KEEP (Zowe Application Server logs) or ZSS_LOGS_TO_KEEP (ZSS logs) to the number of logs that you want to keep. For example, if you set ZLUX_NODE_LOGS_TO_KEEP to 10, when the eleventh log is created, the first log is deleted.
#
Administering the servers and plugins using an APIYou can use a REST API to retrieve and edit Zowe Application Server and ZSS server configuration values, and list, add, update, and delete plugins. If an administrator has configured Zowe to use RBAC, they must authorize you to access the endpoints.
The API returns the following information in a JSON response:
API | Description |
---|---|
/server (GET) | Returns a list of accessible server endpoints for the Zowe Application Server. |
/server/config (GET) | Returns the Zowe Application Server configuration from the zluxserver.json file. |
/server/log (GET) | Returns the contents of the Zowe Application Server log file. |
/server/loglevels (GET) | Returns the verbosity levels set in the Zowe Application Server logger. |
/server/environment (GET) | Returns Zowe Application Server environment information, such as the operating system version, node server version, and process ID. |
/server/reload (GET) | Reloads the Zowe Application Server. Only available in cluster mode. |
/server/agent (GET) | Returns a list of accessible server endpoints for the ZSS server. |
/server/agent/config (GET) | Returns the ZSS server configuration from the zluxserver.json file. |
/server/agent/log (GET) | Returns the contents of the ZSS log file. |
/server/agent/loglevels (GET) | Returns the verbosity levels of the ZSS logger. |
/server/agent/environment (GET) | Returns ZSS environment information. |
/server/config/:attrib (POST) | Specify values for server configuration attributes in the zluxserver.json file. You can change a subset of configuration values. |
/server/logLevels/name/:componentName/level/:level (POST) | Specify the logger that you are using and a verbosity level. |
/plugins (GET) | Returns a list of all plugins and their dataservices. |
/plugins (PUT) | Adds a new plugin or upgrades an existing plugin. Only available in cluster mode. |
/plugins/:id (DELETE) | Deletes a plugin. Only available in cluster mode. |
Swagger API documentation is provided in the $ROOT_DIR/components/app-server/share/zlux-app-server/doc/swagger/server-plugins-api.yaml
file. To see it in HTML format, you can paste the contents into the Swagger editor at https://editor.swagger.io/.
Note: The "agent" end points interact with the agent specified in the server.json
file. By default this is ZSS.