Welcome to the IBM Security Verify Governance Adapter for Broadcom ACF2.

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

• IBM Security Identity Manager CA ACF2 for z/OS Adapter Installation and Configuration Guide 

• IBM Security Privileged Identity Manager CA ACF2 for z/OS Adapter Installation and Configuration Guide 

• IBM Security Identity Governance and Intelligence CA  ACF2 for z/OS Adapter Installation and Configuration Guide 

• IBM Security Verify Governance Broadcom ACF2 for z/OS Adapter Installation and Configuration Guide 

• IBM Security Verify Identity Broadcom ACF2 for z/OS Adapter Installation and Configuration Guide 

The ACF2 for z/OS Adapter is designed to create and manage ACF2 for z/OS accounts. The adapter runs in ”agent” mode and must be installed on z/OS. One adapter is installed per ACF2 installation..

The IBM Security 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  IBM Security 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.

Review and agree to the terms of the IBM Security Verify 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,

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

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

The ACF2 Adapter does not use Secure Socket Layer (SSL) by default to communicate with IBM Security Verify Governance Identity Manager. You have to configure it.

SSL requires digital certificates and private keys to establish communication between the endpoints. Regarding SSL, the ACF2 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 (IBM Security Verify Governance Identity Manager) 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 IBM Security Verify Governance Identity Manager.

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. You can specify the port number on the adapter service form on IBM Security Verify Governance Identity Manager. Ensure that it references the same port number that is configured for the adapter on the z/OS host. The TCP/IP port value can be updated in the VERAGT00 PARMLIB member.

Use the agentCfg utility to configure the adapter. The utility communicates with the adapter through TCP/IP. The TCP/IP port number that is used is dynamically assigned and is in the range 44970 - 44994. The port number and the range of port numbers cannot be configured.

No updates for the current release

Update the panel in Step 9 : Select Adapter communication parameters to define or alter the Identity server to adapter communication settings.

Adapter communication parameters                                              

Update the explaining text as below:

IP Communications Port Number

Specifies the default IP Communications Port Number, which is 45580. When more than one adapter is active in the same LPAR, use a different port number for each adapter instance.

Adapter authentication ID and Adapter authentication password

Specifies the adapter authentication ID and password that are stored in the adapter registry. The ID and password are used to authenticate the Identity server to the ACF2 Adapter. These two parameters must also be specified on the adapter service form that is created on IBM Security Verify Governance Identity Manager.

Enable SSL

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

Update the panel in Step 10 :Select ACF2 site specific parameters.

Site specific ACF2 configuration

  @HEADER field as defined in the ACFFDR

    ===>

  @UID field as defined in the ACFFDR

    ===>

   Fully qualified name of a dataset in the PARMLIB concatenation.

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

   ===>

Update the explaining text as below:

@HEADER

Specify the @HEADER string as specified in the ACFFDR. The fields that are specified in this string are collected during a single account lookup.

@UID

Specify the @UID string as specified in the ACFFDR. The fields that are specified in this string are collected during a single account lookup.

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

The adapter must run under a valid ACF2 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 make sure that the output for the following command is never empty if the adapter is running: ` ps -ef | grep -i <ADAPTERID> | grep -v grep`

For the adapter to perform requests on behalf of another user, you must define one or more SURROGATE class rules.

The CA ACF2 adapter logonid must have UPDATE permission on the BPX.SERVER resource in the FACILITY class

Table 1.

Complete the service/target form fields.

On the General Information tab:

Service Name

Specify a name that identifies the ACF2 Adapter service on the Identity server.

Service Description

Optional: Specify a description that identifies the service for your environment. You can specify additional information about the service instance.

URL

Specify the location and port number of the adapter. The port number is defined during installation, and can be viewed and modified in the PARMLIB member.

No updates for the current release

Configuring the adapter parameters

Remove the following paragraphs:

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

add:

If specific fields that belong to the ACFFDR UI or HEADER are not returned during a filtered reconciliation, it is possible that the adapter does not run APF authorized.

Validate if the adapter binaries and libraries are APF authorized in the <adapter_readonly_home>/bin and <adapter_readonly_home/lib> folders.

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:

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 RACF Adapter environment variables table.

Add the below paragraphs:

Gencert sitecert.server subjsdn(cn='server.my.company.com' o='My Company' ou='My Dept' l='My location' sp=Illinois c=US) size(512) label(Certificate for my server) signwith(certauth label(CA certificate for My Company)

Gencert VERAGT.cert subjsdn(cn='VERAGNT' o='My Company' ou='My Dept' l='My location' sp=Illinois c=US) size(512) label(VERAGNTcert) signwith(certauth label(CA certificate for My Company))

Set profile(user) div(keyring)

Insert VERAGNT ringname(KEYRING)

Set profile(user) div(keyring)

Connect certdata(VERAGNT) label(VERAGNTcert) keyring(VERAGNT) ringname(KEYRING) default

export VERAGNT label(VERAGNTcert) dsn('veragnt.cert.p12') format(pkcs12der) password(mysecretpassword)

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

The ACF2 adapter requires one process per thread plus 8.  The default settings are for 3 threads for each of the four types or requests which is a maximum of 12 active threads which equates to 20 processes (12 + 8).  This is below the default MAXUSERPROC value of 25.  If you change the maximum thread count variables via agentCfg then you might need to increase the MAXUSERPROC parameter in the parmlib member BPXPRMxx.

The  IBM Security 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 ACF2 for z/OS adapter has REXX scripting options. Please see the ACF2  adapter for z/OS Installation and Configuration guide for additional details.

The integration to the IBM Security Verify server – the adapter framework – is supported. However, IBM does not support the customizations, 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.

The IBM Security Verify Manager Adapter supports any combination of the following product versions.

Adapter Installation Platform

             z/OS V2.5

 z/OS  V3.1

Managed Resource:

CA ACF2 R16

 IBM Security Verify Governance:

 IBM Security Verify Governance  v10.x

 IBM Security Verify Governance Identity Manager:

 IBM Security Verify Identity  v10.x

IBM License Tags release (Agent_License) 11.0.0

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

IBM Security Identity Manager
IBM Security Verify

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, CA ACF2, and CA Top Secret are trademarks of CA, 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