2 Understanding Web Service Security Concepts

Web services security encompasses a number of requirements, such as authentication, authorization, and message protection.

Web Services Security concepts are described in the following sections:

Note:

A subset of OWSM authentication and authorization policies are supported for RESTful web services, as described in 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.

2.1 About Web Service Security

Web services with its nature of loosely coupled connections and its use of open access like HTTP, adds a new set of requirements to the security landscape.

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.

Key components of web service security are:

  • 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 "Overview of 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 "Overview of 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 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.

Oracle Web Services Manager (OWSM) 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.

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.

2.2 Understanding Transport-level and Application-level Security

Security concepts can be divided into transport level and application level security. 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, "Overview of Message Protection", "Understanding Authentication", and "Understanding Authorization".

2.3 Understanding Authentication

Authentication is verifying that the user is who they claim to be based on the credentials.

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.

2.3.1 About Digest Authentication

OWSM supports digest based authentication in username-token authentication policies. Digital 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 cryptographic 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.

2.4 Understanding Authorization

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 Windows Communication Foundation (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).

2.5 Overview of Message Protection

Message Protection is about the process of encrypting data, maintaining confidentiality of the messages and message signing.

The following topics describe message protection in detail:

2.5.1 Understanding Message Protection

Message protection encompasses two concepts, message confidentiality which involves keeping the data secret and message integrity by digitally authorizing the message.

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

2.5.2 About 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.

The following example illustrates credit card data represented in XML.

  <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>

The following example illustrates the same XML snippet with the credit card number encrypted and represented by a cipher value.

  <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>

2.5.3 About 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.

<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>

2.6 Overview of the Roles of Keys and Certificates in Security and Authentication

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

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. Note that authentication-only security policies do not require keys. For more information about authentication policies, see Understanding the OWSM Policy Framework.

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, for instance with Oracle Web Services Manager (OWSM).

For more information, refer to the following topics:

2.6.1 About 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.

2.6.2 Understanding 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 "About Recommended Naming Conventions for Documents Created in WSM Repository".

For more information, refer to the following topics:

2.6.2.1 Overview of Message Protection Policy Types

SSL, wss11, and wss10 message protection policies are supported in Oracle Web Service Manager.

2.6.2.1.1 About SSL Policies

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.

2.6.2.1.2 About wss11 Policies

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.

2.6.2.1.3 About wss10 Policies

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.

2.6.2.2 Overview of Authentication Token Policy Types

Supported tokens for authentication are username, Kerberos, X.509 Certificate, SAML sender vouches, SAML bearer, and SAML HOK tokens from STS.

For information on how to configure authentication, see "Configuring Authentication" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

Note:

In the following sections, "signature key alias" means different things in different contexts:

  • In SAML sender vouches policies, the signature key alias means 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, the signature key alias means the key used to sign the request and response message to prevent them from being tampered over the wire.

  • In X.509 authentication policies, the signature key alias means the key used to authenticate a particular end user.

For more information, refer to the following topics:

2.6.2.2.1 About the 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.

2.6.2.2.2 About the 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.

2.6.2.2.3 About the 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.

2.6.2.2.4 About the 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.

2.6.2.2.5 About 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.

2.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).

The working of JKS Keystore and key passwords is shown below:

Note:

For information about the OPSS Keystore Service, see "Managing Keys and Certificates with the Keystore Service" in Securing Applications with Oracle Platform Security Services.

  • 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 2-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 2-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.

2.6.4 About Private Keys and Certificates Configuration for SSL Policies

You can configure keys and trust 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 SOA composite applications, you need to specify the truststore using the javax.net.ssl* property as described in "Configuring SOA Composite Applications for Two-Way SSL Communication" in Administering Oracle SOA Suite and Oracle Business Process Management Suite.

    • 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.

2.6.5 About Setting up Private Keys and Certificates for Message Protection Policies

For OWSM message protection security policies, you must 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.

2.6.5.1 Understanding 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.

2.6.5.2 About Advanced Setup Considerations

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.

2.7 Understanding 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 username and password must represent valid users in the OPSS identity store.

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

The OPSS 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.

2.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.

<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.

<?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.

2.9 Overview of 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.

2.9.1 Understanding Security Tokens

Different kinds of Web services security tokens are explained in the following section.

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 About the Username Token.

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

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

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

2.9.2 About the Username Token

The username token carries basic authentication information.

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

2.9.3 About the 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.

2.9.4 About the 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.

2.9.5 About the 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).

2.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.

2.11 Overview of 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.

Secure conversation is described in the following topics:

2.11.1 About Secure Conversation

The Web Services Secure Conversation Language (WS-SecureConversation) specification defines mechanisms for establishing and sharing security contexts or any credentials, and deriving keys from established security contexts (or any shared secret).

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.

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.

2.11.2 Overview of WS-SecureConversation Usage

WS-SecureConversation is used in specific scenarios.The benefits of using WS-SecureConversation is explained in the following section.

The following topics describe WS-SecureConversation and its combination with WS-ReliableMessaging.

2.11.2.1 When to Use WS-Secure Conversation

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.

2.11.2.2 Benefits of WS-SecureConversation

For more information on the benefits of using WS-SecureConversation, see the comparison of Wss11, Wss10, or SSL OWSM policies.

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.

2.11.2.3 About 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.

2.11.3 WS-SecureConversation Architecture

The WS-SecureConversation specification defines extensions that build on Web Services Security (WS-Security) and Web Services Trust Language (WS-Trust).

