Fusion Middleware Documentation
Advanced Search


Understanding Oracle Web Services Manager
Close Window

Table of Contents

Show All | Collapse

3 Understanding Web Service Security Concepts

This chapter describes the concepts behind Web services security. Web services security encompasses a number of requirements, such as authentication, authorization, and message protection.

This chapter contains the following sections:

Note:

A subset of OWSM authentication and authorization policies are supported for RESTful Web services, as described in Which OWSM Policies Are Supported for RESTful Web Services? in Securing Web Services and Managing Policies with Oracle Web Services Manager.

This section primarily describes Web services over SOAP.

3.1 Overview of Web Service Security

Because of its nature (loosely coupled connections) and its use of open access (mainly HTTP), SOA implemented by Web services adds a new set of requirements to the security landscape:

  • Authentication—Verifying that the user is who she claims to be. A user's identity is verified based on the credentials presented by that user, such as:

    1. Something one has, for example, credentials issued by a trusted authority such as a passport (real world) or a smart card (IT world).

    2. Something one knows, for example, a shared secret such as a password.

    3. Something one is, for example, biometric information.

    Using a combination of several types of credentials is referred to as "strong" authentication, for example using an ATM card (something one has) with a PIN or password (something one knows). See "Understanding Authentication" for more information.

  • Authorization (or Access Control)—Granting access to specific resources based on an authenticated user's entitlements. Entitlements are defined by one or several attributes. An attribute is the property or characteristic of a user, for example, if "Marc" is the user, "conference speaker" is the attribute. See "Understanding Authorization" for more information.

  • Confidentiality, privacy—Keeping information secret. Accesses a message, for example a Web service request or an email, as well as the identity of the sending and receiving parties in a confidential manner. Confidentiality and privacy can be achieved by encrypting the content of a message and obfuscating the sending and receiving parties' identities. See "Understanding Message Protection" for more information.

  • Integrity, non repudiation—Making sure that a message remains unaltered during transit by having the sender digitally sign the message. A digital signature is used to validate the signature and provides non-repudiation. The timestamp in the signature prevents anyone from replaying this message after the expiration. For more information, see "Understanding Message Protection".

Web services security requirements also involve credential mediation (exchanging security tokens in a trusted environment), and service capabilities and constraints (defining what a Web service can do, under what circumstances).

In many cases, Web services security tools such as OWSM rely on Public Key Infrastructure (PKI) environments. A PKI uses cryptographic keys (mathematical functions used to encrypt or decrypt data). Keys can be private or public. In an asymmetric cipher model, the receiving party's public key is used to encrypt plaintext, and the receiving party's matching private key is used to decrypt the ciphertext. Also, a private key is used to create a digital signature by signing the message, and the public key is used for verifying the signature. Public-key certificates (or certificates, for short) are used to guarantee the integrity of public keys.

Web services security requirements are supported by industry standards both at the transport level (Secure Socket Layer) and at the application level relying on XML frameworks.

For more information about the specifications and standards supported by Web services, see Appendix A, "Web Service Security Standards."

Note:

Oracle has been instrumental in contributing to emerging standards, in particular the specifications hosted by the OASIS Web Services Secure Exchange technical committee.

3.1.1 Web Service Security Requirements

The following summarize the Web service security requirements:

  • Use transport security to protect the communication channel between the Web service consumer and Web service provider.

  • Use message-level security to ensure confidentiality by digitally encrypting message parts; integrity using digital signatures; and authentication by requiring username, X.509, or SAML tokens.

Oracle Web Services Manager (WSM) is designed to define and implement Web services security in heterogeneous environments, including authentication, authorization, message encryption and decryption, signature generation and validation, and identity propagation across multiple Web services used to complete a single transaction.

3.2 Understanding Transport-level and Application-level Security

Security concepts can be divided into those that pertain to the transport level and to the application level. Transport-level security secures the communications channel between applications. An example of a transport-level security protocol is Secure Socket Layer (SSL), otherwise known as Transport Layer Security (TLS), the Internet Engineering Task Force (IETF) officially standardized version of SSL. This is the most widely used transport-level data-communication protocol providing:

  • Authentication (the communication is established between two trusted parties).

  • Confidentiality (the data exchanged is encrypted).

  • Message integrity (the data is checked for possible corruption).

  • Secure key exchange between client and server.

SSL provides a secure communication channel, however, when the data is not "in transit," the data is not protected. This makes the environment vulnerable to attacks in multi-step transactions. (SSL provides point-to-point security, as opposed to end-to-end security.)

SSL can be used in three modes:

  • No authentication: Neither the client nor the server authenticates itself to the other. No certificates are sent or exchanged. In this case, only confidentiality (encryption/decryption) is used.

  • One-way authentication (or server authentication): Only the server authenticates itself to the client. The server sends the client a certificate verifying that the server is authentic. This is typically the approach used for Internet transactions such as online banking.

  • Two-way authentication (or bilateral authentication): Both client and server authenticate themselves to each other by sending certificates to each other. This approach is necessary to prevent attacks from occurring between a proxy and a Web service endpoint.

SSL uses a combination of secret-key and public-key cryptography to secure communications. SSL traffic uses secret keys for encryption and decryption, and the exchange of public keys is used for mutual authentication of the parties involved in the communication.

Application-level security complements transport-level security. Application-level security is based on XML frameworks defining message confidentiality, integrity, authenticity (also known as message protection); message structure; trust management and federation. These components of application-level security are described in greater detail in the following sections, "Understanding Message Protection", "Understanding Authentication", and "Understanding Authorization".

3.3 Understanding Authentication

Authentication is verifying that the user is who they claim to be. A user's identity is verified based on the credentials presented by that user, such as:

  • Something one has, for example, credentials issued by a trusted authority such as a digital certificate, standard Security Assertion Markup Language (SAML) token, or Kerberos token.

  • Something one knows, for example, a shared secret such as a password.

  • Something one is, for example, biometric information.

Using a combination of several types of credentials is referred to as "strong" authentication, for example using an ATM card (something one has) with a PIN or password (something one knows).

SAML is one of the most interesting security tokens because it supports both authentication and authorization. SAML is an open framework for sharing security information on the Internet through XML documents. SAML includes three parts:

  • SAML Assertion—How you define authentication and authorization information.

  • SAML Protocol—How you ask (SAML Request) and get (SAML Response) the assertions you need.

  • SAML Bindings and Profiles—How SAML assertions ride "on" (Bindings) and "in" (Profiles) industry-standard transport and messaging frameworks.

The full SAML specification is used in browser-based federation cases. However, Web services security systems such as OWSM only use SAML assertions. The protocol and bindings are taken care of by WS-Security and the transport protocol, for example HTTP.

SAML assertions and references to assertion identifiers are contained in the WS-Security Header element, which in turn is included in the SOAP Envelope Header element (described in the WS-Security SAML Token Profile). The SAML security token is particularly relevant in situations where identity propagation is essential.

3.3.1 Digest Authentication

OWSM supports digest based authentication in username-token authentication policies.

Digest authentication is an authentication mechanism in which a Web application authenticates itself to a Web service by sending the server a digest, which is a cyptographic hash of the password, nonce, and timestamp.

When using digest authentication:

  1. The client makes an un-authenticated request to the Web service, and the server sends a response with a digest authentication challenge indicating that it supports digest authentication.

  2. The client generates a nonce and sends it to the service along with a timestamp, digest, and username. The digest is a cyptographic hash of the password, nonce, and timestamp.

  3. The server generates the hash itself from the password (retrieved from the service store), nonce and timestamp (from the message), and if the generated hash matches the hash in the request, the request is allowed.

The advantage of digest authentication is it is resistant to replay attacks. The implementation maintains a cache of used nonces/timestamps for a specified period of time. All requests with a timestamp older than the specified timestamp are rejected as well as any requests that use the same timestamp/nonce pair as the most recent timestamp/nonce pair still in the cache. WebLogic Server stores this cache in a database.

3.4 Understanding Authorization

Frequently, authentication is the first step of determining whether a user should be given access to a Web service. After the user is authenticated, the second step is to verify that the user is authorized to access the Web service.

Authorization (also known as access control) is granting access to specific resources based on an authenticated user's entitlements. Entitlements are defined by one or several attributes. An attribute is the property or characteristic of a user, for example, if "Marc" is the user, "conference speaker" is the attribute.

