6 Configuring the Web Services Signaling Server Unit

This chapter describes how to configure an Oracle Communications Service Controller Web Services Signaling Server Unit (SSU) using the Administration Console.

About the Web Service SSU

The Web Services SSU enables Service Controller Processing Tier components to communicate with external entities using SOAP or REST over HTTP. Service Controller can act as a Web services server or client to external entities through the Web Services SSU.

In general, you control Web service traffic through the Service Controller Signaling Tier using the following Web Services SSU components:

  • Incoming routing rules, which map a request URL addressed by an incoming request to an internal service or IM.

  • Outgoing routing rules, which specify external Web services to which Service Controller sends service requests.

  • HTTP network access points, which specify connection-level settings for the Web services communications, such as the port on which Service Controller listens for HTTP traffic and security settings for connections.

  • Specific settings for SOAP-based or REST-based HTTP connections.

The Processing Tier components that rely on the Web Services SSU are the Web Services IM (WS-IM) and Service Controller applications, such as Top Up or Subscriber Provisioning. These applications expose SOAP APIs that clients use to configure and manage their services.

Enabling access to the SOAP APIs involves the following general configuration steps:

  1. Opening an HTTP listening port in the Web Services SSU configuration.

  2. Configuring SSL security or authentication requirements for the connection.

  3. Configuring an incoming routing rule that directs incoming client requests to the Web Service endpoint within Service Controller.

This chapter provides information about configuring the Web Services SSU. For more information about a particular SOAP API, see the implementation guide applicable to the Service Controller application, such as Service Controller Subscriber Store User's Guide.

The following procedures describe how to perform a task in the Administration Console.

Configuring Incoming Routing Rules

You use the Incoming Routing Rules tab to define how the Web Services SSU routes incoming Web service messages to internal Service Controller IMs and other applications.

To configure incoming routing rules for Web service messages:

  1. In the navigation tree in the domain navigation pane, expand OCSB.

  2. Expand Signaling Tier.

  3. Expand the SSU Web Services node.

  4. Click the General item.

  5. In the SSU WS tab, click the Incoming Routing Rules tab.

    The Incoming Routing Rules pane contains a table in which each row represents one Web services endpoint.

  6. Click the New button.

    The New dialog box appears.

  7. In the dialog box, provide values for the fields listed in Table 6-1.

    Table 6-1 Web Services Incoming Routing Rules Parameters

    Field Description

    Name

    A unique name for the routing rule.

    Service Name

    The service name of the Service Controller Web service endpoint.

    Setting this field to Any causes all incoming web service messages to be routed to the specified module instance. This value is generally used to create a rule that routes incoming Web services messages to a default IM in the absence of a more specific routing rule.

    For the incoming routing rules for Service Controller applications that expose SOAP APIs, use the following service names:

    • BalanceManagerService: Use for the routing rule for the Top Up and Balance Manager API service.

    • SubscriberProvisioning: Use for the routing rule for the Subscriber Provisioning API service.

    Alias

    A logical name that specifies the Service Controller IM or application to which the Web Services SSU routes an incoming Web services message. The format differs depending upon whether you are routing to an internal service or an IM.

    The alias has the following format for IMs:

    ssu:IM_instance_name.IM_type@domain_id

    The alias has the following format for internal service:

    ssu:domain_Id/application_id

    Where:

    • IM_instance_name: Name of the destination IM instance. This is the IM name you specified when you added this IM in the IM configuration pane.

    • IM_type: Type of the destination IM instance.

    • domain-id: Name of the Processing Domain or Processing Domain Group where the relevant IM or application is deployed. This parameter is required only when your Service Controller deployment includes two or more Processing Domains.

      Use the name given to the domain when it was created. This name is specified by the axia.domain.id property.

    • application_id: Name of the destination Service Controller application.

      This is a static name assigned to each Service Controller application. This is topup for the Balance Manager API service and provisioning for the Subscriber Provisioning API service.

    For the Service Controller SOAP API services, use the following alias values (given the default domain ID of ocsb):

    • ssu:ocsb/topup: The alias for the Balance Manager API service.

    • ssu:ocsb/provisioning: The alias for the Subscriber Provisioning API service.

  8. Click OK to save the new incoming routing rule configuration.

Configuring Outgoing Routing Rules

You use the Outgoing Routing Rules tab to define how the Web Services SSU routes outgoing Web service messages to external Web service endpoints.

In the rule, you specify the address of each external Web service endpoint and assign an alias to each endpoint. IMs and Service Controller applications use the alias to refer to an external Web service destination.

