E Configuring External Authentication Providers for STA

This appendix describes how to configure Oracle's WebLogic Server to use one or more external authentication providers to authenticate users for STA. It includes the following sections:

Understanding the WebLogic Server Active Security Realm
Considerations for Configuring External Authentication Providers
Authentication Provider Configuration Process Overview
Tasks for Configuring Active Directory and OpenLDAP Authentication Providers
Tasks for Configuring IBM RACF Authentication Providers

See Fusion Middleware Securing Oracle WebLogic Server for complete details about managing user authentication with WebLogic Server.

To create users from within the STA application, see the STA User's Guide.

Understanding the WebLogic Server Active Security Realm

WebLogic Server, which is included in the STA installation, manages all user authentication for STA. The STA installation includes one WebLogic Server active security realm, named myrealm. All authentication providers for STA must be defined in this security realm.

WebLogic Server includes an embedded LDAP server, and this is the default authentication provider for STA. During STA installation, the embedded LDAP server is configured in the active security realm with the name DefaultAuthenticator. The DefaultAuthenticator data store includes credentials for the two default user accounts defined during STA installation—the WebLogic Administrator and the default STA Administrator. It also includes credentials for all STA usernames created through the STA user interface.

Note:

Do not change the names of the myrealm security realm and the DefaultAuthenticator; these names are required for STA.

Note:

The active security realm also includes a provider named DefaultIdentityAsserter. Do not make any changes to this provider.

Considerations for Configuring External Authentication Providers

For most sites, the DefaultAuthenticator may be the only authentication provider needed for STA. You can create and maintain STA usernames through the STA user interface, and the DefaultAuthenticator will authenticate and authorize users as they log in.

For some sites, however, it may be desirable to use external providers, in addition to the DefaultAuthenticator, to authenticate STA users. This is useful if your site has many users with credentials already defined on external authentication servers. You can configure one or more external authentication providers for STA.

The following sections provide information for configuring external authentication providers for STA.

"Supported Authentication Provider Types"
"Using the WebLogic Administration Console"
"LDAP Principal User"
"STA Access Group"
"Default STA User Role"
"Configuring the Authentication Process for Multiple Providers"
"LDAP Authentication Referrals"
"Using SSL for Communications"

Supported Authentication Provider Types

STA supports the following authentication provider types:

OpenLDAP
Microsoft Active Directory (AD)
IBM Resource Access Control Facility (RACF)

Using the WebLogic Administration Console

Use the WebLogic Administration console for all STA authentication provider configuration tasks in WebLogic Server. See "Edit the WebLogic Server Active Security Realm" for instructions.

LDAP Principal User

Each external authentication provider must include a user account that WebLogic Server can use to connect to the external provider. In WebLogic Sever, this user is called the Principal user. You can either create a new user account for this purpose or use an existing one. See "Prepare the External Authentication Provider for STA Authentication" for instructions.

This user must have read and write access to the external provider's authentication directory so WebLogic Server can resolve user and group searches and authentications. This user does not need to be assigned to the STA access group (see "STA Access Group", below.

STA Access Group

All users requiring access to STA must belong to the STA access group, which has the name StorageTapeAnalyticsUser. All providers performing authentication for STA must include this group.

For the DefaultAuthenticator, this group is created during STA installation, and all users added through the STA installer, WebLogic Administration console, and STA user interface are assigned to this group automatically.

For external authentication providers, you must create this group in the provider and assign the appropriate users to it. See "Prepare the External Authentication Provider for STA Authentication" for instructions.

Default STA User Role

STA users from external authentication providers are assigned the STA Viewer role by default. If a user requires a different role (Operator or Administrator), you must modify it manually through the STA user interface. See theSTA User's Guide for details about STA user roles.

Configuring the Authentication Process for Multiple Providers

When configuring multiple authentication providers, you can use the following options to control how WebLogic Server uses the providers in the authentication process.

Authentication Provider Order

When a user attempts to log in to STA, WebLogic Server calls authentication providers in the order they are listed in the Authentication Providers table. By default, the providers are listed in the order they were added to the active security realm, but you can change their order to better meet the needs of your site. For example, if an external authentication provider includes many STA users, you may want to put that provider at the top of the list so it is called first. See "Task 4: Ensure Proper Order of Authentication Providers" for instructions.

Note:

The DefaultAuthenticator and the DefaultIdentityAsserter must be the first two providers in the list.

JAAS Control Flag

The Java Authentication and Authorization Service (JAAS) Control Flag attribute assigned to each provider defines whether users must be authenticated by that provider. The default value for this attribute is "Optional," but for STA, Oracle recommends setting it to "Sufficient" for each provider, including the DefaultAuthenticator. See "Task 3: Set the JAAS Control Flag" for instructions.

The "Sufficient" setting indicates that if the provider successfully authenticates a user, no additional authentication is required, and if the provider cannot authenticate the user, authentication continues to the next provider in the list. See Fusion Middleware Securing Oracle WebLogic Server for descriptions of all options for this attribute.

LDAP Authentication Referrals

If an external authentication provider uses LDAP referrals, you must ensure that the Follow Referrals attribute is selected on the Provider Specific screen. This attribute is selected by default, but Oracle recommends you verify the setting. See "Task 2: Define Provider-specific Information" for instructions.

