This chapter explains how to implement security for the communication services that Services Gatekeeper hosts.
Web service security controls the network traffic between Services Gatekeeper and applications or web users, and network nodes it communicates with. Use the instructions in this chapter in conjunction with these sections in "Securing Network Traffic":
"Configuring Network Traffic Security with ApiFirewallMBean"
"Implementing Denial-of-Service Attack Protection with ApiFirewall"
This chapter adds additional information specific to securing network traffic for use with Services Gatekeeper communication services.
By default, Services Gatekeeper communications services are 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 as soon as you find out what your clients require. See "Security Considerations for All Communication Services" for more information.
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).
Communication services do not have security enabled by default because Services Gatekeeper has no way of knowing what kind of security they allow. Ensure that you add or configure communication service security features before allowing subscribers to use them.
Communication services generally require both authentication and authorization services to remain secure. You can provide this security by:
Using a WebLogic security provider to authenticate subscribers by verifying their application IDs and credentials.
Using Services Gatekeeper service-level agreements (SLAs) provide authorization. You secure communication services by authorizing service requests with SLAs, and by authenticating users making the requests with web services security. This is true for services created by you or your partners. SLAs can define the API and TPS that the application can use. Including:
Using OAuth to provide both authorization and SSO authentication for third-party resources. See "Authenticating and Authorizing Resources with OAuth" for more information.
You can use Security Assertion Markup Language (SAML) credentials to gain access to resources protected by OAuth 2.0 in Services Gatekeeper. This enables you to create single sign on (SSO) features that provide your subscribers with one authorized SAML token (federated identity) for use in accessing multiple third-party resources. See ”Support for SAML Assertions” in Services Gatekeeper OAuth Guide.
You create Service Level Agreements (SLAs) to define who is authorized to use communication services. Every communication service must have an SLA that specifies access privileges to Services Gatekeeper and the network nodes it communicates with.
For more information, see Services Gatekeeper Accounts and SLAs Guide.
OAuth provides both authorization and authentication services and replaces more traditional SSO mechanisms. For information about using the OAuth protocol to grant access to resources (such as photos, video, and so on) without compromising the resource owner's security, see:
The first step in protecting your SOAP-based communication is to ensure that all communication with Services Gatekeeper happens within a session. You set this in the Services Gatekeeper Session Manager Web Service, and it automatically requires applications to provide authorization.
For information about creating and securing SOAP-based communication, see these sections in Services Gatekeeper Application Developer's Guide:
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 (Digest Authentication)" 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).
This section assumes that you have installed and started the Services Gatekeeper servers.
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.
In the Domain Structure pane, navigate to Security Realms, the realm_name, and select the Providers, and Authentication tabs.
Click WLNG Application Identity Asserter.
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.
In the Change Center, click Release Configuration.
Create a custom ws-policy.xml file for the password digest. See Example 4-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 4-1 Username Token with Digest Custom Policy (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>
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.
The RESTful service interfaces use HTTP basic authentication and session IDs for security.
For information about:
Implementing HTTP security, see ”Securing Communication Services” in Services Gatekeeper System Administrator's Guide.
Creating and securing RESTful communication services, see ”Using the RESTful Interfaces” in Services Gatekeeper Application Developer's Guide.
Requiring sessions for all RESTful communication, see ”Managing Communication Sessions” in Services Gatekeeper Application Developer's Guide.
Services Gatekeeper uses SSL authentication to secure REST-based Web services. You have the options listed in Table 4-1 for security levels.
Table 4-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 4-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 4-2 Default SSL Truststore and Keystore Values
| Default Credential | Default Value |
|---|---|
|
Demo identity keystore location |
Oracle_home/user_projects/domains/domain_name/security/DemoIdentity.jks |
|
Demo identity keystore password |
DemoIdentityKeyStorePassPhrase |
|
Demo identity keystore (private key) password |
DemoIdentityKeyStorePassPhrase |
|
Default trust keystore location |
Oracle_home/wlserver/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 4-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 4-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 4-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/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/wlserver/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/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.
Services Gatekeeper supports communication services using the MM7, SMPP, and UCP protocols. The following shows security considerations for each protocol:
Native MM7 Communication Services
Services Gatekeeper uses HTTP basic authentication to secure native MM7 communication services. For more information, see ”Native MM7” in Services Gatekeeper Communication Service Reference Guide.
Native SMPP Communication Services
Services Gatekeeper uses authentication credentials to secure native SMPP communication services. For information about creating a native SMPP communications service, see ”Native SMPP” in Services Gatekeeper Communication Service Reference Guide.
Native UCP Communication Services
Services Gatekeeper uses a credential store to secure native UCP communication services. For information about configuring connection information and the credential map, see ”Managing and Configuring Native UCP Connections” in Services Gatekeeper System Administrator's Guide.