Welcome to the IBM Security Verify Governance Broadcom Top Secret Adapter.

These Release Notes contain information for the following products that was not available when the IBM Security Verify Governance Adapter manuals were created:

• IBM Security Verify Governance Broadcom Top Secret Adapter Installation and Configuration Guide 

The Broadcom Top Secret Adapter is designed to create and manage Broadcom Top Secret accounts. The adapter runs in ”agent” mode and must be installed on z/OS. One adapter is installed per Broadcom Top Secret Database, but the Broadcom Top Secret Adapter may be configured to support a subset of the accounts through the scope of authority feature on the Broadcom Top Secret Service Form.

The deployment configuration is based, in part, on the topology of your network domain, but the primary factor is the planned structure of your Identity Provisioning Policies and Approval Workflow process. Please refer to the IBM Knowledge Center for a discussion of these topics.

The Verify Governance Adapters are powerful tools that require administrator level authority. Adapters operate much like a human system administrator, creating accounts, permissions and home directories. Operations requested from the Verify server will fail if the adapter is not given sufficient authority to perform the requested task. IBM recommends that this adapter run with administrative permissions.

By service groups, IBM Security Verify Governance - Identity Manager is referring to any logical entity that can group accounts together on the managed resource.

Managing service groups implies the following:

 Create service groups on the managed resource.

 Modify attribute of a service group.

 Delete a service group.

 Note that service group name change is not supported in the current IBM Security Verify Governance

             Adapter editions.

The Broadcom Top Secret Adapter does not support service groups management.

Review and agree to the terms of the IBM Security Verify Governance product license prior to using this product. The license can be viewed from the "license" folder included in the product package.

In this release the ADK is upgrade to a version which no longer supports OpenSSL-based SSL communication. SSL connections require the use of AT-TLS. It also no longer supports the use of the DAML_USER and DAML_PASSWORD based authentication using the adapter internal accounts. This release of the adapter mandates a protected adapter logonid to run the started task and a valid SURROGATE ACF loginud and password to authenticate to the adapter and perform all the supported operations such as performing reconciliations, add users, changing passwords and connecting users to groups. The use of a separate ACF2 logonid that can be used to authenticate using a password or password phrase is required as well as the use of a separate, protected logonid for the adapter, since the logonid that is used to authenticate with might get locked out after a defined number of failed login attempts.   The ADAPTER ID requires update access to BPX.SERVER in class FACILITY and READ access to the profile for the SURROGATE ID in class SURROGAT.  The SURROGATE logonid requires READ access to all the documented IRR.RADMIN.XX profiles . This has not changed for those who already used a SURROGAT ID in previous releases of this adapter. The only difference is that the use of a SURROGATE ID  now is mandatory and it's value is defined in the DAML_USER and DAML_PASSWORD section of the service form on the server , rather than in the erracfrequester variable.

A secondary security control has been added to the authentication process. If a specific server exceeds a configuration amount of failed login attempts, the server will be disallowed to try to authenticate for a configurable number of seconds.

The AT-TLS configuration using the policy agent requires a valid certificate in a keyring,

Upgrading to the current release requires a full installation. Refer to the Installing and configuring section of the Broadcom Top Secret adapter guide for detailed instructions.

In the  V7.1.15  and later installation package three profiles are included, one specific for ISVG, one specific for Governance Data Integration and one specific for Identity Manager (SVI).  

Installing the ISVI specific version on an Identity Manager server removes the requirement to install the Complex Attribute Handler.  This can be of interest when you have defined policies on the Identity Manager server that manage ertopzprofile related processing.

If no customization has been done to the Identity Manager server that involves the ertopzprofile attribute, the ISVG-specific profile can be used in combination with the Complex Attribute Handler on Identity Manager servers.

For the Governance Data Integration profile the complex attribute handler is not required. It merely defines the Top Secret Profile object class as a Service Group for ISVG compatibility.This profile can be used if Top Secret profile assignments are being made from  ISVG.

Required additions to the <ProtocollProperties> section of the resource.def when using ISIGADI and managing Top Secret profile assignments from both ISVI and ISVG.

      <Property Name  = "ercomplexattributes"

                Value    = "ertopzprofile" />

      <Property Name  = "erattributehandler"

                Value    = "com.ibm.isim.util.complexattribute.TopSecretComplexAttributeHandler" />