Using SSL for Communications

If the connection between WebLogic Server and the external authentication server is to be secured through SSL, you must perform the following activities:

Ensure that the SSLEnabled attribute is selected on the Provider Specific screen. See "Task 2: Define Provider-specific Information" for instructions.
Create and configure a custom trust keystore in WebLogic Server for use with the external authentication server. See Fusion Middleware Securing Oracle WebLogic Server for instructions.

Authentication Provider Configuration Process Overview

This section summarizes the tasks required to configure one or more external authentication providers for STA. See the referenced tasks for detailed instructions.

Prepare the external provider to authenticate STA users, and gather configuration information required by WebLogic Server. See "Prepare the External Authentication Provider for STA Authentication" for instructions.
Configure WebLogic Server to use external authentication providers. For each provider, perform all of the following tasks in the order indicated.
1. Add the external authentication provider to the WebLogic active security realm. See "Task 1: Add an External Authentication Provider" for instructions.
2. Configure provider-specific information for the authentication provider. See "Task 2: Define Provider-specific Information" for instructions.
3. Set the JAAS control flag for the provider. See "Task 3: Set the JAAS Control Flag" for instructions.
4. Ensure WebLogic Server will call all authentication providers in the order you want. See "Task 4: Ensure Proper Order of Authentication Providers" for instructions.
5. Apply the changes to WebLogic Server and STA. See "Task 5: Apply All Configuration Changes" for instructions.
Verify the configuration. See "Verify Configuration of Authentication Providers" for instructions.

Tasks for Configuring Active Directory and OpenLDAP Authentication Providers

Use the following procedures to configure OpenLDAP and Microsoft Active Directory authentication providers. To configure IBM RACF providers, see "Tasks for Configuring IBM RACF Authentication Providers".

"Prepare the External Authentication Provider for STA Authentication"
"Edit the WebLogic Server Active Security Realm"
"Task 1: Add an External Authentication Provider"
"Task 2: Define Provider-specific Information"
"Task 3: Set the JAAS Control Flag"
"Task 4: Ensure Proper Order of Authentication Providers"
"Task 5: Apply All Configuration Changes"
"Verify Configuration of Authentication Providers"

Prepare the External Authentication Provider for STA Authentication

Use this procedure to prepare an external authentication provider to authenticate STA users. This procedure provides general guidelines only, as the specific details depend on your site configuration. Perform these steps on the external authentication server.

Identify or create the LDAP Principal user, which WebLogic Server will use to access the external authentication provider. See "LDAP Principal User" for details.
Create the STA access group. This group must have the name StorageTapeAnalyticsUser. See "STA Access Group" for details.
Identify all users needing access to STA and assign them to the STA access group.
Record site-specific configuration information, which you will use to configure the provider in WebLogic Server. See "Task 2: Define Provider-specific Information" for examples of the information to gather.

Edit the WebLogic Server Active Security Realm

This procedure provides general instructions for logging in to the WebLogic Administration console and making changes to the WebLogic Server active security realm.

Start a supported Web browser on your computer.
In the Location Bar or Address field, enter the URL of the WebLogic Administrator console. The URL uses one of the following formats:

http://local_host_name:port_number/console

https://local_host_name:port_number/console

where local_host_name and port_number are the name and port number of the WebLogic Administrator console defined during STA installation. The default HTTP port number is 7019, and the default HTTPS port number is 7020. For example:
```
https://sta_server:7020/console
```
On the Welcome screen, enter the WebLogic Administration console username and password defined during STA installation, and then click Login.

Description of the illustration ''wl_login.png''

The WebLogic Server Administration Console Home page appears.

Description of the illustration ''wl_home.png''
Use the following steps to access the active security realm.
1. In the Domain Structure navigation tree, select Security Realms.
  
  Description of the illustration ''wl_secrealm.png''
2. In the Realms table, select the myrealm active link.
  
  Description of the illustration ''wl_myrealm.png''
The Settings for myrealm screen appears.
Use the tabs in the control bar to navigate to the screens you want to edit. You can make changes to multiple screens during a single editing session.

Description of the illustration ''wl_controlbar.png''
Use the Change Center section as follows:
- To make changes to the screens, you must click Lock & Edit. This locks out other users from making changes at the same time.
  Description of the illustration ''wl_lockedit.png''
- When you have finished editing each screen, click Save to keep the changes or Release Configuration to cancel them.
- When you have finished your editing session, click Activate Changes to apply all changes to all screens.
- At any time during your editing session, you can click Undo All Changes to cancel all changes to all screens.
For your changes to take effect in STA, you must log out of the WebLogic Administration console and stop and restart STA. See "Task 5: Apply All Configuration Changes" for instructions.

Task 1: Add an External Authentication Provider

Use this procedure to add an external authentication provider to the WebLogic Server active security realm.

If you have not done so already, access the active security realm and lock it from other users. See "Edit the WebLogic Server Active Security Realm" for instructions
In the Settings for myrealm control bar, select the Providers tab.

Description of the illustration ''wl_providers.png''

The Authentication secondary tab is selected by default.

Description of the illustration ''wl_providersauth.png''
In the Authentication Providers table, click New.