The Web Services SSU distributes messages among different Web service endpoints that share the same alias using the weighted load strategy. This strategy determines a Web service endpoint that receives a message based on the weight that you assign to the endpoint. The weight determines a relative share of the traffic that the Web service endpoint should receive. For example, you defined two endpoints whose weight is 100 and 200 correspondingly. The endpoint with the weight of 100 receives 1/3 of the traffic, while the endpoint with the weight of 200 receives the remaining 2/3 of the traffic.

If a Web service endpoint fails, the Web Services SSU redistributes the traffic among remaining Web service endpoints according to their weight.

You can define a Web service endpoint that receives traffic if other endpoints whose weight is greater than zero, fail. This endpoint is known as secondary Web service endpoint, and its weight is always zero. If in the example above, you add one more endpoint whose weight is set to zero, the Web Services SSU sends messages to this endpoint only if the endpoints whose weight is set to 100 and 200 correspondingly, fail.

If you define multiple Web service endpoints with secondary priority, the Web Services SSU distributes traffic equally among them.

The weighted load strategy enables you to control the traffic distribution depending on capabilities of Web service endpoints. For example, if a Web service endpoint runs a more powerful server, this endpoint can serve more traffic, then you would set its load weight relatively higher.

To configure outgoing routing rules for Web service messages:

  1. In the navigation tree in the domain navigation pane, expand OCSB.

  2. Expand Signaling Tier.

  3. Expand the SSU Web Services node.

  4. Click the General tab.

  5. In the SSU WS tab, click the Outgoing Routing Rules tab.

    The Outgoing Routing Rules pane contains a table in which each row represents one Web services endpoint.

  6. Click the New button.

    The New dialog box appears.

  7. In the dialog box, provide values for the fields listed in Table 6-2.

    Table 6-2 Web Services Outgoing Routing Rules Parameters

    Field Description

    Name

    A unique routing rule name.

    Alias

    A logical name that you assign to the Web services endpoint.

    Web Service URI

    The Uniform Resource Identifiers (URI) used to address the Web services endpoint. The format of the address is similar to Web Uniform Resource Locators (URLs).

    For example:

    http://webservices.example.com/eventnotification

    Weight

    Specifies the relative load weight for the Web service endpoint.

    Default value: 0

    Heartbeat

    Whether the Web Services SSU periodically checks the Web services endpoint availability. Select ON to activate periodic availability check, or OFF to disable it.

    Hearbeat Method

    The HTTP method used to check endpoint availability. Service Controller supports the GET only.

    If the Heartbeat field to OFF this field is ignored.

    Response Timeout

    The amount of time, in seconds, Service Controller waits for a response from the Web services endpoint before the endpoint is considered unavailable.

    If the Heartbeat field to OFF this field is ignored.

    Active Interval

    The amount of time, in seconds, between consecutive endpoint availability checks if the last availability check showed that the endpoint was available.

    Inactive Interval

    The amount of time, in seconds, between consecutive endpoint availability checks if the last availability check showed that the endpoint was unavailable.

  8. Click OK to save the new outgoing rule configuration.

Configuring HTTP Access Settings

To enable HTTP connections between Service Controller and external entities, you must configure the HTTP connection settings in the Web Services SSU.

The HTTP connection settings specify the port on which Service Controller listens for HTTP requests, timeout settings, security requirements, and general connection settings.

Configuring HTTP Server General Settings

The general HTTP server settings apply to connections to Service Controller through the Web Services SSU that are initiated by an external client.

To specify general timeout settings:

  1. In the navigation tree in the domain navigation pane, expand OCSB.

  2. Expand Signaling Tier.

  3. Expand the SSU Web Services node.

  4. Click the General item.

  5. Click the HTTP tab.

    The General configuration pane under the Server subtab appears.

  6. Set the value of the Timeout field to the maximum number of milliseconds that Service Controller can use to process a request. If this time expires, Service Controller returns an error response to the client.

    Set to any value from 1000 and 60000. The default is 30000.

  7. Click Apply to save your change.

Configuring HTTP Server Network Access Settings

The network access point specifies the port on which the Web Services SSU listens for HTTP traffic, including HTTP traffic in the form of SOAP and REST messages.