Authorization enables you to determine what operations authenticated clients can access.There are three basic approaches to authorization:

  • Role-based—Role-based security is based on the notion that a set of identities, known as principals, can be grouped into roles, and then a policy can be applied to each of the roles.

  • Identity based—Identity Model enables you to manage claims and policies in order to authorize clients. With this approach, you can verify claims contained within the authenticated users' credentials. These claims can be compared with the set of authorization policies for the WCF service. Depending on the claims provided by the client, the service can either grant or deny access to the operation or resources. Identity Model is useful for fine-grained authorization and is most beneficial when using issue token authentication.

  • Resource based—Individual resources are secured by using Windows access control lists (ACLs).

3.5 Understanding Message Protection

Message protection encompasses two concepts, message confidentiality and message integrity.

Message confidentiality involves keeping the data secret, as well as the identities of the sending and receiving parties. Confidentiality is achieved by encrypting the content of messages and obfuscating the identities of the sending and receiving parties. The sender uses the recipient's public key to encrypt the message. Only the recipient's private key can successfully decrypt the message, ensuring that it cannot be read by third parties while in transit. The Web service's base64-encoded public certificate is published in the WSDL for use by the Web service client, as described in "Using the Service Identity CertificateExtensions" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

Message integrity is achieved by having an authority digitally sign the message. Digital signatures are used to authenticate the sender of the SOAP message and to ensure the integrity of the SOAP message (that is, to ensure that the SOAP message is not altered while in transit).

When a digital signature is applied to a SOAP message, a unique hash is produced from the message, and this hash is then encrypted with the sender's private key. When the message is received, the recipient decrypts the hash using the sender's public key.

Note:

Generally, the recipient does not need to have the sender's public key in its keystore to validate the certificate. It is sufficient to have the root certificate in the keystore to verify the certificate chain. However, if the sender's public key is not present in the message, as in the case of the Thumbprint and SerialIssuer mechanisms, the sender's public key must be in the recipient's keystore.

This serves to authenticate the sender, because only the sender could have encrypted the hash with the private key. It also serves to ensure that the SOAP message has not been tampered with while in transit, because the recipient can compare the hash sent with the message with a hash produced on the recipient's end.

The message-protection assertion templates and predefined policies can be used to protect request and response messages by doing the following:

  • Signing messages

  • Encrypting messages

  • Signing and encrypting messages

  • Decrypting messages

  • Verifying signatures

  • Decrypting messages and verifying signatures

3.5.1 Message Encryption

The XML encryption specification describes a process for encrypting data and representing the result in XML. Specifically, XML encryption defines:

  • How digital content is encrypted and decrypted.

  • How the encryption key information is passed to a recipient.

  • How encrypted data is identified to facilitate encryption.

An XML document may be encrypted as a whole or in part.

Example 3-1 illustrates credit card data represented in XML.

Example 3-1 XML Representation of Credit Card Data

<PaymentInfo xmlns="http://www.example.com/payment">
    <CreditCard>
      <Name>John Smith</Name>
      <CreditCardNumber>4019 2445 0277 5567</NCreditCardNumber>
      <Limit>5000</Limit>
      <Issuer>Example Bank</Issuer>
      <Expiration>04/02</Expiration>
    </CreditCard>
  </PaymentInfo>

Example 3-2 illustrates the same XML snippet with the credit card number encrypted and represented by a cipher value.

Example 3-2 XML Representation of Encrypted Credit Card Data

<PaymentInfo xmlns='http://www.example.com/payment">
    <CreditCard>
      <Name>John Smith</Name>
      <CreditcardNumber>
        <EncryptedData xmlns="http://www..." Type="http://www...">
          <CipherData>
            <CipherValue>A23B4...5C56</CipherValue>
          </CipherData>
        </EncryptedData>
      <Limit>5000</Limit>
      <Issuer>Example Bank</Issuer>
      <Expiration>04/02</Expiration>
    </CreditCard>
  </PaymentInfo>

3.5.2 Message Signing (XML Signature)

The XML Signature specification describes signature processing rules and syntax. XML Signature binds the sender's identity (or "signing entity") to an XML document. The document is signed using the sender's private key; the signature is verified using the sender's public key.

Signing and signature verification can be done using asymmetric or symmetric keys. XML Signature also ensures non-repudiation of the signing entity, that is, it provides proof that messages have not been altered since they were signed.

A signature can apply to a whole document or just part of a document, as shown in the following example.

Example 3-3 XML Representation of Signed Data

<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
<!-- The signedInfo element allows us to sign any portion of a
 document -->
  <SignedInfo>
    <CanonicalizationMethod Algorithm="http://www..."/>
    <SignatureMethod Algorithm="http://www..."/>
    <Reference URI="#Body">
      <DigestMethod Algorithm="http://www..."/>
      <DigestValue>o+jtqlieRtF6DrUb...X8O9M/CmySg</DigestValue>
    </Reference>
  </SignedInfo>
  <!-- Following is the result of running the algorithm over the
  document. If changes are made to the document, the SignatureValue is
  changed. The security application verifies the SignatureValue,
  extracts the X.509 cert and uses it to authenticate the user -->
  <SignatureValue>oa+ttbsvSFi...EtRD2oNC5</SignatureValue>
  <KeyInfo>
    <KeyValue>
      <!-- Following is the public key that matches the private key
      that signs the document -->
      <RSAKeyValue>
        <Modulus>5TT/oolzTiP++Ls6GLQUM8xoFFrAlZQ...</Modulus>
        <Exponent>EQ==</Exponent>
      </RSAKeyValue>
    </KeyValue>
    <!-- Following is the certificate -->
    <X509Data>
      <X509Certificate>wDCCAXqgAwIBAgI...</X509Certificate>
    </X509Data>
  </KeyInfo>
</Signature>

3.6 Understanding Keys and Certificates

Before you can use any message protection security policies or message protection and authentication with SSL security policies, you need to set up your keystores and truststores. (Authentication-only security policies do not require keys.)

The keystore contains the entities private keys and certificates associated with those private keys. A truststore contains certificates from a Certificate Authority (CA), or other entities that this entity trusts. The keystore and the truststore can be maintained together in a common store, such as with Oracle Web Services Manager (OWSM).

Before configuring your Web services, you need to determine the type of private keys and certificates required, the names for the keys and keystores, and then set up your environment accordingly.

3.6.1 Overview of Private Keys and Certificates

Private keys, digital certificates, and trusted certificate authorities establish and verify server identity and trust.

SSL uses public key encryption technology for authentication. With public key encryption, a public key and a private key are generated for a server. Data encrypted with the public key can only be decrypted using the corresponding private key and data verified with a public key can only have been signed with the corresponding private key. The private key is carefully protected so that only the owner can decrypt messages that were encrypted using the public key.

The public key is embedded in a digital certificate with additional information describing the owner of the public key, such as name, street address, and e-mail address. A private key and digital certificate provide identity for the server.

The data embedded in a digital certificate is verified by a certificate authority and digitally signed with the certificate authority's digital certificate. Well-known certificate authorities include Verisign and Entrust.net. The trusted certificate authority (CA) certificate establishes trust for a certificate.

An application participating in an SSL connection is authenticated when the other party evaluates and accepts the application's digital certificate. Web browsers, servers, and other SSL-enabled applications generally accept as genuine any digital certificate that is signed by a trusted certificate authority and is otherwise valid. For example, a digital certificate can be invalidated because it has expired or the digital certificate of the certificate authority used to sign it expired. A server certificate can be invalidated if the host name in the digital certificate of the server does not match the URL specified by the client.