Description of the illustration ''wl_new.png''
Complete the Create a New Authentication Provider screen as follows, and then click OK.
- Name—Enter a name to identify the authentication provider in the WebLogic Server security realm. For example, "My External OpenLDAP Server" or "My AD Server".
- Type—Select one of the following options:
  - For OpenLDAP providers, select OpenLDAPAuthenticator.
  - For Microsoft Active Directory providers, select LDAPAuthenticator.
  Note:
  The ActiveDirectoryAuthenticator option is not supported; do not use it, even for Microsoft Active Directory providers.
  
  Description of the illustration ''wl_createnew.png''
The external authentication provider is added to bottom of the Authentication Providers table.

Description of the illustration ''wl_providersupd.png''
Proceed to "Task 2: Define Provider-specific Information".

Task 2: Define Provider-specific Information

Use this procedure to define provider-specific information for each external authentication provider you have added to the WebLogic Server active security realm.

Before using this procedure, you must gather the necessary configuration information from the external authentication provider; see "Prepare the External Authentication Provider for STA Authentication" for instructions.

If you have not done so already, access the active security realm and lock it for editing. See "Edit the WebLogic Server Active Security Realm" for instructions.
In the Settings for myrealm control bar, select the Providers tab.

Description of the illustration ''wl_providers.png''

The Authentication secondary tab is selected by default.

Description of the illustration ''wl_providersauth.png''
In the Authentication Providers table, select the active link for the provider you want to configure.

Description of the illustration ''wl_selectprovider.png''

The Settings for authenticator screen appears.
In the control bar, select the Configuration tab and then the Provider Specific secondary tab.

Description of the illustration ''wl_tabproviderspec.png''

The Provider Specific screen appears.

Description of the illustration ''wl_providerspec.png''
Complete the screen attributes using the values you gathered from the external authentication provider. These values must match the directory schema and other configuration attributes specific to that provider.

Following are guidelines for attributes required for a basic configuration. Depending on your site requirements, you may need to enter values for other attributes as well.
- Host—IP address of the external authentication server
- Port—Port number on which the external authentication server is listening. Typically this is 389.
- Principal—Distinguished Name of the user account on the external provider that WebLogic Server will use to connect to the external authentication server. See "LDAP Principal User" for details.
- Credential and Confirm Credential—Password for the Principal user
- SSLEnabled—Select this check box if communication between WebLogic Server and the external authentication server will be through SSL. You must perform additional configuration tasks to fully enable this feature. See "Using SSL for Communications" for details.
- User Base DN—Base distinguished name (DN) of the tree that contains users.
- User From Name Filter—Filter WebLogic Server should use to find users
- User Object Class—LDAP object class that stores users
- Group Base DN—Base distinguished name (DN) of the tree that contains groups
- Group From Name Filter—Filter WebLogic Server should use to find groups
- Group Object Class—LDAP object class that stores groups
- Connection Timeout—The default value is 0, which indicates no timeout limit. Oracle recommends setting this value to a nonzero value, such as 60 (expressed in seconds).
- Follow Referrals—Select this check box if the external authentication provider is configured to use referrals to other authentication servers. See "LDAP Authentication Referrals" for details.
Example E-1 and Example E-2 show sample values for an OpenLDAP and a Microsoft Active Directory provider, respectively. The values you enter will be different, but these examples may assist you with entry syntax.
When you have finished entering screen values, click Save.
Description of the illustration ''wl_providerspecsave.png''

Example E-1 Sample Provider-specific Values for an OpenLDAP Provider

Host: 10.123.456.789

Port: 389

Principle: cn=root,o=staOpen,dc=mycompany,dc=com

Credential: OpenLDAP root password>

Confirm credential: OpenLDAP root password

SSL Enable: not selected

User Base DN: ou=users,o=staOpen,dc=mycompany,dc=com

All Users Filter:

User From Name Filter: (&(cn=%u)(objectclass=posixAccount))

User Search Scope: subtree

User Name Attribute: cn

User Object Class: posixAccount

Use Retrieve User Name as Principle: selected

Group Base DN: ou=groups,o=staOpen,dc=mycompany,dc=com

All Groups Filter:

Group From Name Filter: (&(cn=%g)(objectclass=groupOfUniqueNames))

Group Search Scope: subtree

Group Membership Searching: unlimited

Max Group Membership Search Level: 0

Ignore Duplicate Membership: not selected

Static Group Name Attribute: cn

Static Group Object Class: groupOfUniqueNames

Static Member URL Attribute: uniquemember

Static Group DNs from Member DN Filter: (&(uniqueMember=%M)(objectclass=groupOfUniqueNames))

Dynamic Group Name Attribute:

Dynamic Group Object Class:

Dynamic Member URL Attribute:

User Dynamic Group DN Attribute:

Connection Pool Size: 6

Connect Timeout: 60

Connection Retry Limit: 1

Parallel Connect Delay: 0

Results Time Limit: 0

Keep Alive Enabled: not selected

Follow Referrals: selected

Bind Anonymously On Referrals: not selected

Propagate Cause For Login Exception: selected

Cache Enabled: selected

Cache Size: 32

Cache TTL: 60

GUID Attribute: entryuuid

Example E-2 Sample Provider-specific Values for an Active Directory Provider

Host: 10.123.456.789

Port: 389

Principle: CN=StaLdapUser,OU=Users,O=STA,DC=oracle,DC=com

