47 Understanding Oracle Service Bus Security

This chapter provides an overview of the Service Bus security model and its features, including inbound and outbound security.

Service Bus supports open industry standards for ensuring the integrity and privacy of communications and to ensure that only authorized users can access resources in a Service Bus domain. It uses the underlying WebLogic security framework as building blocks for its security services.

Service Bus uses Oracle Platform Security Services (OPSS) and Oracle Web Services Manager (OWSM) as the building blocks for higher-level security services including authentication, identity assertion, authorization, role mapping, auditing, and credential mapping. In order to configure Service Bus access security, you must first configure Oracle WebLogic Server security. Service Bus uses OWSM to provide a policy framework to manage and secure web services consistently across your organization.

Note:

Oracle Web Services Manager (OWSM) is the Web Services security mechanism used by Oracle Service Bus. All newly created resources, such as business services and proxy services, use OWSM policies for security. WLS 9 policies are deprecated, and cannot be used to configure security for a new Service Bus resource.

However, you can import resources already configured with WLS 9 policies into your Service Bus project. You cannot edit or modify these WLS 9policies, but you can replace them with OWSM policies.

This chapter includes the following sections:

47.1 Inbound Security

Inbound security ensures that Service Bus proxy services handle only the requests that come from authorized clients. (By default, any anonymous or authenticated user can connect to a proxy service.) It can also ensure that no unauthorized user has viewed or modified the data as it was sent from the client.

Proxy services can have two types of clients: service consumers and other proxy services. Figure 47-1 illustrates that communication between proxy services and their clients is secured by inbound security, while communication between proxy services and business services is secured by outbound security.

Figure 47-1 Inbound and Outbound Security

Description of "Figure 47-1 Inbound and Outbound Security"

You set up inbound security when you create proxy services and you can modify it as your needs change. For outward-facing proxy services (which receive requests from service consumers), consider setting up strict security requirements such as two-way SSL over HTTPS.

If a proxy service uses public key infrastructure (PKI) technology for digital signatures, encryption, or SSL authentication, create a service key provider to provide private keys paired with certificates. For more information, see Working with Service Key Providers.

For each proxy service, you can configure the following inbound security checks:

Transport-level security applies security checks as part of establishing a connection between a client and a proxy service. The security requirements that you can impose through transport-level security depend on the protocol that you configure the proxy service to use.

For example, for proxy services that communicate over the HTTP protocol, you can require that all clients authenticate against a database of users that you create in Fusion Middleware Control. You then create an access control policy that specifies conditions under which authenticated users are authorized to access the proxy service.

Service Bus also supports client-specified custom authentication tokens for inbound transport-level requests.

For information about configuring transport-level security for each supported protocol, see Configuring Transport-Level Security.
Custom Authentication for message-level security. Service Bus supports client-specified custom authentication credentials for inbound transport-level and message-level requests. The custom authentication credentials can be in the form of a custom token, or a user name and password.

For information on configuring custom authentication transport- and message-level security, see Configuring Custom Authentication.
Message-level security (for proxy services that are web services) is part of the WS-Security specification. It applies security checks before processing a SOAP message or specific parts of a SOAP message.

Part of the configuration for message-level security can be embedded in the WSDL document and WS-Policy document that are associated with the web service. These documents specify whether SOAP messages must be digitally signed and encrypted and which web service operations can be invoked only by authorized users.

Message protection involves encrypting the message for message confidentiality and signing the message for message integrity. OWSM predefined policies and any policy you create using one of the message-protection assertion templates provide the options for message confidentiality, message integrity, or both.

If a proxy service or business service uses a WS-Policy statement to secure access to one or more of its operations, and if you have configured the service as an active intermediary (as opposed to a pass-through service), you use the Oracle Service Bus Console to create a message-level access control policy. The policy specifies conditions under which users, groups, or security roles are authorized to invoke the protected operations.

For more information about configuring message-level security, see Configuring Message-Level Security for Web Services.

47.2 Outbound Security

Outbound security secures communication between a proxy service and a business service. Most of the tasks that you complete for outbound security are for configuring proxy services to comply with the transport-level or message-level security requirements that business services specify.

For example, if a business service requires user name and password tokens, you create a service account, which either directly contains the user name and password, passes along the user name and password that was contained in the inbound request, or provides a user name and password that depend on the user name that was contained in the inbound request. For more information, see Working with Service Accounts.

If a business service requires the use of PKI technology for digital signatures, or SSL authentication, you create a service key provider, which provides private keys paired with certificates. For more information, see Working with Service Key Providers.

47.3 Options for Identity Propagation

A key group of decisions that you must make when designing security for Service Bus is how to handle (propagate) the identities that clients provide. You can configure Service Bus to do any of the following:

Authenticate the credentials that clients provide
Perform authorization checks
Pass client credentials to business services unchanged
Map client credentials to a different set of credentials that a business service can authenticate and authorize
Bridge between security technologies

Table 47-1 describes the decisions that affect how Service Bus propagates client identities to business services.

Table 47-1 Options for Identity Propagation