The different types of trusted certificates that you can use in your environment, along with the benefits and disadvantages of each, are as follows:

  • Self-signed certificates — A self-signed certificate is a certificate that is signed by the entity creating it.

    Benefits:

    • Easy to generate because you can do it yourself, for example, using the keytool command for the JKS keystore as described in "Generating Private Keys and Creating the Java Keystore" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

    • Can be used in production as long as you use only a new certificate that you have generated.

    Disadvantages:

    • Self-signed certificates can quickly become unmanageable if you have many clients and services that need to communicate with each other. For example, if you have three clients communicating with two services, you need to generate a private key and self-signed certificate for both services, and then import the two certificates into the truststore of all three clients.

  • Demonstration Certificate Authority (CA) signed certificates— WebLogic Server includes a set of demonstration private keys, digital certificates, and trusted certificate authorities that are for development only.

    Benefits:

    • Easy to use because they are available and configured for use in the default WebLogic Server installation in a development environment.

    Disadvantages:

    • Should never be used in a production environment. The private key of the demo certificate CA is available to all installations of WebLogic Server, therefore each installation can generate a demo CA signed certificate using the same key. As a result, you cannot trust these certificates.

  • Internal CA signed certificates — An internal CA signed certificate is a certificate that you issue yourself using an internal CA that you can setup for your intranet. This type of certificate can be used if your services are mostly internal only.

    Benefits:

    • You have complete control over the certificate issuance process because you create the certificates yourself.You can control to whom the certificates are issued, how long the certificates remain valid, and so on. For example, if you are issuing certificates to your partners, you can issue them only to partners in good standing.

    Disadvantages:

    • You need to ensure that all clients have the internal CA root certificate imported into their truststore.

  • External CA signed certificates — An external CA signed certificate is a certificate that has been issued by a reputable CA such as Verisign and Entrust.net. This type of certificate should be used if your services are external facing.

    Benefits:

    • In most cases, clients are already set up to trust these external CAs. Therefore, those clients do not have to modify their truststore.

    Disadvantages:

    • You do not have any control over the certificate issuance process.

3.6.2 How Different Security Policies Use Private Keys and Certificates

OWSM security policies that require the use of private keys address two aspects: message protection and authentication:

  • Message protection encompasses two concepts, message confidentiality and message integrity. Message confidentiality involves keeping the data secret and is achieved by encrypting the content of messages. Message integrity ensures that a message remains unaltered during transit by having the sender digitally sign the message.

  • Authentication involves verifying that the user is who they claim to be. A user's identity is verified based on the credentials presented by that user.

The predefined OWSM policies that are included with your installation support various options for message protection and authentication. These options are described in the following sections.

Note:

The naming convention used for OWSM policies identifies the type of options being used. For example, the policy oracle/wss10_username_token_with_message_protection_service_policy is a message protection service policy that uses the wss10 Web services standard and requires a username_token for authentication. For more information about policy naming conventions, see "Recommended Naming Conventions for Policies".

3.6.2.1 Message Protection Policy Types

The types of message protection policies and how they work are described in the following sections.

3.6.2.1.1 SSL

Policies that include the SSL option, such as oracle/wss_saml_or_username_token_over_ssl_service_policy, use one-way SSL for message protection.

When using policies of this type, you need to do the following:

The private key is used to protect the messages for the SSL handshake, at which time the client and service agree on a shared session key. After the SSL handshake, the private key is not used, and all traffic between the client and the service are signed and encrypted using the shared session key.

For information on how to configure SSL, see "Configuring Transport-Level Security (SSL)" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

3.6.2.1.2 wss11

Policies of this type use WS-Security 1.1 for message protection.

When using wss11 policies, you need to do the following:

  • On the service side, set up private keys and define as the Encryption Key Alias in the OWSM Keystore Configuration screen. For details see "Configuring the OWSM Keystore Using Fusion Middleware Control" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

  • On the client side, you need to configure the client-side trust by obtaining the server's certificate in one of the following ways:

    • Use the service's public certificate published in the WSDL using the Service Identity Certificate extension as described in "Using the Service Identity Certificate Extensions" in Securing Web Services and Managing Policies with Oracle Web Services Manager. You also need to import either the server certificate itself, or the root certificate from the CA that issued the server certificate, into the client truststore. You can choose any alias name for the server certificate.

    • Import the server certificate into the client keystore using any alias you choose, and specify that alias using the keystore.recipient.alias property using a configuration override when you attach the policy. For this method you need to import the actual server certificate, you cannot import the CA root certificate.

For each request, the following occurs:

  1. The client creates a symmetric key, encrypts this symmetric key with the service's public key as configured with Encryption Key Alias, and then encrypts and signs the whole message with the symmetric key.

  2. When the service receives the message, it decrypts the encrypted key first, and then decrypts and verifies the whole message.

  3. The Web service then uses the same symmetric key to encrypt and sign the response that it sends back to the client.

3.6.2.1.3 wss10

Policies of this type use WS-Security 1.0 for message protection.

When using wss10 policies, you need to do the following:

  • Set up private keys on both the client and service side. On the client side, you need to set a signature key alias, and on the service side you need both an encryption key alias and signature key alias. Note that you can normally use the same key for both.

  • On the client side, you need to configure the client-side trust by obtaining the server's certificate in one of the following ways:

    • Use the service's public certificate published in the WSDL using the Service Identity Certificate extension as described in "Using the Service Identity Certificate Extensions" in Securing Web Services and Managing Policies with Oracle Web Services Manager. You also need to import either the server certificate itself, or the root certificate from the CA that issued the server certificate, into the client truststore. You can choose any alias name for the server certificate.

    • Import the server certificate into the client keystore using any alias you choose, and specify that alias using the keystore.recipient.alias property using a configuration override when you attach the policy. For this method you need to import the actual server certificate, you cannot import the CA root certificate.

  • On the service side, you need to configure the service to trust the client, either by importing these certificates directly, or importing the CA that issued these certificates.

Similar to the wss11 option, the client creates a symmetric key, and then encrypts the symmetric key with the service's public key. The difference, however, is that it only uses this symmetric key for encrypting the message; it doesn't use it for signing the message. Instead, the client signs the request message with its own private signature key as defined by the Signature Key alias, and the service signs the response with its private signature key.

3.6.2.2 Authentication Token Policy Types

The tokens that are supported for authentication, and the private keys and certificates that are used with these policy types are described in the following sections. For information on how to configure authentication, see "Configuring Authentication" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

Note that in the following sections, "signature key alias" means different things in different contexts.

  • In SAML sender vouches policies, it is the key used to sign the SAML assertion. This proves the authenticity of the SAML assertion, and SAML Login module will then assert the user specified in the SAML assertion.

  • In wss10 policies, it is used to sign the request and response message to prevent them from being tampered over the wire.

  • In X.509 authentication policies, it is used to authenticate a particular end user.

3.6.2.2.1 Username Token

A username token carries basic authentication information such as a username and password. When a username token is used with an authentication-only policy, no private keys are used. When used in a policy that includes authentication and message protection, the keys required for message protection are required.

3.6.2.2.2 Kerberos Token

A Kerberos token is comprised of a binary authentication and session token. When a kerberos token is used with an authentication-only policy, no private keys are used. When used in a policy that includes authentication and message protection, the keys required for message protection are required.

3.6.2.2.3 X.509 Certificate Token

Request messages are signed with the end user's signature key. On the client side you need to configure a signature key alias with the end user's signature key.

3.6.2.2.4 SAML Sender Vouches Token

In SAML sender vouches, the client signs the SAML token with its own private signature key.

Use the SAML sender vouches token with each of the message protection options as follows:

  • With SSL: SAML sender vouches requires two-way SSL. Therefore, you need to set up an SSL client-side private key, and corresponding trust certificate on the service side. If your SSL terminates before WebLogic Server, such as in the Oracle HTTP Server or in the Load balancer, you must configure these layers to propagate the client certificate all the way to WebLogic Server.

  • With wss11: Normally wss11 does not need a client-side signature key. However, when you use wss11 with SAML, you must set up a signature key on the client side, and configure it using the signature key alias. You must also add this client certificate or its issuer to the service's truststore.

  • With wss10: There is no additional setup to use SAML. The regular client signature key that is used for signing the request is also used for signing the SAML token.

    Note:

    Be very cautious when using the SAML signature key. It is a very powerful key as it enables the client side to impersonate any user. Consider configuring the server side to limit the number of SAML signers that is accepts, by setting up a Trusted DN list. For information about setting up a trusted DN, see "Configuring SAML Trusted Issuers and DN Lists Using Fusion Middleware Control" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

3.6.2.2.5 SAML Bearer and SAML HOK Tokens from an STS

For these options, the client does not construct the SAML token. Instead it is STS that constructs and signs the SAML token.

When using tokens from an STS, you must add the STS's certificate or its issuer to the service's truststore. Optionally, you can configure the STS in the Trusted DN list.

3.6.3 How OWSM Locates Keystore And Key Passwords for the JKS Keystore