Credential: LDAP (SAM) password

Confirm credential: LDAP (SAM) password>

SSL Enable: not selected

User Base DN: OU=Users,O=STA,DC=mycompany,DC=com

All Users Filter:

User From Name Filter: (&(cn=%u)(objectclass=user))

User Search Scope: subtree

User Name Attribute: cn

User Object Class: user

Use Retrieve User Name as Principle: selected

Group Base DN: OU=Groups,O=STA,DC=oracle,DC=com

All Groups Filter:

Group From Name Filter: (&(cn=%g)(objectclass=group))

Group Search Scope: subtree

Group Membership Searching: unlimited

Max Group Membership Search Level: 0

Ignore Duplicate Membership: not selected

Use Token Groups for Group Membership Lookup: not selected

Static Group Name Attribute: cn

Static Group Object Class: group

Static Member URL Attribute: member

Static Group DNs from Member DN Filter: (&(member=%M)(objectclass=group))

Dynamic Group Name Attribute: >

Dynamic Group Object Class:

Dynamic Member URL Attribute:

User Dynamic Group DN Attribute:

Connection Pool Size: 6

Connect Timeout: 60

Connection Retry Limit: 1

Parallel Connect Delay: 0

Results Time Limit: 0

Keep Alive Enabled: not selected

Follow Referrals: selected

Bind Anonymously On Referrals: not selected

Propagate Cause For Login Exception: selected

Cache Enabled: selected

Cache Size: 32

Cache TTL: 60

GUID Attribute: objectguid
Proceed to "Task 3: Set the JAAS Control Flag".

Task 3: Set the JAAS Control Flag

Use this procedure to set the JAAS control flag to indicate how WebLogic Server will use each provider in the user authentication process. See "JAAS Control Flag" for details.

Note:

You must perform this procedure for all authentication providers, including the DefaultAuthenticator. Do not perform this procedure for the DefaultIdentityAsserter.

If you have not done so already, access the active security realm and lock it for editing. See "Edit the WebLogic Server Active Security Realm" for instructions.
In the Settings for myrealm control bar, select the Providers tab.

Description of the illustration ''wl_providers.png''

The Authentication secondary tab is selected by default.

Description of the illustration ''wl_providersauth.png''
In the Authentication Providers table, select the active link for the provider you want to update.

Description of the illustration ''wl_selectprovider.png''

The Configuration tab and Common secondary tab are selected by default.
In the Control Flag menu, select Sufficient.

Description of the illustration ''wl_jaassufficient.png''
Click Save.
Proceed to "Task 4: Ensure Proper Order of Authentication Providers".

Task 4: Ensure Proper Order of Authentication Providers

Once you have added external authentication providers to the active security realm, use this procedure to define the order in which they are called by WebLogic Server. By default, new authentication providers are added to the bottom of the list and are therefore called last. See "Authentication Provider Order" for details.

If you have not done so already, access the active security realm and lock it for editing. See "Edit the WebLogic Server Active Security Realm" for instructions.
In the Settings for myrealm control bar, select the Providers tab.

Description of the illustration ''wl_providers.png''

The Authentication secondary tab is selected by default.

Description of the illustration ''wl_providersauth.png''
In the Authentication Providers table, click Reorder.

Description of the illustration ''wl_reorder.png''
In the Reorder Authentication Providers table, arrange the providers in the order you want WebLogic Server to access them, from first to last. Select the check box of the providers you want to reorder, then use the arrow buttons to move them up or down in the list.

Note:
The DefaultAuthenticator and the DefaultIdentityAsserter must be the first two providers in the list.

Description of the illustration ''wl_reorderarrow.png''
When the providers are listed in the order you want, click OK.

Description of the illustration ''wl_reorderok.png''

The Authentication Providers table is updated.

Description of the illustration ''wl_providerorderupd.png''
Proceed to "Task 5: Apply All Configuration Changes".

Task 5: Apply All Configuration Changes

Use this procedure to apply all changes you have made during this editing session. The changes are applied to WebLogic Server and STA.

In the Change Center section, click Activate Changes.

Description of the illustration ''wl_activate.png''

The Messages area indicates that STA must be restarted for the changes to take effect.

Description of the illustration ''wl_message.png''
Log out of the WebLogic Administration console.

Description of the illustration ''wl_logout.png''
Open a terminal session on the STA server and log in as the system root user.

Stop all STA services. See the STA Administration Guide for command usage details.

# STA stop all
Stopping the staui service......
Successfully stopped the staui service
Stopping the staadapter service......
Successfully stopped the staadapter service
Stopping the staengine service......
Successfully stopped the staengine service
Stopping the staweblogic service......
Successfully stopped the staweblogic service
Stopping the staservd Service...
Successfully stopped staservd service
Stopping the mysql service.....
Successfully stopped mysql service
#

Start all STA services.

# STA start all
Starting mysql Service..
mysql service was successfully started
Starting staservd Service.
staservd service was successfully started
Starting staweblogic service......
staweblogic service was successfully started
Starting staengine Service.........
staengine service was successfully started
Starting staadapter Service..........
staadapter service was successfully started
Starting staui Service..........
staui service was successfully started
#

Proceed to "Verify Configuration of Authentication Providers".