Before you start the adapter, ensure that TCP/IP is active.

Starting ADK release 6.0.3 the adapter will write a message to SYSLOG and shutdown if it can not connect to the IP communications port. In previous releases the adapter would write an error to the adapter log and remain active without an indication that it could not communicate with the server in the SYSLOG.

The Verify Governance Adapters can be customized and/or extended. The type and method of this customization may vary from adapter to adapter.

Customizing and extending adapters requires a number of additional skills. The developer must be familiar with the following concepts and skills prior to beginning the modifications:

• LDAP schema management 

• Working knowledge of scripting language appropriate for the installation platform 

• Working knowledge of LDAP object classes and attributes 

• Working knowledge of XML document structure 

Note:  This adapter supports customization only through the use of pre-Exec and post-Exec scripting. The Broadcom Top Secret adapter has REXX scripting options. Please see the Broadcom Top Secret Installation and Configuration guide for additional details.

IBM Security Verify Resources:

The integration to the Verify Governance server – the adapter framework – is supported. However, IBM does not support the customization, scripts, or other modifications. If you experience a problem with a customized adapter, IBM Support may require the problem to be demonstrated on the GA version of the adapter before a case is opened.

Replace withL

The Top Secret Adapter requires APF authorization.

• If the Verify server performs operations against only a portion of the Top Secret database, then the ACID defined as SURROGATE ID must be associated with a security administrator acid type  with the appropriate privileges for the portion of the database it administers.

   

  The acid that runs the adapter,   the adapterID, does not require any special privileged attributes. It does, however, require surrogate authority to run functions under the identity of the ACID specified on the IBM Security Verify Governance Identity Manager service form., the surrogateID. The surrogateID ACID specified on the IBM Security Verify Governance Identity Manager service form must have authority to perform the administration functions requested by the Verify  server.

   

The Top Secret resources that require consideration are:

FACILITY class profile STGADMIN.IGG.DEFDEL.UALIAS, with READ

The adapter requires permissions to update the master catalog. Therefore, the surrogate ACID must have one of the following permissions:

• •UPDATE access to the DATASET class profile that protects the master catalog.  

• •UPDATE,CREATE,SCRATCH access to the 'hlq' that is used for the reconciliation and lookup job intermediate data sets.  

• •READ access to the FACILITY class profile that protects the STGADMIN.IGG.DEFDEL.UALIAS resource. The FACILITY class profile can update the master catalog irrespective of the FACILITY class profile name.  

The adapter must run under a valid CA Top Secret loginid, with access to z/OS UNIX System Services, a valid UID, and a valid TSO account.

The name of the adapter instance must match the name of the started task user.

If you are using shared OMVS userIDs you must ensure that the output for the following command is never empty if the adapter is running: ` ps -ef | grep -i <ADAPTERID> | grep -v grep`

The adapter requires READ  permission to be defined for the  SURROGATE user on the following resources:

Table 1.

The adapter ID requires UPDATE on IBMFAC BPX.SERVER and the adapter ID requires READ on IBMFAC BPX.SRV.surrogateid

Replace with below :

The Top Secret Adapter uses IBM Security Verify Governance Identity Manager to perform user tasks on Top Secret for z/OS®.

The adapter can add, modify, suspend, restore, reconcile, or delete users from Top Secret. The adapter uses the TCP/IP protocol to communicate with IBM Security Verify Governance Identity Manager.

The Top Secret Adapter does not use Secure Socket Layer (SSL) by default to communicate with IBM Security Verify Governance Identity Manager. To enable SSL you must perform post configuration steps.

SSL requires digital certificates and private keys to establish communication between the endpoints. Regarding SSL, the Top Secret Adapter is considered a server. When the adapter uses the SSL protocol, the server endpoint must contain a digital certificate and a private key. The client endpoint (Verify Governance Identity Server) must contain the Certificate Authority or CA certificate.

To enable SSL communication by default, install a digital certificate and a private key on the adapter and install the CA certificate on the Verify Governance Identity Server.