Decision	Description
Which type of credentials do you require clients to provide?	For transport-level security, Service Bus adapts to your existing security requirements. Clients of Service Bus can supply user name and password tokens, SSL certificates, or any other type of custom authentication token that is supported by an Identity Assertion provider that you configure. For message-level security, Service Bus supports the Username Token, X.509 Token, any other type of custom authentication token that is supported by an Authentication or Identity Assertion provider that you configure, and SAML Token profiles (see Using Security Providers). If you are establishing security requirements for a new business service that uses Web Services Security, Oracle recommends that you require clients to provide SAML tokens. SAML is the emerging standard for propagating user identities within web services. See Using SAML with Oracle Service Bus.
Do you require Service Bus to authenticate clients or to simply pass the client-supplied credentials to business services for authentication?	When you require clients to authenticate with Service Bus, you add an additional layer of security. In general, the more security layers you add, the more secure you make a domain. To enable Service Bus to authenticate users, you must create user accounts in Fusion Middleware Control. If your set of users is very large, you must consider whether maintaining a large database of user accounts is worth the effort.
If Service Bus authenticates clients that provide X.509 tokens or SAML tokens, which Service Bus user maps to the tokens?	Oracle recommends that you require clients to authenticate with Service Bus and that you modify the default access-control policies to allow (authorize) only specific, authenticated users access to your proxy services. To authenticate and authorize clients who supply X.509 certificates, SAML tokens, or other types of credentials other than user names and passwords, you must configure an Identity Assertion provider that maps the client's credential to a Service Bus user. Service Bus will use this user name to establish a security context for the client.
If Service Bus authenticates clients that provide custom authentication tokens, which Service Bus user maps to the tokens?	Oracle recommends that you require clients to authenticate with Service Bus and that you modify the default access-control policies to authorize only specific, authenticated users to have access to your proxy services. To authenticate and authorize clients who supply custom authentication tokens other than user names and passwords, you must configure an Identity Assertion provider that maps the client's credential to a Service Bus user. Service Bus will use this user name to establish a security context for the client.
If Service Bus authenticates clients that provide user name and password tokens, decide whether you want to: Pass the client's user name and password to the business service Map the client's user name to a new user name and password and pass the new credentials to the business service	If a custom user name/password token is used, as described in Understanding Custom Authentication Tokens, then the user name and password in the custom token can be used for outbound HTTP basic or outbound WS-Security Username Token authentication if a pass-through service account is used. If you pass the client-supplied user name and password to the business service, then clients are responsible for maintaining the credentials that the business service requires. If the business service changes its security requirements, then you must notify each client to make corresponding changes. If you expect a business service to change its requirements frequently, then consider mapping the credentials that clients supply to the credentials that the business service requires. The more clients for a business service, the more work will be required to maintain this credential mapping.

Table 47-2 describes all combinations of the requirements that you can impose for inbound and outbound transport-level security.

Table 47-2 Combinations of Transport-Level Security Requirements

This Inbound Requirement...	Can Be Used With This Outbound Requirement...	How to Configure
Client supplies user name and password in the HTTP header and Service Bus authenticates the client.	Pass the client's credentials in an HTTP header.	Configure inbound HTTP security. See Configuring Inbound HTTP Security: Main Steps. Be sure to add the client's user name to the Service Bus Security Configuration module. Configure outbound HTTP security. See Configuring Outbound HTTP Security: Main Steps. Be sure to create a pass-through service account and attach the account to the business service.
Same as previous requirement.	Map the client's credentials to a different Service Bus user and pass the new credentials in an HTTP header.	Configure inbound HTTP security. See Configuring Inbound HTTP Security: Main Steps. Be sure to add the client's user name to the Service Bus Security Configuration module. Configure outbound HTTP security. See Configuring Outbound HTTP Security: Main Steps. Be sure to create a user-mapping service account and attach the account to the business service.
Client supplies user name and password in the HTTP header and Service Bus does not authenticate the client.	Pass the client's credentials in an HTTP header.	Configure inbound HTTP security. See Configuring Inbound HTTP Security: Main Steps. Be sure to configure the proxy service for HTTP, no authentication or HTTPS, one-way SSL, no authentication. Configure outbound HTTP security. See Configuring Outbound HTTP Security: Main Steps. Be sure to configure the business service for HTTP basic authentication or HTTPS, one-way SSL, basic authentication. Also create a pass-through service account and attach the account to the business service.
Client supplies custom authentication token in the HTTP header. Service Bus authenticates the client.	Map the client's credentials to a different Service Bus user and pass the new credentials in an HTTP header.	Configure inbound HTTP security. See Configuring Inbound HTTP Security: Main Steps. Be sure to add the client's user name to the Service Bus Security Configuration module. Configure outbound HTTP security. See Configuring Outbound HTTP Security: Main Steps. Be sure to create a user-mapping service account and attach the account to the business service.
Any form of local authentication (HTTP or HTTPS basic, HTTPS client certificate with credential mapping)	Pass the client's credentials to an EJB over RMI. The EJB container authenticates the user.	Create a pass-through service account and attach the account to the business service. See Working with Service Accounts.

Table 47-3 describes all combinations of the requirements that you can impose for inbound and outbound message-level security. In some cases, the inbound requirement for transport-level security affects the requirements that you can impose for outbound message-level security.

Table 47-3 Combinations of Message-Level Security Requirements