Verify Configuration of Authentication Providers

After you have finished configuring one or more external authentication providers for STA, use this procedure to verify that WebLogic Server can access the appropriate users and groups.

If you have not done so already, access the active security realm and lock it for editing. See "Edit the WebLogic Server Active Security Realm" for instructions.
In the Settings for myrealm control bar, select the Users and Groups tab and then the Groups secondary tab.

Description of the illustration ''wl_tabgroups.png''

The Groups screen appears.
Verify that the Groups table includes groups from all configured external authentication providers. The following example shows groups from two external providers.

Description of the illustration ''wl_externalgroups.png''
In the Settings for myrealm control bar, select the Users secondary tab.

Description of the illustration ''wl_tabusers.png''

The Users screen appears.
Verify that the Users table includes all users assigned to the STA access group (StorageTapeAnalyticsUser) on the configured external providers. The following example shows users from two external providers.

Description of the illustration ''wl_externalusers.png''
Log out of the WebLogic Server Administration console.

Description of the illustration ''wl_logout.png''
Verify that you can use a user account from the external authentication provider to log in to STA and display the Dashboard.

Description of the illustration ''wl_loginsta.png''

Description of the illustration ''wl_stadashboard.png''
If a user from an external authentication provider requires STA Operator or Administrator privileges, use the STA user interface to change their role. See the STA User's Guide for instructions. See "Default STA User Role" for additional information.

Tasks for Configuring IBM RACF Authentication Providers

Use the following procedures to configure IBM RACF authentication providers. You must complete the procedures in the order listed.

To configure OpenLDAP and Microsoft Active Directory authentication providers, see "Tasks for Configuring Active Directory and OpenLDAP Authentication Providers".

"Task 1: Review IBM RACF Mainframe Minimum Requirements"
"Task 2: Enable Mainframe Support for STA RACF Authorization"
"Task 3: Configure AT-TLS"
"Task 4: Create the RACF Profiles Used by the CGI Routine"
"Task 5: Import the Certificate File and Private Key File (optional)"
"Task 6: Test the CGI Routine"
"Task 7: Set Up RACF/SSP for the WebLogic Console"
"Task 8: Configure SSL Between STA and RACF"
"Task 9: Configure the WebLogic Server"
"Task 10: Install RACF/SSP on the WebLogic Console"

Note:

STA supports third-party products that are compatible with IBM RACF—for example, CA's ACF-2 and Top Secret. It is up to the person installing STA, or a security administrator, to issue the commands appropriate for the security product installed.

Task 1: Review IBM RACF Mainframe Minimum Requirements

See the STA Requirements Guide for complete RACF requirements, including required PTFs that must be installed on the MVS system to configure STA authentication with RACF.

Task 2: Enable Mainframe Support for STA RACF Authorization

The mainframe side of the RACF service for STA is provided by a CGI routine that is part of the StorageTek Storage Management Component (SMC) for ELS 7.0 and 7.1. This CGI routine is called by the SMC HTTP server and uses RACF profiles defined in the FACILITY class.

For STA to use RACF for access authentication, on the MVS system you must set up an SMC Started Task that runs the HTTP server. See the ELS document Configuring and Managing SMC for detailed instructions.

Note:

The SMC Started Task must match the AT-TLS rule that has been defined. Alternately, allow the AT-TLS definition to use a generic jobname (for example, SMCW).

If you are using a value-supplied STC identifier (for example, JOBNAME.JOB), this will cause a CGI routine connection failure.

The port number used for the HTTP server must match the one defined in the WebLogic console, and the host must match the IP name for the host where the SMC task runs.

Note:

An existing SMC can be used if it exists on the host where RACF authorization is to be performed. In this case, use the port number of the existing HTTP server when you are performing the WebLogic configuration.

Task 3: Configure AT-TLS

Application Transparent Transport Layer Security (AT-TLS) is an encryption solution for TCP/IP applications that is transparent to the application server and client. Packet encryption and decryption occurs in the z/OS TCPIP address space at the TCP protocol level. AT-TLS requirements for RACF authorization are stated in the STA Requirements Guide.

The following RACF commands list the status of the various RACF objects that you will define in the configuration process:

RLIST STARTED PAGENT.* STDATA ALL
RLIST DIGTRING *ALL
RLIST FACILITY IRR.DIGTCERT.LISTRING ALL
RLIST FACILITY IRR.DIGCERT.LST ALL
RLIST FACILITY IRR.DIGCERT.GENCERT ALL
RACDCERT ID(stcuser) LIST
RACDCERT ID(stcuser) LISTRING(keyringname)
RACDCERT CERTAUTH LIST

Use this procedure to configure AT-TLS so the port number defined to the SMC HTTP Server and WebLogic is encrypted to the STA server.

Specify the following parameter in the TCPIP profile data set to activate AT-TLS.
```
TCPCONFIG TTLS
```
This statement may be placed in the TCP OBEY file.

Configure the Policy Agent (PAGENT)

The Policy Agent address space controls which TCP/IP traffic is encrypted.

Enter the PAGENT started task JCL.

For example:

//PAGENT PROC
//*
//PAGENT EXEC PGM=PAGENT,REGION=0K,TIME=NOLIMIT,
// PARM='POSIX(ON) ALL31(ON) ENVAR("_CEE_ENVFILE=DD:STDENV")/-d1'
//*
//STDENV DD DSN=pagentdataset,DISP=SHR//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//*
//CEEDUMP DD SYSOUT=*,DCB=(RECFM=FB,LRECL=132,BLKSIZE=132)

Enter the PAGENT environment variables. The pagentdataset data set contains the PAGENT environment variables.

For example:
```
LIBPATH=/lib:/usr/lib:/usr/lpp/ldapclient/lib:.
PAGENT_CONFIG_FILE=/etc/pagent.conf
PAGENT_LOG_FILE=/tmp/pagent.log
PAGENT_LOG_FILE_CONTROL=3000,2
_BPXK_SETIBMOPT_TRANSPORT=TCPIP
TZ=MST7MDT
```
In this example, /etc/pagent.conf contains the PAGENT configuration parameters. Use your own time zone for the TZ parameter.

Configure PAGENT.

For example:

TTLSRule TBI-TO-ZOS
{
 LocalAddr localtcpipaddress
 RemoteAddr remotetcpipaddress
 LocalPortRange localportrange
 RemotePortRange remoteportrange
 Jobname HTTPserverJobname
 Direction Inbound
 Priority 255
 TTLSGroupActionRef gAct1~TBI_ICSF
 TTLSEnvironmentActionRef eAct1~TBI_ICSF
 TTLSConnectionActionRef cAct1~TBI_ICSF
}
TTLSGroupAction gAct1~TBI_ICSF
{
 TTLSEnabled On
 Trace 2
}
TTLSEnvironmentAction eAct1~TBI_ICSF
{
 HandshakeRole Server
 EnvironmentUserInstance 0
 TTLSKeyringParmsRef keyR~ZOS
}
TTLSConnectionAction cAct1~TBI_ICSF
{
 HandshakeRole ServerWithClientAuth
 TTLSCipherParmsRef cipher1~AT-TLS__Gold
 TTLSConnectionAdvancedParmsRef cAdv1~TBI_ICSF
 CtraceClearText Off
 Trace 2
}
TTLSConnectionAdvancedParms cAdv1~TBI_ICSF
{
 ApplicationControlled Off
 HandshakeTimeout 10
 ResetCipherTimer 0
 CertificateLabel certificatelabel
 SecondaryMap Off
}
TTLSKeyringParms keyR~ZOS
{
 Keyring keyringname
}
TTLSCipherParms cipher1~AT-TLS__Gold
{
 V3CipherSuites TLS_RSA_WITH_3DES_EDE_CBC_SHA
 V3CipherSuites TLS_RSA_WITH_AES_128_CBC_SHA
}

where:

localtcpipaddress: Local TCP/IP address for the HTTP server
remotetcpipaddress: Remote TCP/IP address for the STA client. This can be ALL for all TCP/IP addresses
localportrange: Local port of HTTP server (specified in the HTTP or SMC startup)
remoteportrange: Remote port range (1024-65535 for all ephemeral ports)
HTTPserverJobname: Jobname of the HTTP Server
certificatelabel: Label from the certificate definition
keyringname: Name from the RACF keyring definition

Activate RACF Classes. Either the RACF panels or the CLI can be used.

The RACF classes include:

DIGTCERT
DIGTNMAP

DIGTRING

SERVAUTH class must be RACLISTed to prevent PORTMAP and RXSERV from abending.

SETROPTS RACLIST(SERVAUTH)
RDEFINE SERVAUTH **UACC(ALTER) OWNER (RACFADM)
RDEFINE STARTED PAGENT*.* OWNER(RACFADM) STDATA(USER(TCPIP) GROUP(STCGROUP)
RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE) OWNER(RACFADM)
RDEFINE FACLITY IRR.DIGTCERT.LIST UACC(NONE) OWNER(RACFADM)
RDEFINE FACILITY IRR.DIGTCERT.GENCERT UACC(NONE) OWNER (RACFADM)

Define RACF Keyrings and Certificates
1. Enter the following RACF commands to create Keyrings and certificates:
```
RACDCERT ID(stcuser) ADDRING(keyringname)
```
  where:
  - stcuser: RACF user id associated with the TCPIP address space
  - keyringname: Name of the keyring, must match the Keyring specified in the PAGENT configuration
```
RACDCERT ID(stcuser) GENCERT CERTAUTH SUBJECTSDN(CN('serverdomainname') O('companyname') OU('unitname') C('country')) WITHLABEL('calabel') TRUST SIZE(1024) KEYUSAGE(HANDSHAKE,DATAENCRYPT,CERTSIGN)
```
  Note:
  This is the CA certificate for the STA system.
  
  where:
  - stcuser: RACF user id associated with the TCPIP address space
  - serverdomainname: Domain name of the z/OS server (for example, MVSA.COMPANY.COM)
  - companyname: Organization name
  - unitname: Organizational unit name
  - country: Country
  - calabel: Label for certificate authority (for example, CATBISERVER)