OWSM expects JKS keystore and key passwords to be in the Credential Store Framework (CSF). Here is how it works.

  • A JKS keystore file is protected by a keystore password.

  • A keystore file consists of zero or more private keys, and zero or more trusted certificates. Each private key has its own password, (although it is common to set the key passwords to be the same as the keystore password). OWSM needs to know both the keystore password and key password.

  • The CSF consists of many maps, each with a distinct name. OWSM only uses the map oracle.wsm.security.

  • Inside each map is a mapping from multiple csf-key entries to corresponding credentials. A csf-key is just a simple name, but there can be many different types of credentials. The most common type of credential is a password credential which is primarily comprised of a username and a password.

    OWSM refers to the following csf-keys for the JKS keystore inside the oracle.wsm.security map:

    • keystore-csf-key - This key should contain the keystore password. The username is ignored.

    • enc-csf-key - This key should contain the encryption key alias as the username, and the corresponding key password.

    • sign-csf-key - This key should contain the signature key alias as the username, and the corresponding key password.

    In addition to these csf-keys, you should add a csf-key entry for every new private key that you want OWSM to use, for example when you want to specify signature and encryption keys in configuration overrides.

Figure 3-1 illustrates the relationship between the JKS keystore configuration in the OPSS, the oracle.wsm.security map in the credential store, and the OWSM Java keystore.

Figure 3-1 OWSM Keystore Configuration for Message Protection

Description of Figure 3-1 follows
Description of "Figure 3-1 OWSM Keystore Configuration for Message Protection"

As shown in the figure:

  • The keystore.csf.map property points to the OWSM map in the credential store that contains the CSF aliases. In this case keystore.csf.map is defined as the recommended name oracle.wsm.security, but it can be any value.

  • The keystore.pass.csf.key property points to the CSF alias keystore-csf-key that is mapped to the username and password of the JKS keystore. Only the password is used; username is redundant in the case of the keystore.

  • The keystore.sig.csf.key property points to the CSF alias sign-csf-key that is mapped to the username and password of the private key that is used for signing in the JKS keystore.

  • The keystore.enc.csf.key property points to the CSF alias enc-csf-key that is mapped to the username and password of the private key that is used for decryption in the JKS keystore.

3.6.4 Setting Up Private Keys and Certificates for SSL Policies

The following list summarizes the keys and trust you must configure on the client and service side to use SSL policies:

  • Service-side configuration: For SSL security policies, you must setup the private keys at the SSL termination point. These termination points typically consist of one of the following:

    • Java EE container, such as WebLogic Server. For configuration details, see "Configuring Keystores for SSL" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

    • Oracle HTTP Server, if you have configured it as a Web proxy between the client and WebLogic Server. For configuration details, see "Configuring SSL on Oracle HTTP Server" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

    • Load balancer, if you have a load balancer in front of WebLogic Server or Oracle HTTP Server.

    Note:

    With SSL you can only have one private key per server, so if there are multiple Web services running on the same server, they all use the same private key. This SSL private key needs to be generated with the same DN as the host name, although for testing purposes, you can turn off the host name verifier on the client side.

    Sample basic configuration: Use the demonstration digital certificates, private keys, and trusted CA certificates that are included with WebLogic Server. These keys and certificates are provided for development use only and should not be used in a production environment.

    Advanced configuration: In a production environment, use an internal or external CA.

  • Client-side configuration: On the client side, you need to import the server certificates into the client truststore. If the server side is using self-signed certificates, you need to include them directly. If the server side is using certificates that are signed using a CA, import the CA root certificate into the client truststore. Note that each type of Web service client has a different client truststore:

    • For Java EE (WebLogic) Web services, you need to import the keys into the WebLogic Server trust store. The demonstration CA certificate is already present in the WebLogic Server truststore.

    • For Oracle Infrastructure Web services you need to specify the truststore using javax.net.ssl* system properties, or specify it in the connection. For details, see "Configuring SSL for a Web Service Client" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

    • For asynchronous Web services, you need to configure the truststore as described in "Configuring SSL for Asynchronous Web Services" in Developing Oracle Infrastructure Web Services.

3.6.5 Setting up Private Keys and Certificates for Message Protection Policies

For OWSM message protection security policies, you need to setup your private keys in the OWSM keystore.

There is a single OWSM keystore per domain, and it is shared by all Web services and clients running in the domain. This keystore contains both private keys and trust certificates. The JDK cacerts file is not used by OWSM.

The following sections describe a basic OWSM keystore configuration and an advanced configuration.

Sample Basic Configuration

The easiest way to set up the OWSM keystore is to create a single self-signed private key and use it for the entire domain. When you create the private key and keystore, you specify a name and a password for the keystore, for example default-keystore.jks as the keystore name if you are using a JKS keystore, and welcome1 as the password for the keystore. You also specify an alias name and password to use when referring to the private key, for example orakey as the alias name and welcome1 as the key password. You can use the same key and alias for both the signature key alias and the encryption key alias, and the same password for both the keystore and the alias. You do not need to add any trusted certificates, as certificates associated with private keys are automatically considered as trusted.

Once you have created the keys and keystore, you need to provide the keystore password, and alias names and passwords to OWSM.You can do so using either Fusion Middleware Control or WLST.

The procedures in "Generating Private Keys and Creating the Java Keystore" and "Configuring the OWSM Keystore Using Fusion Middleware Control" in Securing Web Services and Managing Policies with Oracle Web Services Manager describe how to setup this basic configuration for a JKS keystore using the names and passwords specified in this example. In your own environment, you should use names and passwords that are appropriate for your configuration.

As long as your client and server are on the same domain, this set up is sufficient to work with most of the policies. That is, you can use any wss10 or wss11 policies with or without SAML.

If you have multiple related domains that share a common JPS root, you can copy this keystore file to all the domains. By doing so, all the related domains will share this single key for all encryption and signing.

Advanced Setup Considerations

As described in "Sample Basic Configuration", the simplest way to set up message protection security is to have a single private key for all Web services in the domain.

For more sensitive Web services, you need to configure each Web service to use its own distinct private encryption key. These private keys need to exist in the OWSM keystore. Ensure that each one uses a different alias name, for example ServiceA, and ServiceB, and that you add the aliases to the credential store. When you attach a policy to the service, you need to use a configuration override to indicate the specific alias name that the Web service requires, otherwise it will use the default alias that you configured for the domain, for example orakey.

The procedure in "Adding Keys and User Credentials to the Credential Store" in Securing Web Services and Managing Policies with Oracle Web Services Manager describes how to add these sample aliases to the credential store.

You should also use trusted certificates issued by an internal or external CA, instead of self-signed certificates, because it is much easier to manage the trusted CA certificates. Be sure, however, to set up the SAML signers Trusted DN list, as described in "Configuring SAML Trusted Issuers and DN Lists Using Fusion Middleware Control" in Securing Web Services and Managing Policies with Oracle Web Services Manager. This is especially important if you import external CA certificates into the OWSM Keystore, otherwise any user with a certificate will be able to sign a SAML token and impersonate any user.

3.7 How OWSM Uses the Credential Store

The Credential Store Framework (CSF) provides a way to store, retrieve, and delete credentials for a Web Service and other applications. OWSM uses the CSF to manage the credentials in a secure form by retrieving the following information:

  • Alias names and passwords for keys in the Java keystore

    For details about how OWSM uses the credential store to look up alias names and passwords from the Java keystore, see "How OWSM Locates Keystore And Key Passwords for the JKS Keystore".

  • Usernames and passwords used for authentication

    Suppose, for example, that you have a Web service that accepts a username token for authentication. If you create a Web service client to talk to this Web service, you need to configure the Web service client with a username and password that can be sent to the Web service. You store this username and password in the credential store (using either Fusion Middleware Control or WLST) and assign it a csf key.

    For example, the oracle/wss_username_token_client_policy policy includes the csf-key property, with a default value of basic.credentials. To use the wss_username_token_client_policy, you should create a new password credential in the CSF using the credential name basic.credentials, and the username and password with which the client needs to connect. If you have two Web service clients that use this same client policy, these clients can either share the same password credential, which defaults to basic.credentials, or each one can have its own credential. In the latter case, you need to create two password credentials in the CSF, for example App1.credentials and App2.credentials, for Client1 and Client2 respectively. For Client1, you set the csf-key configuration override to App1.credentials, and for Client2, you set the csf-key property to App2.credentials. For more information, see "Overriding Policy Configuration Properties" in Securing Web Services and Managing Policies with Oracle Web Services Manager. Note that in both cases, the usernames and passwords must represent valid users in the OPSS identity store.