The specification (http://docs.oasis-open.org/ws-sx/ws-secureconversation/v1.4/os/ws-secureconversation-1.4-spec-os.doc) 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, or to a SOA reference.

    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 "About Setting the Bootstrap 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.

2.11.4 When to Use WS-SecureConversation

WS-SecureConversation is used in specific scenarios in OWSM.

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.

2.11.5 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.

2.11.6 About Setting the Bootstrap Mode

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

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 additional control.

The following Bootstrap Message Security options are available:

  • Inherit From Application Setting

  • Use Independent Setting:

    • Algorithm Suite

    • Include Timestamp

    • Confirm Signature

    • Encrypt Signature

2.11.7 Overview of Persistence

Two persistence implementations exist: default domain-wide persistence, and client-specific/web service-specific persistence.

The section explains the preceding persistence implementation as follows:

2.11.7.1 About 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.

2.11.7.2 About 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".

2.12 Overview of 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.

The following topics explain Kerberos protocol in detail:

2.12.1 Understanding the Kerberos Protocol

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.

2.12.2 Understanding Credential Delegation in Kerberos

Kerberos uses the credential delegation mechanism when a service needs to access another service or server in order to complete a client request. 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.

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 specify 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.

2.12.3 Understanding 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-Authenticate: 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.

2.12.4 About 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.

2.13 Understanding Web Services Addressing

The Web Services Addressing (WS-Addressing) specification provides transport-neutral mechanisms to address web services and messages.

In particular, the specification(http://www.w3.org/TR/ws-addr-core/) 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):

<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.

2.14 Understanding Web Services Trust

The WS-Trust 1.3 specification 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 (http://docs.oasis-open.org/ws-sx/ws-trust/v1.3/ws-trust.html) , 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 2-2. 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 2-2 STS Token Exchange



In Figure 2-2 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.

2.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.

2.16 Overview of Fine-Grained Authorization Using Oracle Entitlements Server

Oracle Entitlements Server (OES) is a fine-grained authorization service you can use to secure applications and services across the enterprise. It supports centralized definition of complex application entitlements and the distributed runtime enforcement of those entitlements. OES allows you to externalize entitlements and thereby remove security decisions from the application.

OWSM OES integration supports advanced authorization use cases using OES and provides the following capabilities:

  • You can apply OES authorization to your SOAP-based web services. The OES authorization policy provides a grant or deny for a subject to perform a certain action on a given resource.

  • OES can make grant/deny decisions based on context attributes. The context attributes could be based on information from the SOAP request message extracted using XPath statements, or they could be based on HTTP headers.

  • Data masking. OWSM OES can mask (with character of your choice) certain information in the response for the web service request.

This section describes how Oracle Entitlements Server (OES) is integrated with OWSM, and how you can use OES together with OWSM for fine-grained authorization.

See “Configuring Fine-Grained Authorization Using Oracle Entitlements Server" in Securing Web Services and Managing Policies with Oracle Web Services Manager for configuration information.

2.16.1 References for OES Reading

References to many OES concepts and features is described in this section. The focus of the section is the integration with OWSM, and it does not attempt to provide an in-depth discussion of the OES concepts.

If you are not already familiar with OES, you should first refer to the Administrator's Guide for Oracle Entitlements Server and Fine Grained Authorization: Technical Insights for using Oracle Entitlements Server.

Note:

OWSM supports version 11.1.2.2.0 or later of OES.

2.16.2 Overview of OES Integration

You can integrate OWSM and OES. The OWSM agent checks the authorization for a protected web service based on the policies defined in OES and passes OES the autheticated subject and other attributes.

When you integrate OWSM and OES, you:

  • Attach an OWSM authentication policy to your web service.

  • Attach the OWSM oracle/binding_oes_authorization_policy or oracle/component_oes_authorization_policy policy, alone or in combination with the oracle/binding_oes_masking_policy policy as described in this section.

  • Use the OES console to create authorization and data masking policies, typically with separate policies for Obligations.

Note:

OWSM does not expose any OES-related configuration; you use the OES console for this purpose.

For more information, refer to the following topics:

2.16.2.1 OES Integration: The Big Picture

The OWSM agent checks the authorization of a soap request for a protected web service based on the policies defined in OES. To do this, OWSM passes to OES the authenticated subject, the target resource and requested action, as well as a set of implicit attributes that are always passed in authorization requests.

In your OES policy you can define additional required values based on context attributes from the SOAP request, HTTP headers, message context properties or identity information like the subject, roles, and groups. If you configure OES to require any extra of these context attributes to make a permit/deny decision, OWSM passes them as well.

Specifically, there are two ways to contact OES for the authorization decision: a two-step method and a single-step method. You select which via the use.single.step attribute in oracle/binding_oes_authorization_policy and oracle/component_oes_authorization_policy.

The methods function as follows:

  • In the two-step process, you must have previously identified attributes required for fine-grained authorization in the OES console and you now want OWSM to use them.

    OWSM first calls to OES to find out what attributes are needed, gets the attributes from the request payload, and then calls OES a second time to perform the actual authorization using the OES authorization policy. This means that you actually define two OES policies: one to get the needed attributes, and one for the authorization itself.

    You can also use always-passed implicit attributes, plus OES predefined attributes such as time, date, and so forth.

    This method is used for fine-grained authorization, as described in Overview of OES Fine- and Coarse-Grained Authorization.

  • In the single-step process, OWSM makes only one call to OES to perform the authorization using the OES authorization policy. The single-step process does not require any previously-identified attributes. As with the two-step process, you can also use the always-passed implicit attributes, plus OES predefined attributes such as time, date, and so forth.

    This method can be used for coarse-grained authorization, as described in Overview of OES Fine- and Coarse-Grained Authorization.

2.16.2.2 Data Masking

OWSM with OES integration can mask (with asterisks) certain information in the response from the web service, without changing any of the web services code.

Assume you want to ensure that sensitive data is not passed over the wire in response to a web service client request. You use the OES console together with the oracle/binding_oes_masking_policy policy to replace any sensitive data leaving the web service such as a social security number or financial information with asterisks, as shown in Figure 2-3.

Figure 2-3 Masking Sensitive Data



Masking sensitive data is based on who asked for it, and on other context attributes present in the request.

Consider the following code flow for the web service response shown in Figure 2-3.

Understanding Data Masking Code Flow

  1. The web service client sends a request.

  2. On the inbound request, OWSM enforces the request policy and performs the appropriate authentication and authorization for user Bob Doe.

  3. If the request is permitted, OWSM passes the payload to the service provider. The service provider acts on the payload and prepares a response to be sent back to the caller.

  4. During response processing, OWSM invokes the oracle/binding_oes_masking_policy policy to determine if there is any sensitive data that needs to be masked.

    OWSM passes the caller's information and any of the user-defined attributes extracted from the response payload.

  5. The data masking rules defined in OES take into consideration the client information (through transport attributes), the current subject, resource, action and any response attributes configured on the policy.

  6. For each payload attribute, OES responds with About XACML Obligations that specify whether the attribute should be passed as-is, or masked.

  7. OWSM honors the About XACML Obligations returned by OES and masks attributes marked as sensitive by OES.

2.16.2.3 About XACML Obligations

OES supports the XACML concept of Obligations. As described in "Understanding the Policy Model" in Oracle Fusion Middleware Administering Oracle Entitlements Server, when used in a policy, an Obligation may impose an additional requirement for the policy enforcing component.

You configure the Obligation in the OES console. An Obligation is any attribute name/value pair (or any other simple name/value pair) that is returned back to the caller (OWSM). For OWSM OES integration, the Obligation can be an XPath query, HTTP transport header properties, or message context properties.

Another use of Obligations is data masking. In certain applications, such as data security use-cases, a simple yes or no answer may not be sufficient and the OES authorization policy might return an Obligation that specifies what data is to be masked and with what value, as previously shown in Figure 2-3.

2.16.2.4 Overview of OES Fine- and Coarse-Grained Authorization

There are two ways to do authorization with the OWSM OES policies: fine- and coarse-grained authorization. The authorization types are defined in the following topics:

2.16.2.4.1 OES Fine-Grained (Obligations)

You want to determine access to the resource based on the identity of the consumer, plus specific content from the transport header or the payload specified in Obligations. This is the common use case.

In this use case, you define attributes in the OES access policy that OWSM will then extract from the request and pass back to OES during authorization. That is, the OES access policy is based on a combination of identity attributes or attributes extracted from the request payload.

For example, you might have an OES access check of "Allow access if the SOAP Body contains a particular customer ID and if the authenticated user belongs to group TrustedPartners."

Figure 2-4 shows the fine-grained authorization use case.

Figure 2-4 Fine-Grained Authorization



Consider the following code flow for the web service response shown in Figure 2-4.

  1. The web service client sends a SOAP request.

  2. The web service is secured with an OWSM authentication policy and an OWSM OES authorization policy.

  3. OWSM performs authentication and invokes OES for authorization.

  4. OWSM provides the subject, resource, lookup action and all predefined properties to OES.

  5. OES calls the lookup action configured for the protected resource and responds with the configured Obligations (if any) to OWSM. Returned obligations can be returned based on actions; for each action you can define different XPaths, and so forth.

  6. OWSM evaluates the Obligations and executes the XPath on the SOAP/XML payload or finds the property values from the transport header or message context.

  7. OWSM again provides the subject, resource, and action, plus all of the attributes evaluated in Step 6 to OES.

  8. OES determines access based on the subject, resource, action and attributes.

  9. OES responds with permit or deny.

  10. If permit, OWSM passes on the message to the service provider.

  11. If deny, OWSM rejects the request with an authentication failure fault.

2.16.2.4.2 Fine-Grained with SAML

You want to determine access to the resource based on the identity of the consumer and on the attributes passed in a SAML token. (See "user.attributes" and "user.roles.include" in Securing Web Services and Managing Policies with Oracle Web Services Manager for information on passing SAML attributes.

OWSM passes attributes from a SAML assertion. SAML attributes are part of the implicit attributes that are always extracted (if present) and sent automatically. The name of the attribute is the name of the attribute inside the SAML assertion and the value is the list of strings. OES can determine access based on these SAML attributes, as well as the subject, resource and action.

There are two ways to implement this use case. The first approach is to create an OES custom attribute retriever, as described in "Creating Custom Attribute Retrievers" in Oracle Fusion Middleware Developer's Guide for Oracle Entitlements Server. The second approach is to have OES respond using Obligations with XPaths that point to the SAML attribute values.

Consider the following code flow for the approach of using an OES custom attribute retriever:

  1. The web service client sends a SAML token with an attribute statement in a SOAP request.

  2. The web service is secured with oracle/wss10_saml_token_service_policy and an OWSM OES authorization policy.

  3. OWSM performs authentication and checks the SAML assertion for an AttributeStatement. If attributes are present, then OWSM extracts them and passes them as attributes while invoking OES for the access request.

  4. OWSM provides the subject, resource, and action, along with any other pre-defined attributes.

  5. OES determines access based on the SAML attributes, subject, resource and action. OES uses a custom attribute retriever to get the SAML attributes.

  6. OES responds with permit or deny.

  7. If permit, OWSM passes on the message to the service provider.

  8. If deny, OWSM rejects the request with an access-denied fault.

2.16.2.4.3 OES Coarse-Grained Authorization

You want OES to determine access to the resource based on the identity of the consumer and the web service operation being called. The OES access check is based on the identity attributes, which are limited to user name, group, and role. You can also use the implicit attributes, plus OES predefined attributes such as time, date, and so forth.

You must set use.single.step to true in the OWSM OES policy to use this mode.

Figure 2-5 shows the coarse-grained authorization use case. In this use case, assume that you want to secure the service with an authorization policy that determines whether the consumer is allowed to access the service. You want to determine access to the resource based on the identity (authenticated subject) of the consumer and the web service operation being invoked. For example, in Figure 2-5 user Bob Doe might be authorized to get the customer detail but not to delete the customer record.

Figure 2-5 Coarse-Grained Authorization



Consider the following code flow for the web service response shown in Figure 2-5.

  1. The web service client sends a SOAP or XML request.

  2. The web service is secured with an OWSM authentication policy and an OWSM OES policy.

  3. OWSM performs authentication and invokes OES for the access request. OWSM provides the subject, resource and action information to OES.

  4. OES determines access based on the subject, resource and action information.

  5. OES responds with permit or deny.

  6. If permit, OWSM passes on the message to the service provider.

  7. If deny, OWSM rejects the request with an access-denied fault.

2.16.3 About OWSM OES Policies

OWSM includes the following OES authorization and masking policies.

See "Predefined Policies" in Securing Web Services and Managing Policies with Oracle Web Services Manager for specific configuration information for each of the policies.

  • oracle/binding_oes_authorization_policy — This policy does user authorization based on the policy defined in OES. Authorization is based on attributes, the current authenticated subject, and the web service action invoked by the client.

    This policy is used for coarse- or fine-grained authorization on any operation on a web service, as determined by the use.single.step attribute. (See Overview of OES Fine- and Coarse-Grained Authorization.)

    You must use an authentication policy with the OWSM OES authorization policy because the OWSM OES policy requires an authenticated subject.

    This policy also uses the guard element (see orawsp:guard) to define resource, action, and constraint match values. These values allow the assertion execution only if the result of the guard is true. If the accessed resource name and action match, only then is the assertion allowed to execute. By default, resource name and action use the wildcard asterisk "*" and everything is allowed.

    This policy can be attached to any SOAP-based endpoint.

  • oracle/component_oes_authorization_policy — This policy does user authorization based on the policy defined in OES.

    This policy is used for coarse- or fine-grained authorization on any operation on a SOA component, as determined by the use.single.step attribute. (See Overview of OES Fine- and Coarse-Grained Authorization.)

    You must use an authentication policy with the OWSM OES authorization policy because the OWSM OES policy requires an authenticated subject. Authorization is based on attributes, the current authenticated subject, and the web service action invoked by the client.

    This policy also uses the guard element (see orawsp:guard) to define resource, action, and constraint match values. These values allow the assertion execution only if the result of the guard is true. If the accessed resource name and action match, only then is the assertion allowed to execute. By default, resource name and action use the wildcard asterisk "*" and everything is allowed.

    This policy is used for fine-grained authorization on a SOA component.

  • oracle/binding_oes_masking_policy — This policy does response masking based on the policy defined in OES. You can use an authentication policy with the OWSM OES masking policy. (If there is no subject, the masking decision does not consider the user when making a decision.) Masking is based on attributes, the current authenticated subject, and the web service action invoked by the client.

    This policy uses the guard element (see orawsp:guard) to define resource, action, and constraint match values. These values allow the assertion execution only if the result of the guard is true. If the accessed resource name and action match, only then is the assertion allowed to execute. By default, resource name and action use the wildcard asterisk "*" and everything is allowed.

    This policy is used for fine-grained masking on any operation of a web service.

2.16.4 Overview of Resource Mapping and Naming

You must map the OES resource name to the OWSM resource name. When making an authorization call from OWSM, the resource name is passed to OES, and this name must exactly match the one defined in the OES policy.

The following topics include:

2.16.4.1 Resource Mapping and Naming

Table 2-1 shows how to construct the resource string for the OES policy.

If you follow the naming conventions, you do not have to set the resource name in the OWSM policy, OWSM derives it.

Note:

This is the default mapping. If you need to change this mapping, use configuration overrides, as described in "Configuration Properties and Overrides" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

Table 2-1 Determining Resource String

OES Field Value to Use

Application

Deployed Application Name.

For SOA, the composite name is used as the application name.

Resource Type

Fixed, based on subject type.

  • For SOAP must be WS_SERVICE.

  • For SOA component, must be COMPONENT.

Resource Name

  • For SOAP and SOA reference, must be of the form web-service-name/port/web service operation.

  • For SOA component, must be of the form SOA component name/web service operation.

Action

By default, one of:

  • request.lookup (Obligation policy for authorization.)
  • response.lookup (Obligation policy for masking.)
  • mask (Real masking policy.)
  • authorize (Real authorization policy.)

2.16.4.2 Example of OES Policies

Assume that a SOA composite (soa1) has two service bindings (Serv1 and Serv2).

  • Serv1 has port11

  • Serv2 has port21

  • port11 has oper11, oper12

  • port21 has oper21

In OES, the application, resource type, resource name and actions should be defined as shown in Table 2-2.

Table 2-2 Resource String Example

OES Field Value to Use

Application

soa1

Resource Type

WS_SERVICE

Resource Name

Serv1/port11/oper11,

Serv1/port11/oper12,

Serv2/port21/oper21

Action

One of:

  • request.lookup (Obligation policy for authorization.)
  • response.lookup (Obligation policy for masking.)
  • mask (Real masking policy.)
  • authorize (Real authorization policy.)

The authorization and masking OES policies based on Table 2-2 are as follows:

  • Returning Obligations

    • One policy that returns obligations for any operation:

      GRANT (action: request.lookup; Resource: WS_SERVICE/Serv1/Port11, WS_SERVICE/Serv2/Port21; User: any) Obligation: XPath11
      
    • Multiple policies for returning operation-specific Obligations:

      GRANT (action: request.lookup; Resource: WS_SERVICE/Serv1/Port11/oper11;User:any) Obligation: XPath11
      GRANT (action: request.lookup; Resource: WS_SERVICE/Serv1/Port11/oper12;User:any) Obligation: XPath12
      GRANT (action: request.lookup; Resource: WS_SERVICE/Serv2/Port21/oper21;User:any) Obligation: XPath21
      
  • Real authorization

    • One policy performing same authorization regardless of resource and action:

      GRANT/DENY (action: authorize; Resource: WS_SERVICE/Serv1/Port11, WS_SERVICE/Serv2/Port21; User:<actual user>)
      
    • Multiple policies for performing operation-specific authorization:

      GRANT/DENY (action: authorize; Resource: WS_SERVICE/Serv1/Port11/oper11;User:<actual user>)
      GRANT/DENY (action: authorize; Resource: WS_SERVICE/Serv1/Port11/oper12;User:<actual user>)
      
  • Returning masking Obligations:

    GRANT (action: response.lookup; Resource: WS_SERVICE/Serv1/Port11/oper11;User:any) Obligation: XPath11
    GRANT (action: response.lookup; Resource: WS_SERVICE/Serv1/Port11/oper12;User:any) Obligation: XPath12
    GRANT (action: response.lookup; Resource: WS_SERVICE/Serv2/Port21/oper21;User:any) Obligation: XPath21
    
  • Real masking:

    GRANT/DENY (action: mask; Resource: WS_SERVICE/Serv1/Port11/oper11;User:<actual user>)
    GRANT/DENY (action: mask; Resource: WS_SERVICE/Serv2/Port21/oper21;User:<actual user>)
    

2.16.5 How Attributes Are Processed

As the OES administrator, you define attributes in the OES policy as Obligations, which OWSM then extracts from the payload and sends back to OES.

Specifically, OES allows you to create an Obligation in the OES console and provide multiple attribute name/value pairs. For example, you can create an Obligation called Employee and have multiple attributes such as {Name=John, Age=21, SSN=123456}.

The attributes can be obtained from an XPath, an HTTP header, a message context, and constants (name/value). These attributes must follow a specific naming convention, as described in Table 2-3.

Table 2-3 Attribute Types Supported for OES Policies

Attribute Type Description Required Format

XPath query

You provide the attribute name and value as an XPath query in the OES console.

OWSM runs this XPath query on the SOAP message and uses the value as the attribute value. The XPath query can result in a single value or multiple values. In case of multiple values, a list of strings is used to pass all values.

If any XPath query fails to evaluate on the SOAP message, it is ignored and a warning message is generated in the logs. OWSM continues to evaluate next XPath query.

Use XPath (case insensitive) as the Obligation name to signify that it is an XPath.

The Obligation should also return all the namespaces being used in the XPath query. All namespaces should be returned with an attribute name of NAMESPACE (case insensitive) and the value should be the comma separated namespaces.

For example, if you want to use the SAML issuer name for authorization, use the following Obligation format:

Name = XPath, values = {saml_issuer=.//saml:Assertion/@Issuer, CC_Name=ns1:sayHello/arg0, NAMESPACE=ns1=http://...,wsse=http://...}

In the authorization phase, OWSM passes the attribute name saml_issuer and the value is the result of the XPath query. The default namespace has to be mapped to a prefix. (The prefix name must be unique within the application.)

For example:

saml=urn:oasis:names:tc:SAML:1.0:assertion,ns0=http://wsm.oracle.com,myPrefix=http://default_namespace

Namespace definitions are separated using a comma.

HTTP Header

You provide HTTP header names in the OES console.

The value is fetched from the current request HTTP header.

To get HTTP Header properties, define an Obligation with the name "HTTPHeader" (case insensitive). It can have multiple HTTP header names.

The name of the attribute should be the name to which you want to assign the value; the value should be the actual HTTP header name.

For example:

Name = HTTPHeader, values = {AuthHeader=Authorization}

In the authorization phase, OWSM retrieves the HTTP header and assigns it to the name given in the attribute name.

Message Context Properties

You provide message context property names in the OES console.

The value is fetched from the current message context.

Define an Obligation with the name "MessageContext" (case insensitive). It can have multiple message context property names.

The name of the attribute should be the name to which you want to assign a value; the value should be the actual message context property name.

For example:

Name = MessageContext, values = {authMethod=oracle.wsm.internal.authentication.method, endpoint=oracle.j2ee.ws.runtime.endpoint-url}

In the authorization phase, OWSM retrieves the message context property and assigns it to the name given in the attribute name.

For example, the previous example might resolve to:

authMethod=USERNAME_TOKEN & endpoint=http://localhost:7001/myService

Constants

Constants are user-defined attributes that OWSM does not understand and passes "as is."

An Obligation named Employee is an example of a constant.

Implicit

OWSM passes implicit attributes in all authorization requests. You do not perform any configuration to pass them. The following implicit attributes are always passed:

  • serviceURL — The URL of the web service.

  • serviceNS — The namespace of the web service.

  • clientIP — The client's IP address.

  • processingStage — Whether this is a request or response. Possible values are request, response, and fault.

  • isRequestOverSSL — Boolean. True if the request is over one- or two-way SSL.)

  • authenticationMethod — The authentication method. Possible values are SAML_SV, KERBEROS, SAML_HOK, X509_TOKEN_AUTHENTICATION, SAML_BEARER, and USERNAME_TOKEN

  • requestOrigin — Where the request came from, internal or external, as determined from the VIRTUAL_HOST_TYPE transport header.

  • clientSigningCertDN — Either the X509 signing cert or the client cert in two-way SSL.

  • operationName — The operation name invoked by the user.

  • samlIssuer — The SAML issuer extracted from the SAML assertion.

  • type — The type of the request to OES. Values can be request.lookup, response.lookup, authorize or mask. This attribute is always sent.

None required, they are always passed.

You would typically use these constants in a Condition in the OES console.

2.16.6 About the Guard Element

The OWSM OES authorization policies uses the orawsp:guard element. It allows the assertion to execute only if the result of the guard is true. That is, if the accessed resource name and action match, only then OES authorization engine is called.

By default, resource name and action use the wildcard asterisk "*" and everything is allowed. However, if you set a specific resource name, action, and constraint, that requirement must be satisfied before any of the configuration properties and any OES policies are considered.

The resource naming convention for guard differs from the OES standard naming convention. The resource name for the guard must be in the form <Webservice_NS>/<SERVICE_NAME>.

2.17 Overview of Personally Identifiable Information

Personally Identifiable Information (PII) refers to Social Security numbers, addresses, bank account numbers, and other similar information that is typically associated with one specific user and must generally be protected.

OWSM provides a solution for protecting PII when outside the control of a security policy so that PII is hidden in logs, in messages, in audits, and so forth.

2.17.1 Overview of PII Data

The OWSM WS-Security policies provide a way to selectively encrypt information through message protection. However, there may be times when this information is outside of the control of a security policy and not encrypted, such as when it is being processed inside a SOA composite.

PII data is described in the following topics:

2.17.1.1 About PII Data

Your business practices may require that information, and particularly PII information, be encrypted even as it flows within your applications. If this is true for your environment, PII information should remain encrypted as the message flows to various components. For example, in the case of SOA, it means that PII must be encrypted at the entry point of a SOA composite and must be decrypted at the reference binding exit point.

The oracle/pii_security_policy policy is provided to encrypt data for this purpose.

See "About Additional Considerations for Unmarshalling" for additional information when unmarshalling non-string data.

Note:

Although the OWSM WS-Security policies provide a way to encrypt information, this mechanism cannot be used to encrypt PII data because your applications might expect and depend on the information having a specific XML structure. The OWSM policies add CipherData (http://www.w3.org/TR/xmlenc-core/#sec-CipherData) elements to the XML structure, which your applications might not expect.

2.17.1.2 About the PII Security Policy

The oracle/pii_security_policy contains the following settings and configuration properties that specify exactly which PII data you want to protect. You can set these attributes when you attach a policy, and override them as required.

Note:

Local optimization (see "Using Local Optimization with OWSM Policies (SOA Composites")) is off by default so that the oracle/pii_security_policy policy is always enforced and decrypts PII before leaving the SOA composite. Do not turn local optimization on for the oracle/pii_security_policy policy without understanding the ramifications.

See "About PII Policy XPath Expressions" for a description of how XPaths are used to specify the PII data.

  • encryption-algorithm — The data encryption algorithm, which must be AES/CBC/PKCS5Padding.

  • algorithm — The key derivation algorithm, which must be PBKDF2.

  • Salt — A non-null and non-empty salt for key derivation. The default value is pii-security.

  • Iteration — The iteration count for key derivation. The default is 1000.

  • Keysize — The size of the key for key derivation. The default is 128.

  • request.xpaths — A comma-separated list of XPaths for the request. Default value is blank. For example, //ns2:ShipToLocationId.

  • request.namespaces — A comma-separated list of namespaces for the request, where each namespace has a prefix and URI separated by the equals = sign. Default value is blank.

  • response.xpaths —A comma-separated list of XPaths for the response. Default value is blank. For example, //ns2:ShipToLocationId.

  • response.namespaces — A comma-separated list of namespaces, where each namespace has a prefix and URI separated by the equals = sign. Default value is blank.

  • csf.key — The oracle/pii_security_policy policy uses the password CSF key attribute you specify to generate a symmetric key. This key is then used to encrypt and decrypt the PII data. Default value is pii-csf-key.

  • reference.priority — See "Specifying the Priority of a Policy Attachment".

Note:

The pii-security assertion must be the only assertion in a policy. You must not add the pii-security assertion to a policy with any other assertion. If you do so, the policy is invalid.

2.17.2 Example of How PII Data is Protected

It is important to protect PII with the oracle/pii_security_policy policy when outside the control of a security policy.This is explained by the way of example.

Consider the Oracle Service Bus example shown in Figure 2-6. As shown in Figure 2-6, the guiding principle for protecting PII is as follows:

  • A PII policy attached at the service side (proxy service) must encrypt PII after receiving request and decrypt PII before sending out a response.

  • A PII policy attached at the client side (business service) must decrypt PII before sending out request and encrypt after receiving a response.

Encrypting PII data requires both entry and exit points: PII data is encrypted before entry and decrypted before exit.

Figure 2-6 PII Encryption in Oracle Service Bus



The flow of control in Figure 2-6 is as follows:

  1. The OWSM web service client signs and encrypts a client request and sends the request to the proxy service.

  2. To virtualize an external web service, you create an OSB proxy service that uses a pipeline to connect to a business service. Therefore, you attach OWSM service side policies to the proxy.

    The OWSM Agent decrypts the message using the message protection policy.

  3. Any PII information would now potentially be vulnerable. To prevent that, the PII policy encrypts the PII in the message.

  4. Oracle Service Bus assumes control of the message, and the proxy service passes the request to the business service.

  5. The business service accesses the message data, perhaps including the now-encrypted PII data, as needed.

  6. The OWSM agent again applies the PII policy and decrypts the PII fields.

  7. A business service is basically all the client configuration needed to call an external service. Oracle Service Bus supports attaching OWSM client policies to a business service.

    The message protection policy is applied (signed, encrypted) and the message is sent to the web service.

  8. The process is reversed for the response back to the web service client.

2.17.3 About PII Policy XPath Expressions

You use XPath expressions to specify the PII data to be protected.

More specifically, you use XPath expressions to specify exactly which elements you want to protect. The XPath must end in an XPath text node.

If the result of the XPath is a text node, the contents of the text node are encrypted. Empty text nodes (that is, containing all whitespace) are not encrypted or decrypted.

If any XPath returns multiple nodes, all of them are encrypted. If nothing is returned, it is ignored.

The specified XPaths will be evaluated with the first element child of env:Body set as the root node.

Assume that you use JDeveloper to view the following SOAP message:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body 
 
 
xmlns:ns1="http://xmlns.oracle.com/apps/prc/po/editDocument/purchaseOrderService/types/">
<ns1:createPurchaseOrder>
 <ns1:createOrderEntry 
 
 
xmlns:ns2="http://xmlns.oracle.com/apps/prc/po/editDocument/purchaseOrderService/">
 <ns2:DocumentStyleId>1</ns2:DocumentStyleId> 
 <ns2:ProcurementBuId>204</ns2:ProcurementBuId> 
<ns2:BuyerId>100010026863783</ns2:BuyerId> 
<ns2:RequisitioningBuId>204</ns2:RequisitioningBuId> 
<ns2:SupplierId>559</ns2:SupplierId> 
<ns2:SupplierSiteId>5058</ns2:SupplierSiteId> 
<ns2:SupplierContactId>100000011552368</ns2:SupplierContactId> 
<ns2:ApprovalActionCode>BYPASS</ns2:ApprovalActionCode> 
<ns2:DocumentDescription>DO NOT TOUCH THIS ORDER (V15)</ns2:DocumentDescription> 
<ns2:PurchaseOrderEntryLine>
<ns2:LineTypeId>1</ns2:LineTypeId> 
<ns2:ItemId>199</ns2:ItemId> 
<ns2:Quantity>10</ns2:Quantity> 
<ns2:UnitOfMeasureCode>Ea</ns2:UnitOfMeasureCode> 
<ns2:PurchaseOrderEntrySchedule>
<ns2:ShipToLocationId>207</ns2:ShipToLocationId> 
<ns2:ShipToOrganizationId>207</ns2:ShipToOrganizationId> 
<ns2:NeedByDate>2020-12-31</ns2:NeedByDate> 
<ns2:PurchaseOrderEntryDistribution /> 
</ns2:PurchaseOrderEntrySchedule>
</ns2:PurchaseOrderEntryLine>
</ns1:createOrderEntry>
</ns1:createPurchaseOrder>
</soap:Body>
</soap:Envelope>

Some XPath examples are as follows:

  • //ns2:ShipToLocationId

    Use the // notation (descendant-or-self axis) to indicate that you want to search the whole body for ShipToLocationIds. These XPaths require a complete document search and are slower.

  • /ns1:createPurchaseOrder/ns1:createOrderEntry/ns2:BuyerId

    This XPath clearly specifies that you want to look at the createPurchaseOrder child of the body, and then the createOrderEntry child of the createPurchaseOrder, and finally the BuyerId child of createOrderEntry.

The PII policy requires XPath lists for both the request and response messages.

2.17.4 When to Use the PII Policy

You can use the oracle/pii_security_policy policy only in single-SOA composite use cases, and uses cases where PII is at the JCA binding.

Note:

Global Policy Attachment is not recommended with the oracle/pii_security_policy policy.

Different usecases are explained in the following topics:

Note:

Fusion Middleware Control and JDeveloper control produce runtime validation errors if you attach the pii_security_policy policy to a non-supported subject type.

With WLST, validation errors are generated if you attach the policy to a non-supported subject type:

The web service configuration is invalid in this context because of the following error: WSM-01832 : PII Policy oracle/pii_security_policy is not supported on the Resource, as the PII policy 
is not supported on SubjectType : WS_SERVICE

2.17.4.1 Single SOA Composite Use Case

You can attach the pii_security_policy policy only to a SOA composite and only to protect PII within that composite. No other SOA use case is supported.

When you attach the pii_security_policy policy to a SOA composite, the PII is encrypted when a message enters the SOA composite and decrypted when exiting from the composite at a SOA reference binding component. Specifically:

  • At the service side (service binding), the pii_security_policy policy encrypts PII after receiving a request and decrypts PII before sending out a response.

  • At the client side (reference binding), the pii_security_policy policy decrypts PII before sending out a request and encrypts PII after receiving a response.

Note:

PII data requires both entry and exit points: PII data is encrypted before entry and decrypted before exit.

When you attach the pii_security_policy policy at the client side, you must also attach it at the service side, and vice versa. The encryption/decryption mechanism requires both pieces to be in place.

As shown in Figure 2-7, the PII remains encrypted as the message flows to various components of the composite such as a BPEL, Oracle Mediator, and so forth.

Figure 2-7 Single SOA Composite Use Case



Understanding important considerations when both PII and Authorization Policy are attached

If the pii_security_policy policy and an authorization policy are both attached to a SOA composite, the authorization policy is executed before the PII policy. Otherwise, the pii_security_policy policy might encrypt the field to be used for authorization.

However, if the authorization policy is instead attached at the SOA component level, and authorization requires a field that is encrypted by pii_security_policy, authorization fails. This is not a supported use case.

2.17.4.2 Oracle Service Bus Proxy Service to Business Service Use Case

See "Hiding Personally Identifiable Information in Messages" in Developing Services with Oracle Service Bus for information on how to attach oracle/pii_security_policy to Oracle Service Bus.

2.17.4.3 PII at the JCA Binding Use Case

You can attach the PII policy to JCA adapters for both SOA and Oracle Service Bus.

For OSB, see "Hiding Personally Identifiable Information in Messages" in Developing Services with Oracle Service Bus for information on how to attach oracle/pii_security_policy to Oracle Service Bus.

The remainder of this section describes the SOA use case.

As described in "JCA Adapters", in Developing SOA Applications with Oracle SOA Suite, JCA adapters enable you to integrate SOA services and references with technologies such as databases and file systems. JCA adapters integrate with the JCA binding component of the Oracle Fusion Middleware platform, thereby integrating with other service engines and binding components.

Consider the JCA adapter PII use case shown in Figure 2-8.

Figure 2-8 JCA Adapter PII Use Case



The composite includes an inbound service binding component (an inbound adapter), a service component such as a BPEL process, and an outbound reference binding component (an outbound adapter).

Note:

PII data requires both entry and exit points: PII data is encrypted before entry and decrypted before exit.

When you attach the pii_security_policy policy at the reference binding side, you must also attach it at the service binding side, and vice versa. The encryption/decryption mechanism requires both pieces to be in place.

In this use case, PII is protected as follows:

  • Service binding components provide the outside world with an entry point to the SOA composite application.

    At the service side (JCA binding), the pii_security_policy policy encrypts PII after receiving a request and decrypts PII before sending out a response.

  • The PII remains encrypted as the message flows to various components of the composite such as a BPEL, Oracle Mediator, and so forth.

  • Reference binding components enable messages to be sent from the SOA composite application to external services in the outside world.

    At the client side (JCA binding (reference)), the pii_security_policy policy decrypts PII before sending out a request and encrypts PII after receiving a response.

See Oracle SOA Composite Integration with Adapters for additional information on how JCA adapters integrate with SOA environments.

2.17.5 Who Should Have Access to the PII

As the administrator, you always have access to the keys used to encrypt the PII and you can reconfigure PII encryption. Therefore, the PII policy does not protect data from an administrator or any one else with these administrator privileges, and it is not intended to do so.

However, as the administrator, you need to make sure that the encryption key and PII data are not visible in the following scenarios:

  • In any kind of logs, including the OWSM message logs, the server diagnostic logs, SOA message logs, and so forth. Logs are often copied and made available to non-administrative users.

  • In any screens that can be viewed by non-administrative users.

    Such a user should not be able to see any PII information. This user can view logs, but the logs will have encrypted PII data, and this user will not be able to view the key information required to decrypt them.

  • To roles such as "Operator", "Monitor," and so forth. These roles should not be able to access either the PII encryption keys or the PII data, and should not be able to access any log files that contain decrypted PII data.

2.17.6 About Additional Considerations for Unmarshalling

Unmarshalling converts an XML document to create a tree of Java program elements, or objects, that represents the content and organization of the document that can be accessed by your Java code. In the content tree, complex types are mapped to value classes. Attribute declarations or elements with simple types are mapped to properties or fields within the value class and you can access the values for them using get and set methods.

Unmarshalling is managed by the JAXB binding framework.

After the PII data is encrypted, the original text in the message is replaced by an encrypted string. However, if there are non-string data types (integer, date, and so forth) in the encrypted string, any subsequent unmarshalling may break.

Before you implement the pii_security_policy policy, be aware of the implications for unmarshalling: if unmarshalling might be involved, then only the string data type works and others may break.

Unmarshalling can happen in SOA at the following bindings:

  • EJB Adapters

  • Legacy SDO EJB adapter

  • ADF Adapter

  • Direct bindings

  • Rules engine

Unmarshalling can happen at the following SOA components:

  • BPEL Entity Variable

  • Spring service engine

Unmarshalling can happen in Oracle Service Bus at the following points:

  • SOA direct bindings

  • EJB transport

2.18 Understanding OAuth 2.0 for REST and SOAP Services and Clients

Oracle Web Services Manager allows web service clients to interact with the Mobile and Social OAuth 2.0 server implementation for both SOAP and REST web services, for "2-legged" authorization.

For more information, see "Using OAuth2 with Oracle Web Services Manager" in Oracle® Fusion Middleware Securing Web Services and Managing Policies with Oracle Web Services Manager.

2.19 Understanding REST APIs for Managing Credentials and Keystores

The credential and keystore management REST API provides endpoints for creating and configuring credential stores, keystores, and trust stores for your domain or Web services.

For more information, see Introduction to REST API in REST API for Managing Credentials and Keystores with Oracle Web Services Manager.