```
RACDCERT ID(stcuser) GENCERT SUBJECTSDN(CN('serverdomainname') O('companyname') OU('unitname') C('country')) WITHLABEL('serverlabel') TRUST SIZE(1024) SIGNWITH(CERTAUTH LABEL('calabel'))
```
  Note:
  This is the SERVER certificate.
  
  where:
  - stcuser: RACF user id associated with the TCPIP address space
  - serverdomainname: Domain name of the z/OS server (for example, MVSA.COMPANY.COM)
  - companyname: Organization name
  - unitname: Organizational unit name
  - country: Country
  - serverlabel: Label for the server certificate (for example, TBISERVER)
  - calabel: Label for certificate authority, specified in the CA certificate definition
```
RACDCERT ID(stcuser) GENCERT SUBJECTSDN(CN('clientdomainname') O('companyname') OU('unitname') C('country')) WITHLABEL('clientlabel') TRUST SIZE(1024) SIGNWITH(CERTAUTH LABEL('calabel'))
```
  Note:
  This is the CLIENT certificate.
  
  where:
  - stcuser: RACF user id associated with the TCPIP address space
  - clientdomainname: Domain name of the STA client (for example, TBIA.COMPANY.COM)
  - companyname: Organization name
  - unitname: Organizational unit name
  - country: Country
  - clientlabel: Label for the server certificate –TBICLIENT
  - calabel: Label for certificate authority, specified in the CA certificate definition.
2. Connect the CA, SERVER, and CLIENT certificates to the keyring specified in the PAGENT configuration:
```
RACDCERT ID(stcuser) CONNECT(CERTAUTH LABEL('calabel') RING('keyringname') USAGE(CERTAUTH))
```
  where:
  - stcuser: RACF user id associated with the TCPIP address space
  - calabel: Label for certificate authority, specified in the CA certificate definition
  - keyringname: Name of the keyring, must match the Keyring specified in the PAGENT configuration
```
RACDCERT ID(stcuser) CONNECT(ID(stcuser) LABEL('serverlabel') RING('keyingname') DEFAULT USEAGE(PERSONAL)
```
  where:
  - stcuser: RACF user id associated with the TCPIP address space
  - serverlabel: Label for the server certificate
  - keyringname: Name of keyring, must match the Keyring specified in the PAGENT configuration
```
RACDCERT ID(stcuser) CONNECT(ID(stcuser) LABEL('clientlabel') RING('keyingname') USEAGE(PERSONAL)
```
  where:
  - stcuser: RACF user id associated with the TCPIP address space
  - clientlabel: Label for the client certificate
  - keyringname: Name of keyring, must match the Keyring specified in the PAGENT configuration
3. Export the CA and client certificates to be transmitted to STA:
```
RACDCERT EXPORT (LABEL('calabel')) CERTAUTH DSN('datasetname') FORMAT(CERTB64)
```
  where:
  - calabel: Label for certificate authority, specified in the CA certificate definition
  - datasetname: Data set to receive the exported certificate
```
RACDCERT EXPORT (LABEL('clientlabel')) ID(stcuser) DSN('datasetname') FORMAT(PKCS12DER) PASSWORD(' password ')
```
  where:
  - clientlabel: Label for the client certificate
  - stcuser: RACF user id associated with the TCPIP address space
  - datasetname: Data set to receive the exported certificate
  - password: Password for data encryption. Needed when the certificate is received on STA. The password must be eight characters or more.

The export data sets are now transmitted to STA, and FTP can be used. The CA certificate is transmitted with an EBCDIC to ASCII conversion. The CLIENT certificate is transmitted as a BINARY file and contains both the client certificate and its private key.

Task 4: Create the RACF Profiles Used by the CGI Routine

The profiles are defined in the FACILITY class. The first of the profiles is called SMC.ACCESS.STA and determines whether a user has access to the STA application.

A user who requires access to STA must have READ access to this profile. The other profiles are all shown as SMC.ROLE.nnn and are used to determine which roles the user has once logged on.

Note:

The only role defined to STA is StorageTapeAnalyticsUser. To obtain this role, you must request your user ID to be added to the SMC.ROLE.STORAGETAPEANALYTICSUSER profile with READ access.

Task 5: Import the Certificate File and Private Key File (optional)

Use this procedure to verify that public and private keys have been generated successfully and that user IDs and passwords with the appropriate permissions have been defined correctly.

The test can be done using any browser, but Firefox is used here as an example.

In the Firefox Tools menu, select Options.
Select the Advanced tab, and then select the Encryption tab.
Click View Certificates.
In the Certificate Manager dialog box, select the Authorities tab, and then select the certificate file to import.
Click Import.
Select the Your Certificates tab, and then enter the private key file to import.
Click Import.
Click OK to save and exit the dialog box.

Task 6: Test the CGI Routine

Use this procedure to test the CGI routine from a browser.

Open a browser window, and enter the following URL, where host, port, userid, and password are set to appropriate values.
```
https://host:port/smcgsaf?type=authentication&userid=userid&password=password&roles=StorageTapeAnalyticsUser
```
The resulting output indicates whether or not the user is authorized to access STA and the StorageTapeAnalyticsUser role.

Note:
The STA RACF authorization facility does not support changing the password of mainframe user IDs. If a user ID password expires, STA indicates this, and the password must be reset through normal mainframe channels before attempting to log in to STA again.

Task 7: Set Up RACF/SSP for the WebLogic Console

The RACF Security Service Provider (or RACF SSP) must be installed as a WebLogic plug-in. If the RACF SSP has been installed, the STA installer should put the RACF SSP in the appropriate location within WebLogic.