A password credential can store a username and password. A generic credential can store any credential object.

The CSF configuration is maintained in the jps-config.xml file in the domain-home/config/fmwconfig directory.

When you configure the OWSM keystore using Fusion Middleware Control, as described in "Configuring the OWSM Keystore Using Fusion Middleware Control" in Securing Web Services and Managing Policies with Oracle Web Services Manager, the aliases and passwords that you specify are securely stored in the credential store. If, however, you add other aliases to the keystore, or you need to add authentication credentials for a client, you need to ensure that they are configured and stored in the credential store.

3.8 Understanding Security Policies

WS-SecurityPolicy is part of the Web Services Secure Exchange (WS-SX) set of specifications hosted by OASIS (in addition to WS-SecurityPolicy, the WS-SX technical committee defines two other sets of specifications: WS-Trust and WS-SecureConversation, described later in this chapter).

WS-SecurityPolicy defines a set of security policy assertions used in the context of the WS-Policy framework. WS-SecurityPolicy assertions describe how messages are secured on a communication path. Oracle has contributed to the OASIS WS-SX technical committee several practical security scenarios (a subset of which is provided by OWSM 12c). Each security scenario describes WS-SecurityPolicy policy expressions.

WS-SecurityPolicy scenarios describe examples of how to set up WS-SecurityPolicy policies for several security token types described in the WS-Security specification (supporting both WS-Security 1.0 and 1.1). The subset of the WS-SecurityPolicy scenarios supported by OWSM 12c represents the most common customer use cases. Each scenario has been tested in multiple-vendor WS-Security environments.

To illustrate WS-SecurityPolicy, let's use a scenario supported by OWSM: UsernameToken with plain text password. As mentioned earlier, Username token is one of the security tokens specified by WS-Security. This specific scenario uses a policy that says that a requester must send a password in a Username token to a recipient who has authority to validate that token. The password is a default requirement for the WS-Security Username Token Profile 1.1.

This scenario is only recommended when confidentiality of the password is not an issue, such as a pre-production test scenario with dummy passwords.

Example 3-4 Example of WS-SecurityPolicy

<wsp:Policy>
  <sp:SupportingTokens>
    <wsp:Policy>
      <sp:UsernameToken/>
    </wsp:Policy>
  </sp:SupportingTokens>
</wsp:Policy>

An example of a message that conforms to the above stated policy is shown below.

Example 3-5 Example of Message Conforming to WS-SecurityPolicy

<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="...">
  <soap:Header>
    <wsse:Security soap:mustUnderstand="1" xmlns:wsse="...">
      <wsse:UsernameToken>
        <wsse:Username>Marc</wsse:Username>
        <wsse:Password Type="http://docs.oasis open.org...>
           XYZ
        </wsse:Password>
        <wsse:Nonce EncodingType="...#Base64Binary">qB...</wsse:Nonce>
        <wsu:Created>2008-01-02T00:01:03Z</wsu:Created>
      </wsse:UsernameToken>
    </wsse:Security>
  </soap:Header>
  <soap:Body>
    <Oracle xmlns=http://xmlsoap.org/Oracle>
      <text>EchoString</text>
    </Oracle>
  </soap:Body>
</soap:Envelope>

The example above contains a <Nonce> element and a <Created> timestamp, which, while optional, are recommended to improve security of requests against replay and other attacks. A nonce is a randomly generated (unique) number. The timestamp can be used to define the amount of time the security token is valid.

3.9 Understanding Security Tokens

Web Services Security (WS-Security) specifies SOAP security extensions that provide confidentiality using XML Encryption and data integrity using XML Signature. WS-Security also includes profiles that specify how to insert different types of binary and XML security tokens in WS-Security headers for authentication and authorization purposes.

Web services security supports the following security tokens:

  • Username—defines how a Web service consumer can supply a username as a credential for authentication). For more information, see "Username Token"

  • X.509 certificate—a signed data structure designed to send a public key to a receiving party. For more information, see "X.509 Certificate"

  • Kerberos ticket—a binary authentication and session token. For more information, see "Kerberos Token"

  • Security Assertion Markup Language (SAML) assertion—shares security information over the Internet through XML documents. For more information, see "SAML Token"

3.9.1 Username Token

The username token carries basic authentication information. The username-token element propagates username and password information to authenticate the message.

3.9.2 X.509 Certificate

An X.509 digital certificate is a signed data structure designed to send a public key to a receiving party. A certificate includes standard fields such as certificate ID, issuer's Distinguished Name (DN), validity period, owner's DN, owner's public key, and so on.

Certificates are issued by certificate authorities (CA). A CA verifies an entity's identity and grants a certificate, signing it with the CA's private key. The CA publishes its own certificate which includes its public key.

Each network entity has a list of the certificates of the CAs it trusts. Before communicating with another entity, a given entity uses this list to verify that the signature of the other entity's certificate is from a trusted CA.

3.9.3 Kerberos Token

Kerberos token is a cross-platform authentication and single sign-on system. The Kerberos protocol provides mutual authentication between two entities relying on a shared secret (symmetric keys). Kerberos uses the following terminology:

  • A Principal is an identity for a user (i.e., a user is assigned a principal), or an identity for an application offering Kerberos services.

  • A Realm is a Kerberos server environment; a Kerberos realm can be a domain name such as EXAMPLE.COM (by convention expressed in uppercase).

Kerberos involves a client, a server, and a trusted party to mediate between them called the Key Distribution Center (KDC). Each Kerberos realm has at least one KDC. KDCs come in different packages based on the operating platform used (for example, on Microsoft Windows, the KDC is a domain service). The Kerberos Token profile of WS-Security allows business partners to use Kerberos tokens in service-oriented architectures.

3.9.4 SAML Token

The Security Assertion Markup Language (SAML) is an open framework for sharing security information over the Internet through XML documents. SAML was designed to address the following:

  • Limitations of web browser cookies to a single domain: SAML provides a standard way to transfer cookies across multiple Internet domains.

  • Proprietary web single sign-on (SSO): SAML provides a standard way to implement SSO within a single domain or across multiple domains. This functionality is provided by the Oracle Identity Federation product.

  • Federation: SAML facilitates identity management (e.g., account linking when a single user is known to multiple web sites under different identities), also supported by Oracle Identity Federation.

  • Web Services Security: SAML provides a standard security token (a SAML assertion) that can be used with standard web services security frameworks (e.g., WS-Security) – This is the use of SAML that is particularly relevant to web services security, fully supported by OWSM.

  • Identity propagation: SAML provides a standard way to represent a security token that can be passed across the multiple steps of a business process or transaction, from browser to portal to networks of web services, also a feature supported by OWSM.

The SAML framework includes 4 parts:

  • Assertions: How you define authentication and authorization information.

  • Protocols: How you ask (SAML Request) and get (SAML Response) the assertions you need.

  • Bindings: How SAML Protocols ride on industry-standard transport (e.g., HTTP) and messaging frameworks (e.g., SOAP).

  • Profiles: How SAML Protocols and Bindings combine to support specific use cases.

In the context of WS-Security, only SAML assertions are used. The protocols and bindings are provided by the WS-Security framework. SAML is widely adopted by the industry, both for browser-based federation and federation enabled by web services flows.

SAML assertions are very popular security tokens within WS-Security because they are very expressive and can help prevent man-in-the-middle and replay attacks.

Typically, a SAML assertion makes statements about a principal (a user or an application). All SAML assertions include the following common information:

  • Issuer ID and issuance timestamp

  • Assertion ID

  • Subject

  • Name

  • Optional subject confirmation (for example, a public key)

  • Optional conditions (under which an assertion is valid)

  • Optional advice (on how an assertion was made)

SAML assertions can include three types of statements:

  • Authentication statement: issued by an authentication authority upon successful authentication of a subject. It asserts that Subject S was authenticated by Means M at Time T.

  • Attribute statement: issued by an attribute authority, based on policies. It asserts that Subject S is associated with Attributes A, B, etc. with values a, b, and so on.

  • Authorization decision statement (deprecated in SAML 2.0, now supported by XACML): issued by an authorization authority which decides whether to grant the request by Subject S, for Action A (e.g., read, write, etc.), to Resource R (e.g., a file, an application, a Web service), given Evidence E.

SAML assertions can be embedded (i.e., a SAML assertion can contain another SAML assertion). SAML assertions can be signed (using XML Signature) and/or encrypted (using XML Encryption).