This Inbound Requirement...	Can Be Used With This Outbound Requirement...	How to Configure
Client supplies user name and password, or custom authentication token, in the HTTP header and Service Bus authenticates the client.	Pass the client's credentials in a SOAP header.	Configure inbound HTTP security. See Configuring Inbound HTTP Security: Main Steps. Be sure to create a user account with the client's user name. Create a pass-through service account and attach the account to the business service. See Working with Service Accounts.
Same as previous requirement.	Map the client's credentials to a different Service Bus user and pass the new credentials in a SOAP header.	Configure inbound HTTP security. See Configuring Inbound HTTP Security: Main Steps. Be sure to create a user account with the client's user name. Create a user-mapping service account and attach the account to the business service. See Working with Service Accounts.
Same as previous requirement.	Map the client credentials to a SAML token. Service Bus asserts the user identity.	Configure inbound HTTP security. See Configuring Inbound HTTP Security: Main Steps. Be sure to create a user account with the client's user name. Configure a SAML credential mapping provider. See Mapping Identity to a SAML Token.
Client supplies custom user name and password, or custom authentication token, in the message header or body and Service Bus authenticates the client.	Pass the client's credentials in a SOAP header.	Configure an Authentication or Identity Assertion provider to handle the custom token or user name and password. Be sure to create a user account with the client's user name. Create a pass-through service account and attach the account to the business service. See Working with Service Accounts.
Same as previous requirement.	Map the client's credentials to a different Service Bus user and pass the new credentials in a SOAP header.	Configure an Authentication or Identity Assertion provider to handle the custom token or user name and password. Be sure to create a user account with the client's user name. Create a user-mapping service account and attach the account to the business service. See Working with Service Accounts.
Same as previous requirement.	Map the client credentials to a SAML token. Service Bus asserts the user identity.	Configure an Authentication or Identity Assertion provider to handle the custom token or user name and password. Be sure to create a user account with the client's user name. Configure a SAML credential mapping provider. See Mapping Identity to a SAML Token.
Client supplies user name and password in the HTTP header and Service Bus does not authenticate the client.	Pass the client's credentials in a SOAP header.	Configure inbound HTTP security. See Configuring Inbound HTTP Security: Main Steps. Be sure to configure the proxy service for HTTP, no authentication or HTTPS, one-way SSL, no authentication. Configure outbound HTTP security. See Configuring Outbound HTTP Security: Main Steps. Be sure to configure the business service for HTTP basic authentication or HTTPS, one-way SSL, basic authentication. Also create a pass-through service account and attach the account to the business service.
Client supplies a certificate as part of HTTPS client certificate authentication (two-way SSL) and Service Bus authenticates the client.	Map the client credentials to a SAML token. Service Bus asserts the user identity.	Configure inbound HTTP security. See Configuring Inbound HTTP Security: Main Steps. Configure a SAML credential mapping provider. See Mapping Identity to a SAML Token.
An active intermediary proxy service enforces Web-Services Security with the User Name Token Profile.	Encode the credentials as a user name and password token in the SOAP message.	Create an active intermediary proxy service with a WS-Policy statement that requires passwords (not password digests). See Creating an Active Intermediary Proxy Service: Main Steps.
Same as previous requirement.	Encode the credentials as a SAML token in the SOAP message.	Create an active intermediary proxy service with a WS-Policy statement that requires passwords. See Creating an Active Intermediary Proxy Service: Main Steps. Configure a SAML credential mapping provider. See Mapping Identity to a SAML Token.
An active intermediary proxy service enforces Web-Services Security with the X.509 Token Profile.	Encode the credentials as a SAML token in the SOAP message.	Create an active intermediary proxy service with a WS-Policy statement that requires digital signatures and optionally requires authentication with an X.509 token. See Creating an Active Intermediary Proxy Service: Main Steps. Configure a SAML credential mapping provider. See Mapping Identity to a SAML Token.
An active intermediary proxy service enforces Web-Services Security with the SAML Token Profile.	Generate a new SAML token in the outbound SOAP message.	Create an active intermediary proxy service with a WS-Policy statement that requires a SAML token. See Authenticating SAML Tokens in Proxy Service Requests. Configure a SAML credential mapping provider. See Mapping Identity to a SAML Token.
A pass-through proxy service, which can pass user names and passwords, X.509 tokens, or SAML tokens.	A business service that uses either the User Name Token Profile, the X.509 Token Profile, or the SAML Token Profile.	Create a pass through proxy service. See Creating an Active Intermediary Proxy Service: Main Steps. Create a business service that enforces one of the token profiles. See Configuring Business Service Message-Level Security: Main Steps or Configuring SAML Pass-Through Identity Propagation.

For inbound Tuxedo requests, you can configure any of the following security requirements:

Encode the client's credentials in an outbound call to a Tuxedo service.
Encode the client's credentials in an outbound SOAP message as either a user name token or a SAML token.
Map the client's credentials to a different Service Bus user and pass the new credentials in an outbound HTTP header.
Map the client's credentials to a different Service Bus user and pass the new credentials to an EJB over RMI. The EJB container authenticates the user.

For information about using Tuxedo with Service Bus, see Using the Tuxedo Transport.

47.3.1 Using a Service Account with Business Service when Attaching OWSM Policies

The following out-of-the-box OWSM policies support using service accounts:

oracle/**_username_token_**_client_policy
oracle/wss11_saml_token_identity_switch_with_message_protection_client_policy
oracle/**_saml*_**_client_policy (The subject.precedence property has to be set to false)

The following out-of-the-box OWSM policy assertions support service accounts:

oracle/**_username_token_**_client_template
oracle/**_saml*_**_client_template (The subject.precedence property has to be set to false)

47.3.2 Example: Authentication with a User Name Token

Figure 47-2 illustrates how user identities flow through Service Bus when you configure Service Bus as follows:

Require clients to provide user names and passwords in their requests

You can require web services clients to provide credentials at the transport level, the message level, or both. If you require clients to provide credentials at both levels, Service Bus uses the message-level credentials for identity propagation and credential mapping.
Authenticate clients

Figure 47-2 How Service Accounts Are Used

Description of "Figure 47-2 How Service Accounts Are Used"

The illustration begins with the inbound request and ends with the outbound request:

A client sends a request to a proxy service. The request contains the user name and password credentials.

Clients can send other types of tokens for authentication, such as an X.509 certificate or a custom authentication token. To authenticate and authorize clients who supply X.509 certificates, SAML tokens, or other types of credentials other than user names and passwords, you must configure an Identity Assertion provider that maps the client's credential to a Service Bus user. Service Bus will use this user name to establish a security context for the client.
The proxy service asks the domain's authentication provider if the user exists in the domain's authentication provider store.

If the user exists, the proxy service asks the domain's authorization provider to evaluate the access control policy that you have configured for the proxy service.
If the proxy service's access control policy allows the user access, the proxy service processes the message. As part of generating its outbound request to a business service, the proxy service asks the business service to supply the user name and password that the business service requires.

The business service asks its service account for the credentials. Depending on how the service account is configured, it does one of the following:
- Requires the proxy service to encode a specific (static) user name and password.
- Requires the proxy service to pass along the user name and password that the client supplied.
- Maps the user name that was returned from the authentication provider to some other (remote) user name, then requires the proxy service to encode the remote user name.
The proxy service sends its outbound request with the user name and password that was returned from the service account.

47.4 Administrative Security

To secure access to administrative functions, such as creating proxy services or business services, Service Bus provides security roles with pre-defined access privileges. See "Understanding Oracle Service Bus Application Security" in Administering Oracle Service Bus for more information on these roles.

A security role is an identity that can be dynamically conferred upon a user or group at runtime. You cannot change the access privileges for these administrative security roles, but you can change the conditions under which a user or group is in one of the roles.

The Service Bus roles have permission to modify only Service Bus resources; they do not have permission to modify WebLogic Server or other resources on WebLogic Server. When assigning administrative users to roles, assign at least one user to the WebLogic Server Admin role. The WebLogic Server security roles are described in "Roles" in Administering Oracle Service Bus.

47.5 Access Control Policies

Access control determines who has access to the resources in Service Bus. An access control policy specifies conditions under which users, groups, or roles can access a proxy service. For example, you can create a policy that always allows users in the GoldCustomer role to access a proxy service and that allows users in the SilverCustomer role to access the proxy service only after 12pm on weeknights.

An access control policy is an association between a WebLogic resource and one or more users, groups, or security roles. A security policy protects the WebLogic resource against unauthorized access. Access control policies are boolean expressions assigned to specific resources. When there is an attempt to access the resource, the expression is evaluated. The expression consists of one or more conditions joined by boolean operators, such as a role (operator) and access time (8 am to 5 pm). For more information about access control policies, see "Security Fundamentals" in Understanding Security for Oracle WebLogic Server.

Service Bus relies on WebLogic Server security realms to protect its resources. Each security realm consists of a set of configured security providers, users, groups, security roles, and (access control) security policies. To access any resources belonging to a realm, a user must be assigned a security role defined in that realm, as described in "Configuring Oracle Service Bus Administrative Security" in Administering Oracle Service Bus. When a user attempts to access an Service Bus resource, WebLogic Server authenticates and authorizes the user by checking the security role assigned to the user in the relevant security realm and relevant security policy.

Note:

Only a WebLogic Server administrator can define security policies or edit security roles in Fusion Middleware Control.

For all proxy services, you can create a transport-level policy, which applies a security check when a client attempts to establish a connection with the proxy service. Only requests from users who are listed in the transport-level policy are allowed to proceed.

For proxy services that are WS-Security active intermediaries, or that implement message-level custom authentication, you can also create a message-level policy. This type of policy applies a security check when a client attempts to invoke one of the secured operations. Only users who are listed in the message-level policy are allowed to invoke the operation.

You can view and configure security for users, groups, and roles in Fusion Middleware Control.

47.5.1 Configuring Proxy Service Access Control

You can configure transport-level access control for all proxy services. You can also configure access control at the message-level for any WS-Security active intermediary proxy service, or for any proxy service that implements message-level custom authentication,. To configure access control, you must assign an access control policy to the proxy service, either at the transport-level or message-level (or both).

The default transport-level and message-level access control policy for all proxy services is to allow access to all requests. You must assign an access control policy to the proxy service to protect it.

You configure transport-level and message-level access control policies in the Oracle Service Bus Console, as described in Configuring Service Bus Client Access Security.

47.5.2 Access Control Policy Management

Access control policies are persisted in authorization providers, and there is a reference to them in the Service Bus repository.

Access control policies are managed within a Service Bus design session and not outside the session, as was the case in releases prior to 3.0. Because the changes are made within a session, you can commit or discard the changes as with other resources.

Although ACLs can be managed from the Oracle Service Bus Console, you can change policies outside Service Bus. However, changing policies outside of Service Bus can make the reference in Service Bus out-of-date and invalid.

Therefore, for consistent management, either completely manage ACLs outside of Service Bus sessions (using the authorization provider MBeans or third-party authorization provider tools) or completely manage them from within Service Bus sessions. Any combination of the two approaches can result in an inconsistent view of policies.

Service Bus manages access control policy only for proxy services. You must manage access control policy management for other server resources, such as JMS queues, JNDI entries, EJBs, applications, WebLogic Server instances, data sources, and so forth from the Oracle WebLogic Server Administration Console.

Note:

When you clone a service, ACLs are also cloned in the session. If the user commits the session, ACLs on the service will be committed to the authorization provider. Therefore, when you clone a service you need to decide if you want the clone to have the same ACLs as the original. If you do not want this, then make sure to edit the ACLs of the clone.

47.5.2.1 Deleting a Proxy Service

Deleting a proxy service deletes all of the ACLs referenced by the proxy from the repository controlled by Service Bus, as well as from the appropriate authorization provider.

47.5.2.2 Deleting the Access Control Policy Assigned to a Proxy Service

You can also delete the access control policies assigned to a service without deleting the service. To do this:

Create a session.
From the View a Proxy Service > Security tab, use the edit Transport Access Control option to delete the policies.
Commit the session.

47.5.2.3 Moving or Renaming a Proxy Service

Renaming a proxy service correctly moves all of the policies. You need only rename or move the service in a Service Bus session.

47.5.2.4 Renaming a Proxy Service Operation

When an operation is renamed, the existing operation is transparently deleted and a new operation is created.

However, when an operation name is changed by changing the WSDL file, Service Bus considers any policies for the old operation to be invalid, removes the reference from the Service Bus repository, and deletes the policies from the appropriate authorization provider.

In this case Service Bus does not know that the old operation is renamed to the new operation, and it does not add anything new for the new operation. That is, Service Bus considers that there are no policies for this new operation.

You need to add the appropriate policy to the new operation manually. You can do this in the same session as the rename of operation, after the rename is done.

47.6 Configuring the Oracle WebLogic Security Framework: Main Steps

Many of the initial configuration tasks for Service Bus security require you to work in the Oracle WebLogic Server Administration Console to configure the WebLogic security framework. After these initial tasks, you can complete most security tasks from the Oracle Service Bus Console.

To configure the WebLogic security framework for Service Bus:

If you plan to use SSL as part of transport-level security, do the following:
1. In the Oracle WebLogic Server Administration Console, configure identity and trust. See "Configuring Identity and Trust" and "Important Information Regarding Cross-Domain Security Support" in Administering Security for Oracle WebLogic Server.
2. In the Oracle WebLogic Server Administration Console, configure SSL. See "Configuring SSL" in Administering Security for Oracle WebLogic Server.
Oracle recommends the following for your SSL configuration:
- If you configure two-way SSL, you must choose between two modes: Client Certificate Requested But Not Enforced or Client Certificates Requested and Enforced. Oracle recommends that whenever possible you choose Client Certificate Requested and Enforced. For more information, see "Secure Sockets Layer (SSL)" in Understanding Security for Oracle WebLogic Server.
- In a production environment, make sure that Host Name Verification is enabled. See "Using Host Name Verification" in "Configuring SSL" in Administering Security for Oracle WebLogic Server.

In the Oracle WebLogic Server Administration Console, configure authentication providers, which your proxy services use for inbound security.

Table 47-4 describes the authentication providers that are commonly configured for Service Bus. For a description of all authentication providers that you can configure, see "Security Providers" in Administering Security for Oracle WebLogic Server.

Table 47-4 Authentication Providers

If You Require Clients to Provide...	Configure...
Simple user names and passwords	The WebLogic Authentication provider and use Fusion Middleware Control to enter the user names and passwords of the clients that you want to allow access. Note: As described in Configuring Authentication Providers, Oracle recommends that you use the default WebLogic Authentication provider for all WebLogic Server and Service Bus administrative accounts. See "Creating Oracle Service Bus Users" in Administering Oracle Service Bus.
X.509 tokens for inbound HTTPS and two-way SSL authentication	All of the following: The WebLogic Identity Assertion provider, which can validate X.509 tokens but does not by default. Make sure that you enable this provider to support X.509 tokens. In addition, enable this provider to use a user name mapper. See "Identity Assertion and Tokens" in Understanding Security for Oracle WebLogic Server. WebLogic CertPath Provider, which completes and validates certificate chains by using trusted Certificate Authority based checking.
Custom authentication and user name/password tokens for inbound HTTP and message-level authentication	An Identity Assertion provider, possibly user-written or from a third-party, that can validate the token type. Make sure that you enable this provider to support the token.
X.509 tokens for inbound Web Services Security X.509 Token Authentication	If any of your proxy services or business services are web services that use abstract WS-Policy statements, you must also configure the following: In the Web Service Security configuration named `__SERVICE_BUS_INBOUND_WEB_SERVICE_SECURITY_MBEAN__` add the `UseX509ForIdentity` property and set it to `true`. See "Use X.509 Certificates to Establish Identity" in the Oracle WebLogic Server Administration Console Online Help.
SAML tokens	All of the following: WebLogic SAML Identity Assertion Provider V2, which authenticates users based on Security Assertion Markup Language 1.1 (SAML) assertions. WebLogic SAML Credential Mapping Provider V2, which maps Service Bus users to remote users.

If needed, in the Oracle WebLogic Server Administration Console, configure one or more Identity Assertion providers to handle the token types, such as X.509 or custom token types, for which you require support. For a description of all Identity Assertion providers that you can configure, see "Security Providers" in Administering Security for Oracle WebLogic Server.
If you plan to create proxy services or business services that require WS-Security digital signatures on inbound requests, enable the Certificate Registry provider, which is a Certification Path provider that validates inbound certificates against a list of certificates that you register.

See "Configure Certification Path Providers" in the Oracle WebLogic Server Administration Console Online Help.
If you configure message-level security (in inbound requests or outbound requests) to require user name and password tokens, and if you want messages to provide a password digest instead of cleartext passwords, do the following:
1. In the Oracle WebLogic Server Administration Console, find the two Web Service Security configurations that Service Bus provides and set the value of the UsePasswordDigest property to true.
  
  The Service Bus Web Service Security configurations are named:
  
  __SERVICE_BUS_INBOUND_WEB_SERVICE_SECURITY_MBEAN__ and
  
  __SERVICE_BUS_OUTBOUND_WEB_SERVICE_SECURITY_MBEAN__
  
  For information on setting the values in Web Service Security configurations, see "Use a Password Digest in SOAP Messages" in the Oracle WebLogic Server Administration Console Online Help.
2. For each authentication provider that you configured, in the Oracle WebLogic Server Administration Console, select the Password Digest Enabled check box.
3. For each Identity Assertion provider that you configured, in the Oracle WebLogic Server Administration Console set wsse:PasswordDigest as one of the active token types.
If you plan to create a service key provider (which passes key-certificate pairs in outbound requests), use the Oracle WebLogic Server Administration Console to configure a PKI credential mapping provider. In any WebLogic Server domain that hosts Service Bus, you can configure at most one PKI credential mapping provider.

A PKI credential mapping provider maps Service Bus service key providers to key-pairs that can be used for digital signatures and encryption (for Web Services Security) and for outbound SSL authentication. For more information, see "Configuring a PKI Credential Mapping Provider" in Administering Security for Oracle WebLogic Server.

You store the key-pairs that the PKI credential mapping provider uses in a keystore. You can store the PKI credential mappings in WebLogic Server's identity keystore or in a separate keystore. Configure each WebLogic Server instance to have access to its own copy of each keystore. All entries referred to by the PKI credential mapper must exist in all keystores (same entry with the same alias). For information about configuring keystores in WebLogic Server, see "Identity and Trust" in Understanding Security for Oracle WebLogic Server.

Note:

When you create a Service Bus domain, by default the domain contains a user name/password credential mapping provider, which you can use if you need credential mapping for user names and passwords. In addition to this user name/password credential mapping provider, you can add one PKI credential mapping provider. A Service Bus domain can contain at most one user name/password credential mapping provider, one PKI credential mapping provider, and multiple SAML credential mapping providers.
If you want to enable security auditing, do the following:
1. In the Oracle WebLogic Server Administration Console, configure an auditing provider. See "Configuring the WebLogic Auditing Provider" in Administering Security for Oracle WebLogic Server.
2. To enable auditing of events related to WS-Security, when you start each Service Bus server, include the following Java option in the server's startup command:
```
-Dcom.bea.wli.sb.security.AuditWebServiceSecurityErrors=true
```
Service Bus supports the auditing of security events but it does not support configuration auditing, which emits log messages and generates audit events when a user changes the configuration of any resource within a domain or invokes management operations on any resource within a domain. See "Enabling Configuration Auditing" in Administering Security for Oracle WebLogic Server.
If you have not already done so, in the Oracle WebLogic Server Administration Console, activate your changes. If you have made changes that require you to restart WebLogic Server, the Administration Console will indicate that a restart is required. If you see such a message, restart all WebLogic Server instances that host Service Bus so your modifications to the security providers will be in effect for the remaining configuration steps.

47.7 Context Properties Are Passed to Security Providers

Context properties provide a way (the ContextHandler interface) to pass additional information to the WebLogic Security Framework so a security provider can obtain contextual information beyond what is provided by the arguments to a particular provider method. A ContextHandler is a high-performing WebLogic class that obtains additional context and container-specific information.

Service Bus makes use of the ContextHandler interface and passes several context properties to the security framework for transport-level and message-level authentication, transport-level and message-level access control, and credential mapping.

This section describes the situations in which Service Bus-specific context properties are used.

47.7.1 Context Properties for HTTP Transport-Level Authentication

When an HTTP proxy service is configured for authentication, the HTTP transport provider passes a Service Bus implementation of the WebLogic Server ContextHandler. There is no user configuration required for this feature.

The ContextHandler properties in Table 47-5 are passed at runtime, under the following conditions:

To Authentication providers, if the proxy is configured for HTTP basic authentication.
To Identity Assertion providers, if the proxy is configured for client certificate identity assertion.
To Identity Assertion providers, if the proxy is configured for HTTP custom token identity assertion.

Table 47-5 ContextHandler Properties for HTTP Transport Authentication

Property Name	Type	Property Value
com.bea.contextelement.alsb.service-info	com.bea.wli.sb.services.ServiceInfo	An instance of `ServiceInfo` that contains information about the proxy service.
com.bea.contextelement.alsb.transport.endpoint	com.bea.wli.sb.transports.TransportEndPoint	This is the HTTP or HTTPS endpoint.
com.bea.contextelement.alsb.transport.http.http-request	javax.servlet.http.HttpServletRequest	This is the `HttpServletRequest` object.
com.bea.contextelement.alsb.transport.http.http-response	javax.servlet.http.HttpServletResponse	This is the `HttpServletResponse` object.

47.7.2 ContextHandler Properties for Access Control and Custom Authentication

The ContextHandler properties for access control and message-level custom authentication are passed at runtime, under the following conditions:

To Authentication providers when performing message-level custom user name/password authentication.
To Identity Assertion providers when performing message-level custom token identity assertion.
To Authorization providers when performing transport-level or message-level access control.

Table 47-6 ContextHandler Properties for Custom Authentication and Access Control

Property Name	Type	Property Value
com.bea.contextelement.alsb.router.ProxyService	java.lang.String	The service name (full-name; for example `/myproject/myfolder/svc-a`).
com.bea.contextelement.alsb.router.ServiceUri	java.net.URI	The base URI from which the message was received.
com.bea.contextelement.alsb.router.inbound.TransportProvider	java.lang.String	The Id of the transport provider that received this message.
com.bea.contextelement.alsb.router.inbound.request.MessageId	java.lang.String	This is the transport provider-specific message identifier. Ideally it should uniquely identify the message among other messages going through the Service Bus runtime. However, Service Bus does not depend on the message Id being unique. The message Id is added to the message context and thus visible in the pipeline.
com.bea.contextelement.alsb.router.inbound.request.CharacterEncoding	java.lang.String	Character encoding used in the message payload, or null.
com.bea.contextelement.wli.Message	java.io.InputStream	The request message as an input stream.

47.7.3 Additional Transport-Specific Context Properties

In addition to the properties in Table 47-7, other transport-specific properties may be present. For each transport request-header (see the transport SDK), a property with the name

com.bea.contextelement.alsb.router.inbound.request.headers.
<provider-id>.<header-name>

is present, where provider-id is the transport provider id, and header-name is one of the request-headers declared in the provider's schema file. The type and semantics of these properties are transport-specific. For HTTP proxy services, the message-level security properties inTable 47-3 are also available.

Table 47-7 Additional ContextHandler Properties for HTTP Proxy Services

Property Name	Type	Property Value
com.bea.contextelement.alsb.router.inbound.request.metadata.http.relative-URI	java.lang.String	The relative URI of the request.
com.bea.contextelement.alsb.router.inbound.request.metadata.http.query-string	java.lang.String	The query string that is contained in the request URL after the path.
com.bea.contextelement.alsb.router.inbound.request.metadata.http.client-host	java.lang.String	The fully qualified name of the client that sent the request.
com.bea.contextelement.alsb.router.inbound.request.metadata.http.client-address	java.lang.String	The Internet Protocol (IP) address of the client that sent the request.

47.7.4 Administrator-Supplied Context Properties for Message-Level Authentication

Both custom user name/password authentication and custom token authentication allow users (who are in the IntegrationAdmin or IntegrationDeployer roles) to pass additional context information to the security provider in the Context Properties field on the Security tab.

You can configure additional context properties by entering the Property Name as a literal string, and the Value Selector as a valid XPath expression. (XPath expressions can also be literal strings.)

The XPath expression is evaluated at runtime against the same message part that is used for the custom token or custom user name/password. That is, the Value Selector XPath expressions are evaluated against the header for SOAP-based proxy services, and against the body for non-SOAP-based proxy services.

47.7.5 Security Provider Must Have Knowledge of the Property Name

A ContextHandler is essentially a name/value list and, as such, it requires that a security provider know what names to look for. Therefore, for both transport- and message-level custom authentication, the XPath expressions are evaluated only if an Authentication provider or Identity Assertion provider asks for the value of one of these properties.

This means that your configured Authentication or Identity Assertion provider must explicitly know which property names to request through the ContextHandler.getValue(propertyName) method. The only way to satisfy this requirement is for you, or a third party, to write a custom Authentication or Identity Assertion provider.

The following example shows how to get the HttpServletRequest property from a provider that you write.

Example - Getting the HttpServletRequest Property

:
Object requestValue = handler.getValue("com.bea.contextelement.alsb.transport.http.http-request");
if ((requestValue == null) || (!(requestValue instanceof HttpServletRequest)))
return;
HttpServletRequest request = (HttpServletRequest) requestValue;
log.println(" " + HTTP_REQUEST_ELEMENT + " method: " + request.getMethod());
log.println(" " + HTTP_REQUEST_ELEMENT + " URL: " + request.getRequestURL());
log.println(" " + HTTP_REQUEST_ELEMENT + " URI: " + request.getRequestURI());
return;

If the security provider does not need the value of the user-defined property, then the XPath expression is not evaluated.

47.7.6 WebLogic Server Administrative Channel is Supported

This release of Service Bus can use the WebLogic Server administrative channel.

As described in "Understanding Network Channels" in Administering Server Environments for Oracle WebLogic Server, a WebLogic Server network channel is a configurable resource that defines the attributes of a network connection to WebLogic Server.

You can configure a particular type of network channel, called an administrative channel, to isolate "administration" and application ("business") traffic in a WebLogic domain. The administrative channel is a secured channel that accepts only SSL connections.

In Service Bus, business traffic is comprised of all messages sent to and from Service Bus proxy services and business services. SSL business traffic must use the default WebLogic Server secure network channel.

Administration traffic is comprised of all communication with the Oracle WebLogic Server Administration Console, Oracle Service Bus Console, internal traffic within a cluster, and traffic between administration scripts and admin or Managed Servers.

When an administrative channel is enabled in a domain, all of the administration traffic in that domain must go through that channel. Otherwise, the administration traffic also uses the default WebLogic Server secure network channel.

Using the Administrative Channel: Main Steps describes using the administrative channel.

47.7.6.1 Using the Administrative Channel: Main Steps

Complete the following steps to use the administrative channel:

Close any open browser connections to the Oracle Service Bus Console for the domain.

As soon as you activate the administrative channel in WebLogic Server, the Oracle Service Bus Console for the domain becomes unavailable at the current URL. The Help system also becomes unavailable.
Enable the domain-wide administration port in the Oracle WebLogic Server Administration Console (which configures an administrative channel on your behalf), or explicitly create an administrative channel. Both of these tasks are described in "Configuring Network Resources" in Administering Server Environments for Oracle WebLogic Server.

The domain-wide administration port control is located on the Domain > Configuration > General page. The default administration port is 9002.

Be sure to activate the change.
Open a browser connection to the new URL for the Oracle Service Bus Console for the domain.

The URL is https://hostname:9002/servicebus if you enabled the domain-wide administration port and accepted the default port number.
Revise any startup scripts that refer to the old URL. If you are using the Windows graphical interface to launch the Oracle Service Bus Console for the domain, revise the shortcut property to reflect the new URL.

47.8 Using Security Providers

This section provides instructions on using security providers with Service Bus.

This section includes the following topics:

47.8.1 Configuring Authentication Providers

Check the provided WebLogic Server authentication providers to see if one meets your needs. WebLogic Server includes a broad array of Authentication providers, including the following:

The WebLogic Authentication provider accesses user and group information in WebLogic Server's embedded LDAP server. This is the default out-of-the-box authentication provider. This provider is not optimized for use with very large numbers of users.
LDAP Authentication providers access external LDAP stores. You can use an LDAP Authentication provider to access any LDAP server. WebLogic Server provides LDAP Authentication providers already configured for Open LDAP, Oracle Directory Server Enterprise Edition, Microsoft Active Directory, and Novell NDS LDAP servers.
RDBMS Authentication providers access external relational databases. WebLogic Server provides three RDBMS Authentication providers: SQL Authenticator, Read-only SQL Authenticator, and Custom RDBMS Authenticator.
The SAML Authentication provider, which authenticates users based on Security Assertion Markup Language 1.1 (SAML) assertions.

See "Improving the Performance of WebLogic and LDAP Authentication Providers" in Administering Security for Oracle WebLogic Server for guidance on improving the performance of these authentication providers.

As described in "Why Customize the Default Security Configuration" in Administering Security for Oracle WebLogic Server, you may want to use an Authentication provider that accesses a database other than WebLogic Server's embedded LDAP server. For example, you might want to use a different authentication provider for the majority of user accounts, but continue to use the default authentication provider (embedded LDAP) for Service Bus and WebLogic Server administrative user accounts.

Using the WebLogic Authentication provider for all WebLogic Server and Service Bus administrative user accounts provides reliable access in the event of a network or database problem. Oracle recommends that you use the default WebLogic Authentication provider for all WebLogic Server and Service Bus administrative accounts for this reason.

If one of the bundled Authentication providers meets your needs, see "Configuring Authentication Providers" in Administering Security for Oracle WebLogic Server for instructions on how to configure this Authentication provider in the Oracle WebLogic Server Administration Console.

If none of the Authentication providers included in WebLogic Server suits your needs, you (or a third-party) must first write a custom Authentication provider and then use the Oracle WebLogic Server Administration Console to add that provider to the security realm, as described in the following steps:

Note:

Only a broad overview of the required tasks is included here. You will need to consult the WebLogic Server documentation to actually complete the tasks.

To add a provider to a security realm:

"Create Runtime Classes Using the Appropriate SSPIs" (in Developing Security Providers for Oracle WebLogic Server).
"Generate an MBean Type Using the WebLogic MBeanMaker"
"Configure the Custom Authentication Provider Using the Administration Console"

47.8.2 Using a Custom Authorization Provider to Protect Service Bus Resources

You can use Service Bus resources with custom Authorization providers, but those providers must understand the type and format of the Service Bus resources.

There are three possible resource objects for Service Bus that an Authorization provider must be able to detect and handle:

These resource objects are described in the sections that follow.

47.8.2.1 WebLogic Authorization Provider Usage Information

This section briefly describes the WebLogic Server authorization provider SSPI. See "Authorization Providers" in Developing Security Providers for Oracle WebLogic Server for complete information.

You protect resources by binding access control policies to resources using the Oracle Service Bus Console, third-party tools or scripts. The WebLogic Server Security Service Provider Interface (SSPI) requires containers, such as Service Bus, to implement the Resource SPI. These implementations represent concrete resources.

The Authorization provider database contains a map from resource to policy. When an attempt is made to access a resource, the container calls the runtime SSPI to get an access control decision. The container passes a resource instance indicating which resource is being accessed.

An Authorization provider has one method, getAccessDecision(). The getAccessDecision() method obtains the implementation of the AccessDecision SSPI. The AccessDecision SSPI itself has one method, isAccessAllowed(). isAccessAllowed has five parameters, one of which is the Resource object for which access is being requested.

isAccessAllowed determines if the requestor should be allowed to access the named resource. To do this, the Authorization provider must find the right access control policy to evaluate. The provider must first look for a policy bound to the resource passed in. The lookup can use either the getId() or toString() method as a lookup key, as described in "Looking Up WebLogic Resources in a Security Provider's Runtime Class" in Developing Security Providers for Oracle WebLogic Server. If no policy is found, the Authorization provider must then get the parent resource and look again. This process is repeated until a policy is found or the parent is null, in which case no policy is found. When no policy is found, isAccessAllowed must return false.

This algorithm allows you to create coarse-grained policies that protect all proxy services in a given project or folder, all resources in a project, or all Service Bus proxy services in a Service Bus domain. More specific, finer-grained policies take precedence over coarse-grained policies.

Note:

The Oracle Service Bus Console user interface does not provide pages for protecting proxy services at the folder, project or domain level.

47.8.2.2 ALSBProxyServiceResource Object

The ALSBProxyServiceResource object is used for transport-level and message-level access control to Service Bus proxy services. The ALSBProxyServiceResource resource extends weblogic.security.service.ResourceBase, which itself implements weblogic.security.spi.Resource.

ALSBProxyServiceResource implements the following methods, as described in weblogic.security.spi.Resource:

getType() – Returns the type, where type is "<alsb-proxy-service>"

getKeys() – Returns up to four key-value properties: path, proxy, action, and operation. The properties are defined as follows:

path is the full-name of the proxy service. For example, path=project/folder1/folder2
proxy is the name of the proxy service. For example, proxy=myProxy
action is one of two values, invoke or wss-invoke. For example, action=invoke

The action attribute is used to distinguish between transport-level and message-level access control. invoke is used for transport-level access control. wss-invoke is used for message-level access control; that is, access control on WS-Security active intermediaries or proxies with custom message-level authentication. The operation attribute is only allowed when action is wss-invoke.

operation is the name of the operation to invoke, and is used only when action is wss-invoke. For example, operation=processPO. The operation attribute is only allowed when action is wss-invoke.

An ALSBProxyServiceResource has from 1 to 4 keys. The following table explains how the various combinations protect proxy services. The most specific policies take precedence.

If the Resource Contains These Keys	A Policy Bound to the Resource Protects:
path	The policy protects all proxy services in the given path
path and proxy	The policy protects all access to the given proxy service (transport-level as well as message-level)
path, proxy, and action	If action="invoke": The policy is the transport-level policy to the given proxy If action="wss-invoke": The policy is the message-level policy to the given proxy (for all operations)
path, proxy, action="wss-invoke", and operation	The policy is a message-level policy for the given proxy and operation

getPath() – Gets the path (project and folders) to the proxy service. This is the path where the proxy service exists within the Service Bus configuration framework.

getProxyServiceName() – Gets the name of the proxy service. For example, proxy=myProxy.

getAction() – Gets one of two values, invoke or wss-invoke. For example, action=invoke.

getOperation() – Gets the name of the operation to invoke, and is used only when action is wss-invoke. For example, operation=processPO.

makeParent() – Creates a new ALSBProxyServiceResource object that represents the parent of the current ALSBProxyServiceResource resource. makeParent() uses the path of the proxy service to create the parent.

47.8.2.2.1 ALSBProxyServiceResource Examples

The following examples show various uses of the ALSBProxyServiceResource object.

Using ALSBProxyServiceResource for transport-level access control for proxy project/folder/myProxy:
```
type=<alsb-proxy-service>, path=project/folder, proxy=myProxy, action=invoke
```
Using ALSBProxyServiceResource for message-level access control for operation processPO on proxy project/folder/myProxy:
```
type=<alsb-proxy-service>, path=project/folder, proxy=myProxy, action=wss-invoke, operation=processPO
```

Using the parentage hierarchy for an ALSBProxyServiceResource, from fine-grained to coarse-grained:

type=<alsb-proxy-service>, path=myProject/f1/f2, proxy=myProxy, action=wss-invoke, operation=foo
type=<alsb-proxy-service>, path=myProject/f1/f2, proxy=myProxy, action=wss-invoke
type=<alsb-proxy-service>, path=myProject/f1/f2, proxy=myProxy
type=<alsb-proxy-service>, path=myProject/f1/f2
type=<alsb-proxy-service>, path=myProject/f1
type=<alsb-proxy-service>, path=myProject
type=<alsb-project>, project-name=myProject
type=<alsb-proxy-service>

47.8.2.3 ProjectResourceV2 Object

The ProjectResourceV2 is the root resource for all ALSBProxyServiceResource objects in a given project. ProjectResourceV2 extends ResourceBase.

Setting an access control policy on a ProjectResourceV2 provides a coarse-grained access control policy for all proxy services in the given project that do not have more specific policies.

ProjectResourceV2 has the following methods:

getType() – Returns the type, where type is "<alsb-project>".

getKeys() – Returns the key, where key is "project-name".

getName() – Gets the name of the ProjectResourceV2 object.

makeParent() – There is no parent for an ProjectResourceV2 object. This method therefore returns the object name that was used to create the ProjectResourceV2 object, or null if ProjectResourceV2 does not exist.

47.8.2.4 ConsoleResource Object

The com.bea.wli.security.resource.ConsoleResource object is used for access control to the Oracle Service Bus Console. However, we do not recommend that you set access control policies for ConsoleResource objects using a custom Authorization provider. This is because these policies are subject to change in future Service Bus releases.

We instead recommended that even if you need to use a custom Authorization provider, you also continue to use the WebLogic Server XACML Authorization provider to maintain the policies for the ConsoleResource object. In this case of two Authorization providers, you must also configure an Adjudication provider.

47.8.3 About Errors When Using Security Provider Policies

If you are using a plug-in security provider with WebLogic Server to store policies for use with Service Bus, you may encounter an error that says Service Bus cannot determine whether or not required policies are available.

An error message like that does not necessarily mean the policies do not exist, or that you have a connection or configuration problem with the security provider. Service Bus uses a WebLogic Server SSPI to read policies that security providers can implement. However, the SSPI read functionality is optional. It is possible that a security provider does not allow read access by not implementing this SSPI. In such a case, Service Bus cannot reliably determine whether or not the security provider contains the required policies, even when the required policies could very well exist in the security provider.

To determine whether or not such a warning indicates a real problem, try creating or modifying resources in the Oracle Service Bus Console. Also, try securing a proxy service with an access control policy and test it. For information on configuring an access control policy on a proxy service, see Configuring Service Bus Client Access Security.. If you can successfully create or manipulate resources as well as test a secured proxy service while using the security provider, then the security provider is configured correctly and you can safely ignore the error message.