Use this procedure to place the RACF SSP in the proper location, if it has not been already.

Place the RACF security jar file into the following directory:

/Oracle_storage_home/Middleware/wlserver_10.3/server/lib/mbeantypes/staRACF.jar

where Oracle_storage_home is the Oracle storage home location specified during STA installation.

Task 8: Configure SSL Between STA and RACF

Use this procedure to install the MVS security certificate on the STA server and import it into the system-wide Java keystore.

Verify that the required PTFs have been installed on the MVS system. These PTFs allow for authentication with RACF or other third-party security software when you log in to the STA application. See "Task 1: Review IBM RACF Mainframe Minimum Requirements" for details.
Obtain the following files:
- MVS server certificate, in ASCII format
- STA client private key, in binary PKCS12 format; the MVS system administrator should give you the password to this file.
Transfer the files to the STA server, and place them in the certificates directory. The directory location is as follows:

/Oracle_storage_home/Middleware/user_projects/domains/TBI/cert

where Oracle_storage_home is the Oracle storage home location specified during STA installation.
Convert the certificate from Distinguished Encoding Rules (DER) format to Privacy Enhanced Mail (PEM) format. For example:
```
# openssl pkcs12 -clcerts -in PKCS12DR.xxxxxx -out mycert.pem
```
Where:
- pkcs12 indicates PKCS#12 data management.
- -clcerts indicates you want to output client certifications only.
- -in specifies the input file.
- -out specifies the output file.
You will be asked to enter the import password (given to you with the certificate), a new PEM password, and password verification.
Change to the JRE binary directory. The directory location is as follows:

/Oracle_storage_home/StorageTek_Tape_Analytics/jdk/jre/bin

where Oracle_storage_home is the Oracle storage home location specified during STA installation.

For example:
```
# cd /Oracle/StorageTek_Tape-Analytics/jdk/jre/bin
```
Use the Java keytool utility to import the certificate file into the system-wide Java keystore. The keystore is located in the following file:

/Oracle_storage_home/StorageTek_Tape_Analytics/jdk1.6.0_xx/jre/lib/security/cacerts

For example:
```
# ./keytool -importcert -alias tbiServer -file mycert.pem -keystore /Oracle/StorageTek_Tape_Analytics/jdk1.6.0_75/jre/lib/security/cacerts -storetype jks
```
Where:
- -importcert indicates you want to import a certificate.
- -alias indicates the name you want to assign to the entry in the keystore.
- -file indicates the name of the certificate file you want to import.
- -keystore indicates the location of the system-wide Java keystore.
- -storetype indicates the type of keystore.

Task 9: Configure the WebLogic Server

To configure WebLogic for RACF authentication, use the procedure in "Reconfigure WebLogic to use a Different Security Certificate."

Task 10: Install RACF/SSP on the WebLogic Console

Go to the WebLogic console login screen using the HTTP (STA 2.1.x default is 7019) or HTTPS (STA 2.1.x default is 7020) port number you selected during STA installation.
```
https://yourHostName:PortNumber/console/
```
For example:
```
https://sta_server:7020/console/
```
Log in using the WebLogic administration console username and password you defined during STA installation.
In the Domain Structure section, select Security Realms.

Description of the illustration ''wl_secrealm.png''
In the Realms section, select the myrealm active link (select the name itself, not the check box).

Description of the illustration ''wl_myrealm.png''
In the Change Center section, click Lock & Edit.

Description of the illustration ''wl_lockedit.png''
Select the Providers tab.

Description of the illustration ''wl_providers.png''
In the Authentication Providers section, click New.

Description of the illustration ''wl_new.png''
Enter the name of the authentication provider you want to add (for example, STA RacfAuthenticator), and select RacfAuthenticator in the Type menu. Click OK.

Note:
The RACF jar file should be listed in the Type menu. If it is not, stop and restart STA using the STA command. See the STA Administration Guide for command usage details.
Verify the RACF provider is included in the Authentication Providers table. The DefaultAuthenticator and DefaultIdentityAsserter must always be the first two providers in this list.
Select the DefaultAuthenticator active link (select the name itself, not the check box).

Description of the illustration ''racf_defauth.png''
In the Control Flag menu, select Sufficient, and then click Save.
Click the Provider Specific tab, and then click Save.

Description of the illustration ''racf_defprovspec.png''
Click the Providers locator link to return to the Authentication Providers screen.

Description of the illustration ''ssp_provlink.png''
In the Authentication Providers table, select the RACF authenticator name you created in Step 8 (select the name itself, not the check box).

Description of the illustration ''racf_selracf.png''
In the Control Flag menu, select Sufficient, and then click Save.

Description of the illustration ''racf_racfauthsufficient.png''
Click the Provider Specific tab.

Description of the illustration ''racf_provspecific.png''
Enter the Host name (for example, mvshost.yourcompany.com) and Port number (for example, 8700) where the MVS system is running, and then click Save.

Description of the illustration ''racf_racfauthhostport.png''
In the Change Center section, click Activate Changes.

Description of the illustration ''wl_activate.png''
Log out of the WebLogic Administration console.
Stop and restart STA using the STA command. See the STA Administration Guide for command usage details.
```
# STA stop all
# STA start all
```