To configure HTTP server network access settings:

  1. In the navigation tree in the domain navigation pane, expand OCSB.

  2. Expand Signaling Tier.

  3. Expand the SSU Web Services node.

  4. Click the General item.

  5. Click the HTTP tab.

  6. In the Server subtab, click the Network Access subtab.

  7. Click the New button.

    The New dialog box appears.

  8. In the dialog box, provide values for the fields listed in Table 6-3.

    Table 6-3 HTTP Network Access Parameters

    Field Description

    Server Address

    The local IP address or hostname bound to this HTTP listener.

    Server Port

    An available port number on which the Signaling Server listens for HTTP traffic. Be sure to avoid entering a port number already in use by the system.

    Protocol

    The protocol used for the port, either HTTP or HTTPS for Secure HTTP.

    SSL Client Auth

    Whether to enable SSL client authentication for this access point.

    Set to true to enable SSL client authentication. Enable SSL client authentication only if this network access point uses HTTPS protocol. If enabled, clients attempting to connect to this access point must present a client certificate that matches one in the truststore.

    Set to false to disable SSL client authentication.

    For more information on security, see Service Controller Security Guide.

    Keystore ID

    The identifier of the security keystore for the connection in the Credential Store. Only applicable if this network access point uses HTTPS.

    See Service Controller Security Guide for more information on using the Credential Store.

    Truststore ID

    The identifier of the security truststore in the Credential Store. Only applicable if this network access point uses HTTPS.

    See Service Controller Security Guide for more information on using the Credential Store.

    Target

    The target Signaling Server to which this configuration applies. If empty, it applies to all servers.

  9. Click OK to save the new HTTP access configuration.

Creating or Modifying HTTP Server Security Contexts

You use the Security Context tab to apply authentication requirements to the resources exposed by Service Controller through the Web Services SSU. When authentication is required, Service Controller validates the credentials provided in incoming requests.

Note:

The HTTP server security context applies HTTP Basic Authentication or HTPP Digest Authentication requirements to requests. Alternatively, you can require credentials in the form of Web Service Security (WSSE) UsernameToken credentials. See "Authenticating SOAP Requests with WSSE UsernameToken Credentials" for more information.

You associate a security requirement to a resource by configuring a security context by URI path.

For instance, the default REST root URI context is exposed at /rest. If HTTP Basic Auth is enabled for this address, any resource available under the REST root URI (such as /rest/subscriber) has the same requirement, unless a more specific security context applies to it.

To configure a security context for HTTP access:

  1. In the navigation tree in the domain navigation pane, expand OCSB.

  2. Expand Signaling Tier.

  3. Expand the SSU Web Services node.

  4. Click the General item.

  5. Click the HTTP tab.

  6. In the Server subtab, click the Security Context subtab.

  7. In the Security Context pane, you can either:

    • Click New to create a new context.

    • Select an existing context in the list and click Update to modify its values.

  8. In the dialog box, provide values for the fields listed in Table 6-4.

    Table 6-4 HTTP Security Context Parameters

    Field Description

    Context URI

    The URI to which the security requirement applies.

    Auth Method

    The authentication method applied to the resource. Options are:

    • NONE: No authentication is required.

    • BASIC: HTTP Basic Authentication is required to access the resource.

    • DIGEST: HTTP Digest Authentication is required to access the resource.

    Realm

    The security realm value to be presented to clients who do not provide credentials.

    Username

    The required user name to be included in the requests.

    Credential Key

    A key that identifies the credential in the Credential Store. This key is a name for the credential provided when loading the password associated with the user in the Credential Store.

    See Service Controller Security Guide for more information on the Credential Store.

  9. Click OK to save the new security context configuration.

Configuring HTTP Client Settings

The HTTP client settings apply to outgoing connections. In this case, Service Controller acts as a client to external HTTP servers through the Web Services SSU.

To configure HTTP client settings:

  1. In the navigation tree in the domain navigation pane, expand OCSB.

  2. Expand Signaling Tier.

  3. Expand the SSU Web Services node.

  4. Click the General item.

  5. Click the HTTP tab.

  6. Click the Client tab.

  7. Modify, if required, the default settings for the outgoing connection listed in Table 6-5.

    Table 6-5 HTTP Client Parameters

    Field Description

    Connect Timeout

    The amount of time, in milliseconds, Service Controller allows for establishing an HTTP connection to a remote server. If the timeout expires before receiving data, the connect attempt is abandoned.

    The default value is 50000 milliseconds. Value must be from 1000 to 60000.

    Read Timeout

    The amount of time, in milliseconds, Service Controller allows for reading data from a remote server on the established connection. If the timeout expires, the read attempt is aborted.

    The default value is 30000 milliseconds. Value must be from 1000 to 60000.

  8. Click Apply to save your changes to the configuration.