The default TCP/IP port on the z/OS host for the adapter and server communication is 45580. You can change this port to a different port. When you specify the port number on the adapter service form on IBM Security Verify Governance Identity Manager, make sure that it references the same port number that is configured for the adapter on the z/OS host. The port number is can be configured by updating the VERAGT00 PARMLIB member and restarting the adapter.

You can restrict the use of these ports to the Top Secret Adapter. To protect these ports with the Top Secret protection, define the profiles in the Top Secret Adapter SERVAUTH resource class. For more information, see the z/OS Communications Server, IP Configuration Guide.

No updates in the current release

Update the panel for Step  7.a  Select Disk location parameters to define or alter data set and UNIX System Services (USS) locations.

As below:

-------- VERIFY Top Secret Adapter Customization -----

  Input Data Sets

   Fully qualified data set name of the UPLOAD data set.

    ===>                             +

   Fully qualified name of a dataset in the PARMLIB concatenation.

   This dataset will be used to copy the environment settings member to.

    ===>

 Enter data sets names, volume ID, Storage Class and z/OS Unix directories.

   USS Adapter read-only home

    ===>

   USS Adapter read/write home

    ===>

   Storage Class %===>

     and/or

   Disk Volume ID%===>

   Fully qualified data set name of Adapter Load Library

    ===>                              +

   Fully qualified data set name of Adapter EXEC Library

                                   +

Fully qualified data set name of the UPLOAD data set

Specifies the name of the data set that you have received earlier. For example, IBMUSER.VERTSS.UPLOAD.XMI.

Fully qualified name of a dataset in the PARMLIB concatenation.            

    Fully qualified name of a dataset in the PARMLIB concatenation.            

    This dataset will be used to copy the environment settings member VERAGT00 to.

This member contains all the adapter configuration settings as used to be available in the registry.dat file for adapter versions prior to version 10.0.010.00

Specify maximum number of failed login attempts for this ISVG/ISVGIM server after which, on the next attempt, new authentication attempts from the same ISVG/ISVGIM server will be blocked for a given number of seconds.

Specify number of seconds to block the ISVG/ISVG-IM server address after exceeding the maximum number of failed login attempts

Top Secret ID under which requests will be processed

Optional: Specify a Top Secret ACID other than the one that is used by the adapter. This ACID can be a Control ACID with authority over a subset of ACIDs in the Top Secret database.

1. 1.Test the connection for the service that you created on the Identity server.  

2. 2.Run a full reconciliation from the Identity server.  

3. 3.Run all supported operations such as add, modify, and delete on one user account.  

4. 4.Verify the ibmdi.log  adapter logfile and the z/OS syslog after each operation to ensure that no errors are reported.  

5. 5.Verify the trace.log file to ensure that no errors are reported when you run an adapter operation.  

No updates in the current release

Remove the below paragraph

Add the below paragraph:

Changing configuration settings:

To change a configuration setting, edit the parmlib member and restart the adapter.

Note that the configuration/registry settings need to be added in the format: name=value. Each setting/value combination needs to be specified on a new line.

E.g.  SSLMODE=ATTLS

See the following references for more information:

https://www.ibm.com/docs/en/zos/3.1.0?topic=applications-environment-variables

https://www.ibm.com/docs/en/zos/3.1.0?topic=evszxcl-cee-envfile#ceeenvf

See  Chapter 7 of the adapter Installation and Configuration Guide for an overview of the registry settings and their values.

Next in

Section: Configuring SSL Authentication

Remove:

DAML SSL implementation

1. aware - set controlling to false and enabled to true in /etc/pagent/ttls.policy . Use https in the connection from ISVG/ISVGIM. Define SSLMODE=NONE in parmlib member

2. application controlled: set controlling and enabled to true etc/pagent/ttls.policy . Use https in the connection from ISVG/ISVGIM. Define SSLMODE=ATTLS in parmlib member

3. don't use AT-TLS:  set enabled and controlling to false in /etc/pagent/ttls.policy. User http in the connection from ISVG/ISVGIM. Define SSLMODE=none in parmlib member

Note: if you set controlling to false and SSLMODE=ATTLS, you will see an ioct error in the adapter logs

Profile entitlements and Rights

The order of profiles attached to an ACID is important and affects the checking of the profile permissions.

To add profiles in a particular order you must add the profile names in the account form in this manner. The first number indicates the order and the separator is a vertical bar character:

010|PROFA

020|PROFB

The profile names are sorted by number (if necessary) by the adapter and added to the ACID in that order.

Any request to update ertopzprofile values must have the profile values in the request sorted from the lowest sequence to the highest sequence.

For instance:

<Modification Operation="replace">

<attr name="ertopzprofile">

                               <value>010|T3AUTO40</value>

                               <value>020|T3AUTO20</value>

                               <value>030|T3AUTO50</value>

</attr>

</Modification>

If the profiles in the request are not ordered by sequence, this will result in inconsistency in the profile assignments.

Add paragraph:

AT-TLS return codes:

For AT-TLS return codes, please see:

add:  

Q: I can see "__errno2 = "" message in the log .  What do they mean?

A: you  can use the bpxmtext utility to find the full text for the errorno2 number. E.g.:

bpxmtext 77b77221                                                                                                                                                    

TCPIP

JRGetConnErr: The connection was not in the proper state for retrieving.

Action: Try the request later.

bpxmtext 05230138                                                                                                                                                    

BPXFSCLS 02/14/24

JRFileIsBlocked: The file is blocked

Action: The request cannot be processed.  Try again later.

remove:

Why is my registry file cleared?

There might be several causes. To determine the cause, provide an answer to the following questions when contacting support:

It might be useful to collect the output from the following commands at the time a correct, configured registry file is active and compare that output to the output for the same commands after an IPL when you notice the registry is reset:

df -k /adapter_readwrite_home

ls -Elg /adapter_readwrite_home/data

/adapter_readwrite_home/bin/regis /adapter_readwrite_home/data/<adapter_name>.dat -list

Move the table to the "Environment variables" paragraph and rename that paragraph to "Configuration settings/Environment variables".

Add the below rows to the table:

Option  Default value    Valid Value    Function and Meaning             Required                          

SSLMODE     ATTLS                 ATTLS, NONE  Use SSL or not                          No

TLSVER         VERSION1   VERSION1,   AT-TLS Version      No

         VERSION2

TIMEOUT  N/A      any numeric   Seconds wait before allowing  No

              new authentication attempts

MFAILED N/A      any numeric   Maximum failed login attempts  No

              before setting the TIMEOUT for

              the service.

Remove the rows for REGISTRY and ISIM_ADAPTER_CIPHER_LIST from the Adapter environment variables table.

Add the below paragraphs:

If you experience issues opening an account form after upgrading to the latest release , it might be required to start the design forms editor, open the Top Secret account form and select save. It is not required to make any changes to the form.

The IBM Security Verify Governance Adapter supports any combination of the following product

versions.

Operating Systems:

z/OS V2.5

z/OS V3.1

Managed Resource:

Broadcom CA Top Secret for z/OS R16

 IBM Security Verify Governance:

 IBM Security Verify Governance  v10.x

Notices

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation

North Castle Drive

Armonk, NY  10504-1785  U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation

Licensing

2-31 Roppongi 3-chome, Minato-ku

Tokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged should contact:

IBM Corporation

2ZA4/101

11400 Burnet Road

Austin, TX 78758  U.S.A.

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

The following terms are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both:

IBM
IBM logo

Adobe, Acrobat, Portable Document Format (PDF), and PostScript are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, other countries, or both.

Cell Broadband Engine and Cell/B.E. are trademarks of Sony Computer Entertainment, Inc., in the United States, other countries, or both and is used under license therefrom.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Microsoft, Windows, Windows NT®, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

Intel®, Intel logo, Intel Inside®, Intel Inside logo, Intel Centrino™, Intel Centrino logo, Celeron®, Intel Xeon™, Intel SpeedStep®, Itanium®, and Pentium® are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

CA ACF2, and CA Top Secret are trademarks of Broadcom, Inc. in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Linux is a trademark of Linus Torvalds in the U.S., other countries, or both.

ITIL® is a registered trademark, and a registered community trademark of the Office of Government Commerce, and is registered in the U.S. Patent and Trademark Office.

IT Infrastructure Library® is a registered trademark of the Central Computer and Telecommunications Agency which is now part of the Office of Government Commerce.

Other company, product, and service names may be trademarks or service marks of others.

End of Release Notes