This chapter explains the Oracle Communications Services Gatekeeper system administration security issues.
This chapter explains security issues that affect Services Gatekeeper system administrators, including these sections:
Also see Services Gatekeeper Security Guide for additional information on security, including these sections:
One of the first things you must do while setting up your Services Gatekeeper implementation is decide how to protect your web service communication and OAM MBeans.
For more information about Services Gatekeeper security and how these tasks help create a secure Services Gatekeeper implementation, see Services Gatekeeper Security Guide.
Web service security controls the network traffic between Services Gatekeeper and applications and network nodes it communicates with. By default, Services Gatekeeper is configured to send credentials in clear text for inbound traffic only. Outbound security is not enabled because there is no way for Services Gatekeeper to know what security policies may be required by a client. Set up that level of security at the earliest after you find out what your clients require.
Oracle recommends that for production implementations you fully secure web services using the instruction in one of these sections, depending on the web interface you use:
Secure client (outbound) traffic and require digest authentication (encrypted credentials) for all traffic. Applying a security policy (WS-Security) to a web service establishes both inbound and outbound security policies. To secure the link by which Services Gatekeeper returns notifications, use Secure Sockets Layer (SSL).
MBean security controls who is authorized to modify the runtime MBean Server within your WebLogic Server installation. This server allows OAM procedures to be performed.
Oracle recommends that you secure the OAM MBeans using the instructions in "Securing the Oracle Access Manager MBeans".
Services Gatekeeper provides a set of firewall settings to protect against denial of service (DOS) attacks from malicious or malformed REST or SOAP messages. For details see ”Security Considerations for Developers” in Services Gatekeeper Security Guide.
Some communication services use tunneled parameters to send information to Services Gatekeeper, which can present a security vulnerability. You can use an interceptor to filter tunneled parameters to control this vulnerability and limit which xparameters can be set by inbound messages.
Filtering blocks requests that contain xparameters that are not specifically configured as allowed. This filtering applies to all of Services Gatekeeper, not just individual applications.
For general information about xparameters and filtering, see the discussion on using parameter tunneling in the Services Gatekeeper Extension Developer's Guide.
This section explains the behavior and configuration of the tunneled parameters filtering application.
When enabled, the interceptor_xparam application filters inbound messages for tunneled xparameters in inbound messages. Messages containing xparameters not explicitly allowed in the application's configuration file are rejected. Specifying a list of allowable xparameters enables tighter security in your Services Gatekeeper implementation. Filtering is on a global, not application, level.
The interceptor_xparam application is installed with Services Gatekeeper and is deployed as a standalone EAR file named xparam_interceptors.ear. It is implemented by the x-param-filter-interceptor interceptor.
To turn the application on, configure the customized interceptor chain and enable interceptor_xparam. You must configure the xparameters that you want to allow as described in "XParameter Filter Configuration File"; otherwise all requests that contain xparameters are rejected. If the application is active when Services Gatekeeper starts up, the application reads a configuration file that lists the allowed xparameters. If the list of allowed xparameters changes, you must update the configuration file and redeploy the filtering application. You can disable all tunneled parameters filtering by stopping or undeploying the EAR file and removing the interceptor from your interceptor chain.
The xparameter filter configuration file, xparam_filter_config.xml, is located in the xparam_interceptors.ear in the APP-INF/classes directory. The schema file, xparam_filter_config.xsd, is also available in this directory.
To allow an xparameter in a request, list its key as an <xParamKey>
sub element within the <allowedXParams>
element in xparam_filter_config.xml. For example:
<allowedXParams> <xParamKey>sms.protocol.id</xParamKey> <xParamK>sms.service.type<xParamKey> . . . </allowedXParams>
The xparameter keys are listed by communication service in the sections on tunneled parameters in the chapters in the Services Gatekeeper Communication Service Reference Guide. Some communication services do not support any xparameters.
If an xparameter is not configured in xparam_filter_config.xml, a SOAP request that passes the xparameter is rejected.
The following is an example of a rejection response to a request that passed the xparameter called dest_addr_subunit
:
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"> <env:Header/> <env:Body> <env:Fault> <faultcode>env:Server</faultcode> <faultstring/> <detail> <v2:ServiceException xmlns:v2="http://www.csapi.org/schema/parlayx/common/v2_1"> <messageId>SVC0001</messageId> <text>A service error occurred. Error code is %1</text> <variables>Error validating the request, xparam: dest_addr_subunit in the request data is not allowed.</variables> </v2:ServiceException> </detail> </env:Fault> </env:Body> </env:Envelope>
See "Internal XParameters" for information about exceptions for xparameters that are not rejected.
It is possible for custom interceptors to insert xparameters on behalf of an application. To prevent these internal xparameters from being rejected by the filter, ensure that any custom interceptor that adds xparameters is executed after the x-param-filter-interceptor in the interceptor chain.
Xparameters added to a request through the <contextAttribute>
of an SLA are not rejected because the InjectValuesInRequestContextFromSLA interceptor executes after x-param-filter-interceptor.
See "Using Service Interceptors to Manipulate Requests" in the Services Gatekeeper Extension Developer's Guide for information about the order of execution of custom interceptors.
SOAP-based security provides end-to-end message-level security for web services through an implementation of the WS-Security standard.
WS-Security defines a mechanism that offers three levels of security to SOAP messages:
Authentication tokens (username token). The digest authentication version of authentication tokens is the default SOAP-based communication security setting. WS-Security authentication tokens let an application provide a user name and password or X.509 certificate for the purpose of authentication headers. With additional setup, Security Assertion Markup Language (SAML) can also be used for authentication.
SOAP-based communication with the Partner Relationship Manager uses this security by default. However you must configure other web services to use this strategy. See "Setting up UsernameToken with Password Digest" for instructions.
XML encryption (SAML tokens). WS-Security's use of W3C's XML encryption standard enables the XML body or portion of it to be encrypted to ensure message confidentiality.
To set up SAML token security, configure the WebLogic SAML Identity Assertion Provider, which authenticates users based on SAML assertions and SAML credential mapping provider. The SAML Identity Assertion Provider is required only if you are using SAML assertions. See ”Using Security Assertion Markup Language (SAML) Tokens For Identity” in Oracle WebLogic Server Securing WebLogic Web Services for Oracle WebLogic Server.
XML digital signatures (X.509 certificate tokens). WS-Security's use of W3C's XML digital signatures lets the message be digitally signed to ensure message integrity. The signature is based on the content of the message itself (by applying the hash function and public key). If the message is altered en route, the signature becomes invalid. See "Setting up UsernameToken with X.509" for instructions.
Services Gatekeeper uses a WebLogic Server mechanism for web services Security - WSSE (Web Services Security Environment) policies:
”Oracle Web Services Security” in Oracle WebLogic Server Developing Applications with Oracle Security Developer Tools.
”Oracle WSM Policy Framework” in Oracle WebLogic Server Developing Applications with Oracle ADF Data Controls.
"References" (specification references) in Oracle WebLogic Server Developing Applications with Oracle Security Developer Tools.
Authentication is handled transparently by WS-Security and subsequently by the configured authentication providers and login modules of the WebLogic Security framework. WS-Security also supports signing and encrypting a message by providing a security token hierarchy associated with the keys used for signing and encryption (for message integrity and confidentiality).
To apply a WSSE policy of the type UsernameToken with Password Digest to a web service endpoint in Services Gatekeeper from the Administration Console:
Start the Administration Console.
Enable digest authentication:
Click Providers.
Click Authentication.
Select the WLNG Application Identity Asserter check box.
Click the WLNG Application Identity Asserter link.
The Settings for WLNG Application Identity Asserter window appears.
Under Active Types: move wssePasswordDigest from Available: to Chosen: using the left arrow icon.
Click Save.
Create a custom ws-policy.xml
file for the password digest. See Example 5-1 for an example.
For every web service:
Put a copy of the custom ws-policy.xml
file in the WEB-INF/policies
directory of the WAR file for the web service.
Edit the WEB-INF/policies/weblogic-webservices-policy.xml
file replacing the old wsl-policy file with policy:UsernameTokenDigestPolicy.xml
.
Repackage and redeploy these files.
Edit the deployment plan, plan.xml
, to indicate inbound only for entry WsPolicy_policy: UsernameTokenDigestPolicy.xml
in plan.xml
.
Example 5-1 Username Token with digest custom policy example (UsernameTokenDigestPolicy.xml)
<?xml version="1.0"?> <!-- WS-SecurityPolicy --> <wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:wssp="http://www.bea.com/wls90/security/policy" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wls="http://www.bea.com/wls90/security/policy/wsee#part" > <!-- Identity Assertion --> <wssp:Identity> <wssp:SupportedTokens> <!-- Use UsernameToken for authentication --> <wssp:SecurityToken IncludeInMessage="true" TokenType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#UsernameToken"> <wssp:UsePassword Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest"/> </wssp:SecurityToken> </wssp:SupportedTokens> </wssp:Identity> </wsp:Policy>
This section outlines how to set up WSSE with X.509, configure the default identity asserter, and configure the keystore.
To set up UsernameToken with X.509 from the Administration Console:
Select Security Realms from the Domain Structure menu for the domain you want to configure.
Select myrealm.
The settings for myrealm appear.
Click the Providers tab.
The list of authentication providers appears.
Click the DefaultIdentityAsserter provider in the table.
The settings for DefaultIdentityAsserter appear.
Click the Common tab.
Under Active types, move X.509
from the Available list to the Chosen list if it is not there already.
Click the Provider Specific tab.
Set the Default User Name Mapper Attribute Type is to CN
if it is not set to CN
already.
To configure the keystore:
Select Environment from the Domain Structure menu.
A summary of the environment appears.
Select Servers.
A summary of servers appears.
Click AdminServer.
The settings for the AdminServer appear.
Click the Keystores tab. The keystore settings appear.
Configure the Identity and Trust sections of the keystore form. See ”Configuring Identity and Trust” in Oracle WebLogic Server Administering Security for Oracle WebLogic Server for information about setting the keystore values.
Click Save to save your configuration.
To turn off outbound security associated with a particular WS-Policy file, you must edit the plan.xml file that is created when you attach Policy to a web service, as in step 8 above. The default location is: /domain_home/wlng-access-network-domain/servers/AT1/stage/wlng_at/plan/Plan.xml, but your location may be different. Make sure the value element is set to inbound
as in the following example:
<variable> <name>WsPolicy_policy:Auth.xml_Direction_11745107731400</name> <value>inbound</value> </variable>
Services Gatekeeper 2.2 and earlier use a different mode of authentication than the WS-Security model. Services Gatekeeper can be configured to support applications designed to work using the older model, but the WS-Policy that is configured by default must be removed.
Note:
The easiest way to do this is to make these changes before you start Services Gatekeeper for the first time. Certain configuration values are cached on start up.For example, if you started Services Gatekeeper during the post-install phase to set up additional JMS Servers, you must redeploy the wlng_at.ear
file after you have made your changes.
To remove the policy files from a web service:
Expand the EAR file for the access tier part of the communication service.
Expand the war file for the web service in question.
Modify the weblogic-webservices-policy.xml file for that web service to remove the policy entries.
Example 5-2 shows the weblogic-webservices-policy.xml
file for a web service with policy entries.
Example 5-2 weblogic-webservices-policy.xml with policy entries
<?xml version='1.0' encoding='UTF-8'?> <webservice-policy-ref xmlns="http://www.bea.com/ns/weblogic/90" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <port-policy> <port-name>AudioCall</port-name> <ws-policy> <uri>policy:Auth.xml</uri> <direction>inbound</direction> </ws-policy> </port-policy> </webservice-policy-ref>
Example 5-3 shows the same file for that web service after the policy entries were removed.
Re-package the war file with the modified weblogic-webservices-policy.xml
file
Re-package the ear file.
Copy the modified ear file to the domain directory of the administration server.
If you have previously run Services Gatekeeper, you should now re-deploy the EAR file using the Administration Console.
For information about creating and using a custom policy file for message-level security, see "Creating the Web Service Reliable Messaging WS-Policy File" in Oracle WebLogic Server Developing JAX-WS Web Services for Web Services here:
http://www.oracle.com/pls/topic/lookup?ctx=wsc70&id=WSGET290
Also see the Oracle WebLogic Server Administration Console Online Help.
WS-Policy files can be used to require applications clients to authenticate, digitally encrypt, or digitally sign SOAP messages. By default, Services Gatekeeper supplies these policy files: auth.xml, encrypt.xml, sign.xml, and UsernameTokenDigestPolicy.xml. If the built-in WS-Policy files do not meet your security needs, you can build custom policies.
WS-Policy assertions are used to specify a web service requirement for digital signatures and encryption, along with the security algorithms and authentication mechanisms that it requires; for example, Policy for SAML.
Services Gatekeeper supports using SAML tokens to pass authentication and authorization between REST-based applications. The most common use for SAML is creating single sign-on (SSO) logins. Services Gatekeeper supports allowing users to provide credentials once, and then obtain access to a group of related REST-based applications. This streamlines the user experience by allowing them to enter credentials once and then access multiple applications.
Services Gatekeeper allows the use of SAML tokens among REST-based applications that interact with the access tier. It is not supported by the Partner and API Management Portal.
See "Supported SAML Specification" in Statement of Compliance for the SAML specification that this release of Services Gatekeeper supports.
Services Gatekeeper uses SSL authentication to secure REST-based Web services. You have the options listed in Table 5-1 for security levels.
Table 5-1 SSL Security Options
SSL Level | Client Response Setting | Notes |
---|---|---|
One-Way |
Client certificates not required |
Essentially no security. Only use in a test and evaluation implementation. |
Two-Way |
Client certificates requested but not enforced. |
The default setting. Appropriate for a test and evaluation system. A client certificate is requested but if one is not returned, the session continues normally. |
Two-Way |
Client certificates requested and enforced. |
The most secure setting; appropriate for most production implementations. A client certificate is requested and if one is not returned the session is terminated. |
Table 5-2 lists the default keystore and truststore name and locations. If you are configuring a test and evaluation implementation it is acceptable to use these values. If you are configuring a production implementation, replace these values with settings that you create.
Table 5-2 Default SSL Truststore and Keystore Values
Default Credential | Default Value |
---|---|
Demo identity keystore location |
Oracle_home/Middleware/wlserver_10.3/server/lib/DemoIdentity.jks |
Demo identity keystore password |
DemoIdentityKeyStorePassPhrase |
Demo identity keystore (private key) password |
DemoIdentityKeyStorePassPhrase |
Default trust keystore location |
Oracle_home/Middleware/wlserver_10.3/server/lib/DemoTrust.jks |
Default trust keystore password |
DemoTrustKeyStorePassPhrase |
Follow the instructions in the following sections to set up and configure SSL security for RESTful communication between Services Gatekeeper and external applications:
Enabling and Configuring SSL for Each Application Tier Server
Adding Certificates to the Application Tier Servers and Applications
To enable SSL, perform these steps on each of your application tiers that use RESTful communication:
Open the WebLogic Server Administration Console.
Click Lock and Edit.
Navigate to Environment, then Servers, then AT_server_name, then the Configuration tab, then the General subtab.
Check the SSL Listen Port Enabled check box.
Set the SSL Listen Port: number to 7002.
Navigate to the Keystores subtab.
If you are setting up a production environment, change these settings to values that you create. Use the default values (listed in Table 5-2) for test and evaluation implementations:
Keystores: Click Change.
Demo Identity Keystore: Change this to different location that you have created.
Demo Identity Keystore Passphrase: Change this to a secure password that you create.
Demo Trust Keystore: Change this to a location that you have created.
Demo Trust KeyStore Passphrase: Change this to a secure password that you create.
Navigate to the SSL tab.
If you are setting up a production environment, change these settings to values that you create. Use the default values (listed in Table 5-2) for test and evaluation implementations:
Identity and Trust Location: Click Change.
Private key Passphrase: Change this to a secure password that you choose.
Two Way Client Cert Behavior: See Table 5-1 for the possible values. Select the value appropriate for your implementation.
Click Release Configuration.
Once you have configured SSL and key- and truststores for each application-facing server, you must create a file of trust certificates to import into the client keystore and truststore locations.
To do so:
Open a shell on the Services Gatekeeper server.
Change the directory to the location of your trust store. You set this with the directions in "Enabling and Configuring SSL for Each Application Tier Server". The default directory is Oracle_home/Middleware/wlserver/server/lib.
(Optional) List the credentials to confirm that they are correct with the following command. The default values for keystore_name and:
keytool -list -v -storetype JKS -keystore keystore_name.jks -storepass keystore_password
Export the certificates from the Services Gatekeeper keystore into a file with this command:
keytool -exportcert -v -storetype JKS -keystore keystore_file.jks -storepass keystore_password -alias nt1-cacert -rfc -file SG_trust_cacert_file.cer
Where:
keystore_file.jks is the Services Gatekeeper keystore file you set in the "Enabling and Configuring SSL for Each Application Tier Server" section.
keystore_password is the keystore password you created in the "Enabling and Configuring SSL for Each Application Tier Server" section.
SG_trust_cacert_file.cer is the Services Gatekeeper truststore certificate file.
This command exports the keystores into a file called export_file.cer that you use to import certificates into the Services Gatekeeper trust store.
Import SG_trust_cacert_file.cer into the client application's keystore. See your application product documentation for details.
Note:
Do this for each server communicating with Services Gatekeeper.Obtain your client application's truststore certificate file. See your client application or client server documentation for details. You need the truststore certificate file with the .cer file extension.
Change the directory to the location of your keystore. You set this with in the "Enabling and Configuring SSL for Each Application Tier Server" section. The default directory is Oracle_home/Middleware/wlserver_release_level/server/lib
Import your client application's certificates into the Service Gatekeeper truststore with this command:
keytool -importcert -v -alias client-cacert -file client_cacert_file.cer -storetype JKS -keystore truststore_file.jks -storepass truststore_password
Where:
client_cacert_file.cer is the client truststore certificates file.
truststore_file.jks is the Services Gatekeeper truststore file you set in the "Enabling and Configuring SSL for Each Application Tier Server" section.
truststore_password is the truststore password you created in the "Enabling and Configuring SSL for Each Application Tier Server" section.
To secure RESTful Web service traffic with network-facing servers, you must:
Import the network node server certificates into Services Gatekeeper keystore as trusted entries,
Export your Services Gatekeeper keystores into the network node server.
To secure RESTful traffic, you must first know the location of the network server certificate file (keystore_cacert_file.cer) that you created in the "Adding Certificates to the Application Tier Servers and Applications" section.
To secure network-facing traffic:
Open a shell on the Services Gatekeeper server.
Change directory to the location of your Services Gatekeeper keystore. You set this in the "Enabling and Configuring SSL for Each Application Tier Server" section. The default directory is Oracle_home/Middleware/wlserver/server/lib.
To import the network server keystore credentials, generate a public/private key pair, and create a keystore file, use this command:
keytool -genkeypair -v -alias key_pair -keyalg RSA -storetype JKS -validity 3650 -keystore keystore_file.jks -dname "domain_name" -storepass public_key_password -keypass private_key_password
Where:
key_pair is the name of the public/private key pair.
public_key_password is the public key for the public/private key pair.
keystore_file.jks is the Services Gatekeeper Java keystore file accepting the keystore credentials that is created with this command.
domain_name is the distinguished name of the network node credential key, for example: ”CN=oracle-wac-gw-nt1,OU=CGBU,O=Oracle,L=ANY,C=US”.
private_key_password is the private key of the public/private key pair.
To import the Services Gatekeeper keystore credentials into the network node server, use this command:
keytool -exportcert -v -alias key_pair -keystore keystore_file.jks -storetype JKS -storepass public_key_password -rfc -file cacert_file.cer
Where:
key_pair is the name of the public/private key pair.
keystore_file.jks is the Services Gatekeeper keystore file to import.
public_key_password is the public key password for the certificates.
cacert_file.cer is the certificate file that is created by this command.
Start the Administration Console (or another MBean browser) and navigate to the MBeans tab.
Click Lock and Edit.
Check the Display: tree check box.
Navigate to wlng, then RESTfulClientSSL.
Edit these fields to direct Services Gatekeeper to use the keystores you have imported:
Click Save.
Click Activate Changes.
The Java Management Extension (JMX) OAM MBeans control access to the Services Gatekeeper OAM functionality. You can change these MBean settings using the Administration Console or through an external mechanism. Access to these MBeans are controlled by JMX Policy, which associates administrative user groups with access privilege levels. By default any administrative user can access and change the Services Gatekeeper OAM MBeans. You may want use the instructions in this section to add more restrictive access control to prevent inadvertent or malicious changes to these MBeans. However, the decision should be based on your implementation's security policies.
Administrative users and groups are set up as described in the "Managing Users and User Groups" section. To control how these users have access to MBeans, and thus OAM functionality, you must assign JMX Policy to these user groups. You use WebLogic Server Administration Console to do this. For details see the discussion on managing security policies in Oracle WebLogic Server Administration Console Online Help at:
https://docs.oracle.com/cd/E24329_01/apirefs.1211/e24401/taskhelp/security/ManageSecurityPolicies.html
Each policy can do the following:
Control read access for all an MBean's attributes or for specific attributes that you select.
Control write access for all an MBean's attributes or for specific attributes that you select.
Control invoke access for all an MBean's operations or for specific operations that you select.
For example, to give a user complete access to an MBean, select the WLNG_Administrator's Group in the policy condition.
In addition to controlling access to OAM functionality in a general way – ReadOnly, ReadWrite, and so on – you may also want to control access by Service group. So, for example, if you have users whose job is limited to setting up and managing Application Service Providers through a system using the Partner Relationship Management interfaces, you might want to give them, and only them, ReadWrite privileges, but only to a subset of the available MBeans, those having to do with the operator part of those transactions. To do this, you have to create custom XACML policies to attach to these subsets. Services Gatekeeper uses the standard WebLogic Server mechanisms for this purpose. For the basic process you must:
Determine the special identifier (called the resourceId) for each MBean.
Create an XACML policy for a security role.
Specify one or more Rule elements that define which users, groups, or roles belong to the new security role.
Attach this role to the MBean by way of the resourceId.
For details on using XACML documents to secure WebLogic resources, see "Using XACML Documents to Secure WebLogic Resources" in Oracle WebLogic Server Securing Resources Using Roles and Policies for Oracle WebLogic Server.
For a reference for XACML on WebLogic Server, see ”Reference for XACML on WebLogic Server” in Oracle WebLogic Server Securing Resources Using Roles and Policies for Oracle WebLogic Server.