3.10 Understanding Secure Attachments

OWSM policies support two mechanisms to secure attachments: Packaging SOAP messages with attachments (SwA), and Message Transmission Optimization Mechanism (MTOM).

Packaging SOAP messages with attachments (SwA) has become common for any data that cannot be placed inside SOAP Envelope. The primary SOAP message can reference additional entities as attachments or attachments with MIME headers. For more information, see "Securing SwA Attachments" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

Using MTOM, binary content can be sent as a MIME attachment, which reduces the transmission size on the wire. The binary content is semantically part of the XML document. Attaching an MTOM policy ensures that the message is converted to a MIME attachment before it is sent to the Web service or client. See "MTOM Attachment Policies" in Securing Web Services and Managing Policies with Oracle Web Services Manager for more information.

3.11 Understanding Secure Conversation

OWSM implements the Web Services Trust (WS-Trust 1.3) and Web Services Secure Conversation (WS-SecureConversation 1.3) specifications, which together provide secure communication between Web services and their clients.

The Web Services Secure Conversation Language (WS-SecureConversation) specification (http://docs.oasis-open.org/ws-sx/ws-secureconversation/v1.4/os/ws-secureconversation-1.4-spec-os.doc) defines extensions that build on Web Services Security (WS-Security) 1.1 and 1.0 and Web Services Trust Language (WS-Trust) to provide secure communication across one or more messages. Specifically, this specification defines mechanisms for establishing and sharing security contexts or any credentials, and deriving keys from established security contexts (or any shared secret).

OWSM includes policies for which WS-SecureConversation is enabled by default, as described in "Which Policies Support WS-SecureConversation?" in Securing Web Services and Managing Policies with Oracle Web Services Manager. You may find that using the preconfigured WS-SecureConversation policies makes your security tasks easier to view at a glance and manage.

In addition, the OWSM security policies described in "Which Policies Support WS-SecureConversation?" include a configuration setting that allows you to enable and configure WS-SecureConversation for that policy.

This section describes the following topics:

3.11.1 Why Use WS-SecureConversation

There are two primary reasons you might want to use WS-SecureConversation: performance and security.

WS-Security, the standard employed by the OWSM security policies, provides the basic mechanism for securing messages.

However, without WS-SecureConversation, a client using an OWSM security policy (for example, oracle/wss11_username_with_message_protection) that exchanges multiple messages must repeatedly authenticate itself and perform expensive asymmetric operations such as key exchanges in each request.

To securely exchange multiple messages, a client and a Web service typically require a security context in which to exchange the messages. WS-SecureConversation provides just such a context. It adds a "handshake" process, which allows a Web service and its client to authenticate to each other and to establish a shared security context. The security context is shared by the client and Web service for the lifetime of a communication session. This context contains a shared secret key that can be used to secure subsequent messages between the client and service, and can improve performance by avoiding repeated key exchanges in multi-message exchange scenarios.

Enabling secure conversation means that there is no need to repeatedly exchange the keys and authenticate each time.

Consider the following sequence:

  1. When the first request is made by the client, the handshake happens between the client and the Web service.

  2. The client authenticates itself to the service as defined in the bootstrap policy using the WS-Trust protocol.

  3. The Web service returns the secure context token (SCT) containing the binary secret that is used for subsequent requests to secure messages during the communication session.

Note:

The authentication mechanism required by the Web service does not change, merely the frequency with which the authentication operation is performed.

WS-SecureConversation provides different benefits depending on whether you are using Wss11, Wss10, or SSL OWSM policies, as follows:

  • Wss11 — Wss11 scenarios involve one or two asymmetric cryptographic operations in the request depending on the policy. When WS-SecureConversation is in use, the authentication and asymmetric cryptographic operations are done only once at bootstrap time and the subsequent application requests will use the SCT to secure the messages. The SCT uses only symmetric cryptographic operations, which are less expensive.

    For example, when a "username with message protection" policy is enabled with WS-SecureConversation, the bootstrap policy uses the username token for authentication and Wss11 for message protection. However, subsequent messages do not involve any authentication and the messages are protected by the SCT.

  • Wss10 — Wss10 scenarios involve four asymmetric cryptographic operations in the request and response messages. When WS-SecureConversation is in use, the authentication and asymmetric cryptographic operations are done only once at bootstrap time and the subsequent application requests use the SCT to secure the messages. The SCT uses only symmetric cryptographic operations, which are less expensive.

    For example, when a "username with message protection" policy is enabled with WS-SecureConversation, the bootstrap policy uses the username token for authentication and Wss10 for message protection. However, subsequent messages do not involve any authentication and the messages are protected by the SCT.

  • SSL — With SSL scenarios, communication happens via SSL throughout the session. At the bootstrap time, authentication happens. Subsequent requests use the SCT to sign the timestamp and no authentication token is sent. Signing the timestamp by SCT proves that the request is sent by the authenticated client.

    In these scenarios, SSL is used for message protection; signing the timestamp with the SCT is used for authentication.

    For example if WS-SecureConversation is enabled for a "username over SSL" policy, the bootstrap policy uses the username token for authentication and SSL for message protection. However, subsequent messages will also use SSL but will contain a timestamp signed by the SCT instead of the username token.

3.11.1.1 Using WS-SecureConversation With WS-ReliableMessaging

A particularly important use of WS-SecureConversation is to provide security for WS-ReliableMessaging (WS-RM) policies. WS-RM benefits from the use of secure conversation to prevent sequence attacks.

As explained in the WS-ReliableMessaging specification (http://docs.oasis-open.org/ws-rx/wsrm/v1.2/wsrm.html), because reliable messaging sequences are expected to exchange a number of messages, it is recommended that a security context be established by using the WS-Trust and WS-SecureConversation mechanisms for protecting sequences.

Therefore, you should attach a WS-SecureConversation-enabled security policy with your WS-RM policy.

3.11.2 WS-SecureConversation Architecture

The WS-SecureConversation specification (http://docs.oasis-open.org/ws-sx/ws-secureconversation/v1.4/os/ws-secureconversation-1.4-spec-os.doc) defines extensions that build on Web Services Security (WS-Security) and Web Services Trust Language (WS-Trust).

The specification is the best source of information about the WS-SecureConversation architecture, features, and functions.

At a minimum, you should be familiar with the following concepts:

  • WS-Trust — As described in Web Services Trust Language (WS-Trust) in Understanding WebLogic Web Services for Oracle WebLogic Server, the Web Services Trust Language (WS-Trust) specification defines extensions that build on Web Services Security (WS-Security) 1.1 and 1.0 to provide a framework for requesting and issuing security tokens, and to broker trust relationships.

  • Security Context — A security context is an abstract concept that refers to an established authentication state and negotiated key(s) that may have additional security-related properties.

  • Security Context Token — A security context token (SCT) is a representation of the security context abstract concept, which allows a context to be named by a URI and used with WS-Security. Once the context and secret have been established (authenticated), you can then compute derived keys for each key usage in the secure context.

  • Derived Keys — As described in the WS-SecureConversation specification (http://docs.oasis-open.org/ws-sx/ws-secureconversation/v1.4/os/ws-secureconversation-1.4-spec-os.doc), "A security context token implies or contains a shared secret. This secret MAY be used for signing and/or encrypting messages, but it is recommended that derived keys be used for signing and encrypting messages associated only with the security context."

    Again as described in the WS-SecureConversation specification, "Once the context and secret have been established (authenticated), the mechanisms described in Derived Keys can be used to compute derived keys for each key usage in the secure context."

    Derived keys are useful for message protection. Instead of using the same SCT across multiple requests, a different key derived from the SCT is used in each request, which improves overall security.

    When you enable WS-SecureConversation for a policy, OWSM uses derived keys by default for WSS10 and WSS11. (For SSL policies, message protection is done using SSL and a derived key is not necessary.)

  • Session management — OWSM maintains the client and server secure conversation session information based on a computed Session ID.

    On the Web server side, the Session ID is maintained based on the port used by the Web service.

    Client sessions are expressed by the term "reference," which is similar in concept to a client port/binding that enables message communication.

    In the WS-SecureConversation implementation, each client reference is a separate WS-SecureConversation session. From the perspective of a Web service client request, this leads to the following outcomes:

    • Multiple requests can belong to the same reference.

    • All the requests with the same Session ID belong to the same session.

    • The state for which the Session ID is valid depends on the re-authentication setting.

    OWSM computes the Session ID at runtime for each message, and associates one or more requests to a session. OWSM uses user credentials, service information, and policy and configuration data to compute the Session ID.

    The Session ID is especially important when used with Oracle WS-RM policies, where for security and performance reasons multiple messages in an RM session are protected by the same secure conversation session.

  • Inner and outer policies — In the OWSM implementation of WS-SecureConversation, a secure conversation policy has actually two policies: inner and outer. The bootstrap (inner) policy is used to obtain the token and establish the handshake between the client and the Web service. The outer policy is used for application messages when making requests with the token.

    The message security settings for the outer policy are obtained from the original OWSM WS-Security policy, such as such as wss11_username_with_message_protection. The message security settings for the inner policy are then derived from the outer policy.

    In most cases, you do not need to be concerned with the details of the inner and outer policies, as OWSM handles this on your behalf. However, the OWSM WS-SecureConversation implementation provides an Advanced setting that provides additional control, as described in "Using Basic Mode Versus Advanced Mode".

  • Re-authentication — OWSM includes a re-authenticate control that indicates whether to create a separate session for each user or to allow users to share the same session. A user is authenticated only once whether re-authenticate is true or not.

    There is one supported use case in which the user ID might be different for each application message and therefore needs to be authenticated in each message during the WS-SecureConversation session: ID propagation with SAML sender vouches.

    Re-authentication allows multiple users to share a session. In this case, the authentication token is sent in each request because multiple users share the session. However, there is no need to exchange keys and asymmetric operations (sign, encrypt) are not performed in subsequent requests.

    The state for which the Session ID is valid depends on the re-authentication setting:

    • If re-authenticate is false, on the client side the Session ID is maintained for a single reference for a given user.

      On the server side, the Session ID is maintained based on the port used by the Web service.

    • If re-authenticate is true, on the client side the Session ID is maintained for a single reference, which may involve multiple users.

      On the server side, the Session ID is maintained based on the port used by the Web service.

3.11.3 When To Use WS-SecureConversation

You should consider using WS-SecureConversation in the following scenarios:

  • You are using any OWSM WS-RM policy.

  • Your Web service client is protected with an OWSM security policy (for example, oracle/wss11_username_with_message_protection) and frequently exchanges multiple messages.

When a Web service client or service are secured by OWSM and expect to be involved in multiple message exchanges, it makes sense to enable WS-SecureConversation. Enabling WS-SecureConversation provides better performance because the SCT secures subsequent messages between the client and service and you do not incur the overhead of repeated authentication and public key crypto operations.

Note:

For ID propagation use cases, WS-SecureConversation provides a performance benefit mainly for message protection because the authentication token is sent in each message during the session at the expense of performance.

Consider the following scenarios in which multiple message exchanges might happen and WS-SecureConversation might be useful:

  • One to One — In this case, a client application invokes a particular Web service multiple times on behalf of a single user.

  • One to One with re-authenticate=true (identity propagation) — In this case, a client application invokes a particular Web service multiple times. However, a different identity may need to be passed to the Web service in each subsequent request.

    A single secure conversation session is created for all users.

3.11.4 When To Use Re-Authentication

You can enable the re-authenticate control only in the case of ID propagation with SAML sender vouches policies. You should use re-authentication when the user ID might be different for each application message. In this situation, the user is authenticated in each message.

The bootstrap is done using the client identity and the end user identity is passed in all application requests to the service. WS-SecureConversation provides a benefit mainly for message protection, because the authentication token is sent in each message during the session at the expense of performance.

By default, the re-authenticate control is not set with WS-SecureConversation, and you can enable it only when WS-SecureConversation is also enabled.

3.11.5 Using Basic Mode Versus Advanced Mode

In the OWSM implementation of WS-SecureConversation, a secure conversation policy has actually two policies: inner and outer.

The bootstrap (inner) policy is used to obtain the token and establish the handshake between the client and the Web service. The outer policy is used for application messages when making requests with the token.

The message security settings for the outer policy are obtained from the original OWSM WS-Security policy, such as such as oracle/wss11_username_with_message_protection. The message security settings for the inner policy are then derived from the outer policy.

Therefore in most cases, you do not need to be concerned with the details of the inner and outer policies, as OWSM handles this on your behalf. However, the OWSM WS-SecureConversation implementation provides the Advanced screen shown in Figure 3-2 that provides additional control.

Figure 3-2 Secure Conversation Advanced Screen

Description of Figure 3-2 follows
Description of "Figure 3-2 Secure Conversation Advanced Screen"

The following Advanced options are available:

  • Client entropy

  • Server entropy

  • Derived Keys

  • Bootstrap Message Security:

    • Inherit From Application Setting

    • Use Independent Setting:

      • Algorithm Suite

      • Encrypt Signature

      • Signature Confirmation

      • Include Timestamp

      See "Configure Secure Conversation: Advanced Management" in Developing Oracle Infrastructure Web Services for additional information on setting these options.

3.11.6 Persistence

This section describes how to manage persistence for a session.

3.11.6.1 Default Domain-Wide Persistence Implementation

OWSM includes a default domain-wide persistence implementation that supports the Coherence Cluster and in-memory persistence providers.

The Coherence persistence provider is the default when running in WebLogic Server, for both the Web service client and Web service. Otherwise, the in-memory persistence provider is the default.

The level of persistence granularity for session recovery is the session object.

This persistence implementation is enabled by default and does not require any configuration.

3.11.6.2 Client- and Web Service-Specific Persistence Implementation

Each client and Web service can specify one or more (one per port) persistence providers, which can be either the Coherence provider or the in-memory provider.

To do this, use one of the mechanisms described in "Configure Persistence".

3.12 Understanding the Kerberos Protocol

Kerberos is an authentication protocol that enables computers (clients and servers) communicating over a non-secure network to prove their identity to one another in a secure manner, with the help of a trusted third party. In Kerberos, this trusted third party is the Key Distribution Center (KDC), which contains key information for clients and servers, called principals. The KDC consists of two components:

  • The Authentication Service (AS), which authenticates a principal with the KDC

  • The Ticket Granting Service (TGS), which provides authenticated principals with tickets they can use to request services from other principals in the KDC.

OWSM supports MIT Kerberos and Microsoft Active Directory as the KDC. For information about using MIT Kerberos, see "Using MIT Kerberos" in Securing Web Services and Managing Policies with Oracle Web Services Manager. For information about using Microsoft Active Directory, see "Using Microsoft Active Directory with Key Distribution Center" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

Here are the high-level steps involved when Kerberos is used for message security between a client principal and a server principal:

  1. AS-REQ (request to Authentication Service): The client begins the authentication process by sending the user ID to the AS.

  2. AS-REP (reply from Authentication Service): The AS responds with:

    • A client/TGS session key, encrypted using a hash of the user's password from the KDC

    • A Ticket Granting Ticket (TGT), encrypted using the secret key of the TGS.

  3. TGS-REQ (request to Ticket Granting Service): To begin communicating with services, the client first sends the following to the TGS:

    • The TGT it received from the AS

    • The ID of the requested service

    • An authenticator, encrypted using the client/TGS session key from the AS

  4. TGS-REP (reply from Ticket Granting Service): The TGS decrypts the TGT using its secret key, extracts the client/TGS session key from the decrypted TGT, and then uses this session key to decrypt the authenticator. It then responds with:

    • A client/server session key, encrypted using the client/TGS session key

    • A Service Ticket (ST), encrypted using the service's secret key

  5. AP-REQ (request to application): After receiving the reply from the TGS, the client initiates contact with the service by sending it:

    • The ST it received from the TGS

    • A new authenticator, encrypted using the client/server session key from the TGS

  6. AP-REP (reply from application): The service decrypts the ST using its secret key, extracts the client/server session key, and then uses this session key to decrypt the authenticator. It then extracts the timestamp from the decrypted authenticator, adds one to it, and sends this value back to the client after encrypting it using the client/server session key.

  7. The client decrypts the confirmation and checks whether the timestamp is correctly updated. If so, the client can trust the server and can begin issuing service requests.

For information on configuring OWSM to support the Kerberos protocol, see "Configuring the Kerberos Login Module" and "Configuring Kerberos Tokens" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

3.12.1 Credential Delegation in Kerberos

Sometimes, a service needs to access another service or server in order to complete a client request. In order to establish such a connection, Kerberos requires the first service to be authenticated to the second service or server using the client's user account and authority level. The mechanism Kerberos provides to meet this requirement is called credential delegation.

A common way to provide credential delegation in Kerberos is through the use of the FORWARDABLE and FORWARDED flags in Kerberos tickets, a technique called forwarded TGT. Here are a high-level steps involved in using forwarded TGT:

  1. The user requests the KDC for a TGT with forwardable flag set (Forwardable TGT) by setting the KDC option named FORWARDABLE in the initial AS-REQ.

  2. The client requests a FORWARDED ticket by presenting this forwardable TGT to the TGS. The client also sets the KDC Option named FORWARDED in the request (TGS_REQ) in addition to providing a set of service addresses for the new ticket.

  3. More such tickets (with the FORWARDED flag set) can be obtained from the KDC by providing the FORWARDED ticket obtained in Step 2.

Here are more detailed steps that specifies the message sequence:

  1. The user authenticates to the KDC by sending a KRB_AS_REQ message and requests a forwardable TGT.

  2. The KDC returns a forwardable TGT in the KRB_AS_REP message.

  3. The user requests a forwarded TGT based on the forwardable TGT from Step 2. This is done by the KRB_TGS_REQ message.

  4. The KDC returns a forwarded TGT for the user in the KRB_TGS_REP message.

  5. 5. The user makes a request for a service ticket to Service 1 using the TGT returned in Step 2. This is done by the KRB_TGS_REQ message.

  6. The ticket granting service (TGS) returns the service ticket in a KRB_TGS_REP message.

  7. The user makes a request to Service 1 by sending a KRB_AP_REQ message, presenting the service ticket, the forwarded TGT, and the session key for the forwarded TGT.

  8. To fulfill the user's request, Service 1 needs to invoke Service 2 to perform some action on behalf of the user. Service 1 uses the forwarded TGT of the user and sends that in the KRB_TGS_REQ message to the KDC, asking for a ticket to Service 2 in the name of the user.

  9. The KDC returns a ticket for Service 2 to Service 1, in a KRB_TGS_REP message, along with a session key that Service 1 can use. The ticket identifies the client as the user, and not Service 1.

  10. Service 1 makes a request to Service 2 using a KRB_AP_REQ, acting as the user.

  11. Service 2 performs the task and responds.

  12. Service 1 responds to the user's request with the response it gets from Service 2.

For information on configuring OWSM to use credential delegation, see "Configuring Credential Delegation" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

3.12.2 Kerberos and SPNEGO

SPNEGO (Simple and Protected GSS-API Negotiation Mechanism) is a standard that enables a client and a service to negotiate a method to use for authentication. Because SPNEGO uses HTTP headers to perform the negotiation, it is especially useful in a cross-platform context such as the web, where SOAP and REST endpoints that use HTTP are common.

When Kerberos is used in SPNEGO negotiation, the Kerberos token is wrapped in the HTTP header under the auth-scheme Negotiate. The WWW-Authenticate and Authorization headers are used to communicate the SPNEGO token between the client and the service, as follows:

  1. The client requests access to a protected service on the server without any Authorization header.

  2. Since there is no Authorization header in the request, server responds with the status code 401 (Unauthorized) and the WWW-Authenticate header set to Negotiate.

  3. The client uses the user credentials to obtain the Kerberos token and then sends it to the server in the Authorization header of the new request. For example, Authorization: Negotiate a87421000000492aa874209....

  4. The server decodes the token in the Authorization header. If the context is not complete (as in the case of Mutual Authentication), the server responds with a 401 status code and a WWW-Authenticate header containing the decoded data. For example, WWW-Authentiate: Negotiate 74900a2a....

  5. The client decodes this data and sends new data back to the server. This cycle continues until the security context is established.

For information on configuring OWSM to use Kerberos with SPNEGO, see "Configuring Kerberos With SPNEGO Negotiation" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

3.12.3 Kerberos and WS-SecureConversation Derived Keys

The Web Services Secure Conversation (WS-SecureConversation) specification includes a feature called derived keys, which enables parties that have already authenticated to each other to use a common secret to derive additional keys for various uses, such as signing and encrypting messages. Moreover, the WS-SecureConversation specification defines two types of derived keys:

  • Explicit derived keys, which use the wsc:DerivedKeyToken element to contain the token information. The ds:KeyInfo element then contains a reference to this information.

  • Implicit derived keys, which include the token information directly in the ds:KeyInfo element.

When using Kerberos in a WS-SecureConversation context, you can configure OWSM to use derived keys by enabling the Use Derived Keys option in the OWSM assertions for Kerberos.

3.13 Understanding Web Services Addressing

The Web Services Addressing (WS-Addressing) specification (http://www.w3.org/TR/ws-addr-core/) provides transport-neutral mechanisms to address Web services and messages. In particular, the specification defines a number of XML elements used to identify Web service endpoints and to secure end-to-end endpoint identification in messages.

SOAP does not provide a standard way to specify where a message is going or how responses or faults are returned. WS-Addressing provides an XML framework for identifying web services endpoints and for securing end-to-end endpoint identification in messages.

A Web service endpoint is a resource (such as an application or a processor) to which web services messages are sent.

The following is an example using WS-Addressing (wsa is the namespace for WSAddressing):

Example 3-6 Example of WS-Addressing

<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope"
   xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">
   <S:Header>
      <wsa:MessageID>http://example.com/xyz-abcd-123</wsa:MessageID>
      <wsa:ReplyTo>
         <wsa:Address>http://example.myClient1</wsa:Address>
      </wsa:ReplyTo>

WS-Addressing is transport-independent; that is, the request may be over JMS and the response over HTTP. WS-Addressing is used with other WS-* specifications, such as WS-Policy.

3.14 Understanding Web Services Trust

The WS-Trust 1.3 specification (http://docs.oasis-open.org/ws-sx/ws-trust/v1.3/ws-trust.html) defines extensions to WS-Security that provide a framework for requesting and issuing security tokens, and to broker trust relationships. WS-Trust extensions provide methods for issuing, renewing, and validating security tokens. To secure communication between a Web service client and a Web service, the two parties must exchange security credentials. As defined in the WS-Trust specification, these credentials can be obtained from a SecurityTokenService (STS), which acts as trust broker.

There are multiple scenarios in which you might consider using an STS, including:

  • Token Exchange/Conversion — Assume that you need to exchange one kind of token for another type of token. For example, if the client has a Kerberos token but the Web service requires a SAML token. You can use the STS to exchange the Kerberos token for a SAML token.

  • Federation — Identity federation allows a user to consolidate the many local identities he has configured among multiple service providers. With a federated identity, the individual can log in at one service provider site and move to an affiliated service provider site without having to re-authenticate or re-establish his identity.

    For example, you might use the STS to map a client user name to the user name expected by the Web service.

  • Centralized Trust — The STS is trusted by both the Web service client and the Web service. You use this trust to provide interoperable security tokens.

Consider the token exchange scenario shown in Figure 3-3. In this scenario, a customer has a desktop application (for example, a .NET Web service) that is talking to a backend Web service that can accept a SAML token.

Figure 3-3 STS Token Exchange

Description of Figure 3-3 follows
Description of "Figure 3-3 STS Token Exchange"

In Figure 3-3 user "joe" logs into his desktop and a Kerberos ticket is created. When the user opens the desktop application and performs an operation, this results in a backend Web service call and we want to propagate the identity of "joe" to the backend application. However the token we have is a Kerberos token on the client side and the backend Web Service only accepts a SAML token. You can use an STS to do a token conversion or token exchange.

For information on configuring OWSM to support the Kerberos protocol, see "Configuring WS-Trust" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

3.15 Understanding Web Services ReliableMessaging

WS-ReliableMessaging makes message exchanges reliable. It ensures that messages are delivered reliably between distributed applications regardless of software component, system, or network failures. Ordered delivery is assured and automatic retransmission of failed messages does not have to be coded by each client application.

Consider using reliable messaging if your Web service is experiencing the following problems:

  • network failures or dropped connections

  • messages are lost in transit

  • messages are arriving at their destination out of order

WS-ReliableMessaging considers the source and destination of a message to be independent of the client/server model. That is, the client and the server can each act simultaneously as both a message source and destination on the communications path.

For information on WS-ReliableMessaging (WS-RM), see "Using Web Services Reliable Messaging" in Developing Oracle Infrastructure Web Services.