Configuring SOAP Web Service Access

As an HTTP-based protocol, SOAP is subject to the common HTTP connection settings configured in the HTTP tab. These include, for example, the port on which Service Controller listens for HTTP traffic, Basic Authentication security, and so on. See "Configuring HTTP Access Settings" for information on configuring common HTTP access settings.

In addition, you can configure specific settings that apply to SOAP-based communication with external SOAP clients or servers.

Configuring SOAP Server Settings

The SOAP server settings apply to client connections to Service Controller in which Service Controller acts as the Web Service provider or server front-end. These include connections made to the Subscriber Profile API and Balance Manager API services.

To enable the SOAP services, you must configure HTTP access settings. You can then configure specific settings for SOAP access as described in this section.

Configuring Common SOAP Server Settings

To configure general SOAP access settings:

  1. In the navigation tree in the domain navigation pane, expand OCSB.

  2. Expand Signaling Tier.

  3. Expand the SSU Web Services node.

  4. Click the General item.

  5. Click the SOAP tab.

    The Server settings pane appears.

  6. Verify and, if required, modify the default settings listed in Table 6-6.

    Table 6-6 SOAP Server Parameters

    Field Description

    Root URI

    The path root for the SOAP API services provided by Service Controller. The default is /soap.

    Together with the service location, this root path forms the complete URI for accessing the SOAP resource at the Service Controller Signaling Domain.

    For example, given the default path for the root URI and Subscriber Provisioning service, the full path would be:

    https://hostname:port/soap/SubscriberProvisioning

    Timeout

    The maximum amount of time, in milliseconds, Service Controller may take to generate a response before returning an error response to the client.

    The default value is 10000 milliseconds. Values can be from 1000 to 60000.

  7. Click Apply to save your changes to the configuration.

Configuring the URI Path for a Specific SOAP Service

To view or change the URI path of a SOAP service, follow these steps:

  1. In the navigation tree in the domain navigation pane, expand OCSB.

  2. Expand Signaling Tier.

  3. Expand the SSU Web Services node.

  4. Select the name of the service for which you want to modify the existing URI path, either Subscriber Provisioning or Balance Manager.

  5. In the End Point tab, click the URI context for the service.

  6. Click the Update button.

  7. Set the URI field to the value of the new path. The path value should be preceded by a slash character, as in the default value.

    By default, this is /SubscriberProvisioning for the Subscriber Provisioning SOAP service, and /BalanceManagerService for the Balance Manager SOAP service. Together with the root URI path, this path makes up the URI at which clients address the SOAP service.

  8. Click OK.

See "Authenticating SOAP Requests with WSSE UsernameToken Credentials" for information on configuring the authentication fields for the SOAP service.

Configuring SOAP Client Parameters

The SOAP client settings apply to outgoing connections. In this case, Service Controller acts as a client to external SOAP Web service providers.

To configure SOAP client settings:

  1. In the navigation tree in the domain navigation pane, expand OCSB.

  2. Expand Signaling Tier.

  3. Expand the SSU Web Services node.

  4. Click the General item.

  5. Click the SOAP tab.

  6. Click the Client subtab.

  7. Enter values for the fields listed in Table 6-7.

    Table 6-7 SOAP Client Parameters

    Field Description

    Connect Timeout

    The amount of time, in milliseconds, Service Controller allows for establishing a connection to a remote server. If the timeout expires before Service Controller establishes the connection, the connect attempt is abandoned.

    The default value is 5000. Values can be from 1000 to 60000. To disable time outs, set this value to 0.

    Read Timeout

    The amount of time, in milliseconds, Service Controller allows for reading data from a remote server on an established connection. If the timeout expires, the read attempt is aborted.

    The default value is 30000. Values can be from 1000 to 60000. To disable time outs, set the value to 0.

  8. Click Apply to save your changes to the configuration.

Authenticating SOAP Requests with WSSE UsernameToken Credentials

Service Controller can authenticate incoming SOAP requests that contain WSSE UsernameToken credentials, as specified by OASIS UsernameToken Profile 1.0. For general information on WSSE UsernameToken, see the OASIS Web Service Security specifications at:

http://www.oasis-open.org/

You enable WSSE UsernameToken credential requirement by SOAP service. That is, it can be enabled for the Subscriber Provisioning service and disabled for the Balance Manager service, for example.

A service that requires WSSE UsernameToken authentication should not be configured to require an HTTP Basic Authentication credential as well. See "Creating or Modifying HTTP Server Security Contexts" for more information about HTTP Basic Authentication security contexts.

Service Controller validates the WSSE UsernameToken credential against credentials stored in the Service Controller Credential Store. Before configuring service authentication as described below, add the credential to be authenticated to the Credential Store. See Service Controller Security Guide for information about the Credential Store.

To apply WSSE UsernameToken credential authentication to incoming SOAP service requests, follow these steps:

  1. In the navigation tree in the domain navigation pane, expand OCSB.

  2. Expand Signaling Tier.

  3. Expand the SSU Web Services node.

  4. Click the General item.

  5. Click the SOAP tab.

  6. Click the Credential Store subtab.

  7. In the Key field, enter an alias for the credential.

  8. In the Password field, enter the password value for the credential.

  9. Verify that HTTP Basic Authentication is disabled for the underlying HTTP security context for the SOAP service as follows:

    1. Click the HTTP tab under the SSU Web Services node.

    2. In the Server subtab, click the Security Context subtab.

    3. Verify that the Auth Method value is NONE for the Context URI path applicable to the Web service. By default, the context path for all SOAP Web services exposed by Service Controller is /soap.

    4. If necessary, select the security context item and click the Update button to change the Auth Method.

  10. Under the OCSB navigation tree, expand, if necessary, the Signaling Tier node and then the SSU Web Services node.

  11. Click the name of the service for which you want to require WSSE UsernameToken authentication, either BALANCE MANAGER or SUBSCRIBER PROVISIONING.

  12. In the End Point tab, click the URI context for the service.

  13. Click the Update button.

  14. For the Authentication Method value, choose USERNAME_TOKEN.

  15. For the Username value, enter the user name portion of the credential to be authenticated by WSSE UsernameToken authentication.

  16. For the Credential Key value, enter the credential alias you used when storing the password to be validated into the Credential Store.

  17. Click OK to save your changes to the configuration.

Clients of the service must submit valid WSSE UsernameToken credentials with their service requests.

Configuring REST Web Service Access

As an HTTP-based protocol, REST-based communication is subject to the common HTTP connection settings configured in the HTTP tab. These include, for example, the port on which Service Controller listens for HTTP traffic, Basic Authentication security, and so on. See "Configuring HTTP Access Settings" for information on configuring common HTTP access settings.

In addition, you can configure specific settings that apply to REST-based communication with external REST clients or servers.

Configuring REST Server Parameters

The REST server settings apply to client connections made to Service Controller in which Service Controller acts as the server or server front-end for a REST API service.

To configure REST server settings:

  1. In the navigation tree in the domain navigation pane, expand OCSB.

  2. Expand Signaling Tier.

  3. Expand the SSU Web Services node.

  4. Click the General item.

  5. Click the REST tab.

  6. In the Server tab, verify and, if required, modify the default settings listed in Table 6-8.

    Table 6-8 REST Server Parameters

    Field Description

    Root URI

    The URI path at which Service Controller exposes REST APIs. This path value forms the root of the address that clients use to access REST resources.

    For example, given the default path of /rest, the full address of a REST resource would be:

    https://hostname:port/rest/subscriber/carol

    Timeout

    The amount of idle time, in milliseconds, after which Service Controller releases a client connection on which it is awaiting data.

    The default value is 10000 milliseconds. Values can be from 1000 to 60000. To disable timeout, set the timeout to 0.

  7. Click Apply to save your changes to the configuration.

Configuring REST Client Parameters

The REST client settings apply to outgoing connections. In this case, Service Controller acts as a client to external REST Web service providers.

To configure REST client settings:

  1. In the navigation tree in the domain navigation pane, expand OCSB.

  2. Expand Signaling Tier.

  3. Expand the SSU Web Services node.

  4. Click the General item.

  5. Click the REST tab.

  6. Click the Client subtab.

  7. Verify and, if required, modify the default settings listed in Table 6-9.

    Table 6-9 REST Client Parameters

    Field Description

    Connect Timeout

    The amount of time, in milliseconds, Service Controller allows to establish a connection to a remote server. If the timeout expires before receiving data, the connection attempt is abandoned.

    The default value is 5000. Values can be from 1000 to 60000. To disable timeout, set the timeout to 0.

    Read Timeout

    The amount of time, in milliseconds, Service Controller allows for reading data from a remote server on an established connection. If the timeout expires, the read attempt is abandoned.

    The default value is 30000 milliseconds. Values can be from 1000 to 60000. To disable timeout, set the timeout to 0.

  8. Click Apply to save your changes to the configuration.