Oracle® Communications Services Gatekeeper Communication Service Guide Release 5.1 E37526-01 |
|
|
PDF · Mobi · ePub |
This chapter describes the Extended Web Services (EWS) Subscriber Profile/Lightweight Directory Access Protocol (LDAPv3) communication service in detail.
The EWS Subscriber Profile/LDAPv3 communication service exposes Oracle's Extended Web Services Subscriber Profile application interface.
The communication service acts as an LDAP client to a directory service, connecting to the directory service using LDAPv3.
For the exact version of the standards that the communication service supports for the application-facing interfaces and the network protocols, see the appendix on standards and specifications in Oracle Communications Services Gatekeeper Concepts Guide.
Using the EWS Subscriber Profile/LDAPv3 communication service, an application can:
Retrieve the specific value for a particular property belonging to a subscriber profile stored in an LDAP data source.
Retrieve an entire subscriber profile from an LDAP data source, subject to SLA filtering.
For information about the application interface for the Extended Web Services Subscriber Profile communication service, see the discussion of Extended Web Services Subscriber Profile in Oracle Communications Services Gatekeeper Application Developer's Guide.
For information about the RESTful Call Notification interface, see the discussion of Subscriber Profile in Oracle Communications Services Gatekeeper RESTful Application Developer's Guide.
The RESTful Service Call Notification interfaces provide RESTful access to the same functionality as the SOAP-based interfaces. The internal representations are identical, and for the purposes of creating SLAs and reading CDRs, and so on, they are the same.
The EWS Subscriber Profile/LDAPv3 communication service generates Event Data Records (EDRs), Charging Data Records (CDRs), alarms, and statistics to assist system administrators and developers in monitoring the service
For general information, see Appendix A, "Events, Alarms, and Charging."
Table 23-1 lists IDs of the EDRS created by the EWS Subscriber Profile/LDAPv3 communication service. This list does not include EDRs created when exceptions are thrown
EWS Subscriber Profile/LDAPv3-specific CDRs are generated under the following conditions:
After Services Gatekeeper has returned a full or partial subscriber profile to an application based on one or more attributes requested by that application.
After Services Gatekeeper has returned a subscriber profile to an application based on the ID of the profile.
Table 23-2 maps methods invoked from either the application or the network to the transaction types collected by the Services Gatekeeper statistics counters.
This section describes the properties and workflow for the EWS Subscriber Profile/LDAPv3 plug-in instance.
It includes an LDAP server schema to use in constructing LDAP queries.
A connection pool is used for connections to the LDAP server. The connection pool is shared among all plug-in instances, and any configuration settings related to this pool or schema updates are broadcast to all plug-in instances in the cluster.
Use "Operation: updateLDAPSettings" to force configuration changes to take effect.
Table 23-3 lists the technical specifications for the communication service.
Table 23-3 Properties for EWS Subscriber Profile/LDAPv3
Property | Description |
---|---|
Managed object in Administration Console |
domain_name > OCSG > server_name > Communication Services > plugin_instance_id |
MBean |
Domain=com.bea.wlcp.wlng Name=wlng_nt InstanceName=same as the network protocol instance_id assigned when the plug-in instance is created. Type=com.bea.wlcp.wlng.plugin.subscriberprofile.ldap.managedplugin.management.SubscriberProfileMBean |
Network protocol plug-in service ID |
Plugin_ews_subscriber_profile_ldap |
Network protocol plug-in instance ID |
The ID is assigned when the plug-in instance is created. See "Managing and Configuring the Plug-in Manager" in Oracle Communications Services Gatekeeper System Administrator's Guide. |
Supported Address Scheme |
tel, id, imsi, ipv4 |
Application-facing interface |
com.bea.wlcp.wlng.ews.plugin.SubscriberProfilePlugin |
Service type |
SubscriberProfile |
Exposes to the service communication layer a Java representation of: |
Extended Web Services Subscriber Profile |
Interfaces with the network nodes using: |
LDAP |
Deployment artifact NT EAR wlng_nt_subscriber_profile_ews.ear |
ews_subscriber_profile_service.jar and Plugin_ews_subscriber_profile_ldap.jar |
Deployment artifact AT EAR: Normal wlng_at_subscriber_profile_ews.ear |
ews_subscriber_profile.war and rest_subscriber_profile.war |
Deployment artifact AT EAR: SOAP Only wlng_at_subscriber_profile_ews_soap.ear |
ews_subscriber_profile.war |
All subscriber-profile-related operations are handed off to network nodes that accept LDAP queries according to LDAPv3. The decision concerning which node in the LDAP directory should be used to perform the query is decided at run time based on configuration settings. The data that is handed back to the application that initiated the Subscriber Profile query is filtered using the result filter mechanism in the service provider group and application group SLAs. For more information, see <resultRestrictions>
in "Defining Service Provider Group and Application Group SLAs" in the Oracle Communications Services Gatekeeper Accounts and SLAs Guide.
A schema is used for constructing queries. See Example 23-1.
Example 23-1 LDAP Query schema XSD
<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="LdapConfig"> <xs:complexType> <xs:sequence> <xs:element name="Keys" type="KeySet" minOccurs="1" maxOccurs="unbounded"/> <xs:element name="LdapObject" type="LdapObject" minOccurs="1" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element> <xs:complexType name="KeyObject"> <xs:sequence> <xs:element name="uriScheme" type="xs:string" minOccurs="1" maxOccurs="1"/> <xs:element name="addressKeyName" type="xs:string" minOccurs="1" maxOccurs="1"/> <xs:element name="objectKeyName" type="xs:string" minOccurs="0" maxOccurs="1"/> <xs:element name="objectKeyValue" type="xs:string" minOccurs="0" maxOccurs="1"/> </xs:sequence> <xs:attribute name="id" type="xs:string" use="optional"/> </xs:complexType> <xs:complexType name="KeySet"> <xs:sequence> <xs:element name="Key" type="KeyObject" minOccurs="1" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="id" type="xs:string" use="required"/> </xs:complexType> <xs:complexType name="LdapObject"> <xs:sequence> <xs:element name="ObjectKeySet" type="xs:string" minOccurs="0" maxOccurs="1"/> </xs:sequence> <xs:attribute name="id" type="xs:string" use="required"/> <xs:attribute name="keyName" type="xs:string" use="required"/> <xs:attribute name="keyValue" type="xs:string" use="required"/> </xs:complexType> </xs:schema>
The LDAP server schema describes the following elements:
LdapObject: Holder of a KeySet
KeySet: Defines a collection of KeyObjects. Sets of keys are used because there may be several ways to reach a certain node in the tree. One LDAP plug-in instance can be configured with several KeySets and can provide the link between the search key in the Extended Web Services interface and the LDAP tree.
KeyObject: Defines an entry point to the LDAP tree and provides the link between the search key in the Extended Web Services interface and the LDAP tree.
Table 23-4 describes the schema objects in detail.
Object | Element | Description |
---|---|---|
LdapObject |
ObjectKeySet |
Defines the KeySet through which it can be reached. Refers to theID attribute of a defined KeySet. |
LdapObject |
id |
The identity of the LdapObject. Can be referenced from other LdapObjects through the ParentObjectId field. |
LdapObject |
keyName |
The name of the key through which the LdapObject can be reached. |
LdapObject |
keyValue |
The value of the key through which the LdapObject can be reached. |
KeyObject |
uriScheme |
Defines the URI scheme of the address for which this key applies. |
KeyObject |
addressKeyName |
Defines the key name with which the address value is associated. |
KeyObject |
objectKeyName |
Provides the possibility of defining the addressing key of a possible tree node above the node that is reached by the address key (that is, like the domain object in the 3DS directory information tree). |
KeyObject |
objectKeyValue |
See objectKeyName. Defines the value of the key. |
KeyObject |
id |
The identity of the key. Used only for descriptive purposes. |
KeySet |
Key |
All keys in the KeySet |
KeySet |
id |
The identity of the KeySet. Used when associating an LdapObject with a KeySet. |
Example 23-2 shows a directory information tree built using the schema described in Table 23-4.
Example 23-2 Example of LDAP server schema
<?xml version="1.0" encoding="UTF-8"?> <LdapConfig xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:noNamespaceSchemaLocation='sp_config.xsd'> <Keys id="myKeys"> <Key id="misidnKey"> <uriScheme>tel</uriScheme> <addressKeyName>msisdn</addressKeyName> <objectKeyName>domainName</objectKeyName> <objectKeyValue>msisdnD</objectKeyValue> </Key> <Key id="imsiKey"> <uriScheme>imsi</uriScheme> <addressKeyName>imsi</addressKeyName> <objectKeyName>domainName</objectKeyName> <objectKeyValue>imsiD</objectKeyValue> </Key> <Key id="subscriberIdKey"> <uriScheme>id</uriScheme> <addressKeyName>id</addressKeyName> <objectKeyName>domainName</objectKeyName> <objectKeyValue>subsD</objectKeyValue> </Key> <Key id="ipv4Key"> <uriScheme>ipv4</uriScheme> <addressKeyName>ipv4Addr</addressKeyName> <objectKeyName>domainName</objectKeyName> <objectKeyValue>ipv4D</objectKeyValue> </Key> </Keys> <LdapObject id="mySchema" keyName="serviceName" keyValue="mySchema"> <ObjectKeySet>myKeys</ObjectKeySet> </LdapObject> </LdapConfig>
Following is an outline for configuring the plug-in using the Administration Console or an MBean browser.
Create one or more instances of the plug-in service. See "Managing and Configuring the Plug-in Manager" in Oracle Communications Services Gatekeeper System Administrator's Guide. Use the plug-in service ID as listed in the "Properties for EWS Subscriber Profile/LDAPv3" section.
Select the MBean for the plug-in instance. The MBean display name is the same as the plug-in instance ID given when the plug-in instance was created.
Define the characteristics of the LDAP server to connect to:
Using either "Attribute: Schema" or "Operation: updateSchemaURL", define the schema.
See "LDAP Server Schema" for a description of the schema and "Configuration Workflow for EWS Subscriber Profile/LDAPv3" for a description of the mappings.
Define the connection pool characteristics for the connection:
Set up the routing rules to the plug-in instance. See "Managing and Configuring the Plug-in Manager" in Oracle Communications Services Gatekeeper System Administrator's Guide. Use the plug-in instance ID and address schemes listed in the "Properties for EWS Subscriber Profile/LDAPv3" section.
If required, create and load a node SLA. For details see "Defining Global Node and Service Provider Group Node SLAs" and "Managing SLAs" in the Oracle Communications Services Gatekeeper Accounts and SLAs Guide.
Provision the service provider accounts and application accounts. For information, see Oracle Communications Services Gatekeeper Accounts and SLAs Guide.
There are no specific management operations, except for "Operation: updateLDAPSettings", used to update the LDAP connection pool after changing any of the following attributes:
If the results from the LDAP query should be filtered, use the service provider group and application group SLAs. See <resultRestriction>
in "Defining Service Provider Group and Application Group SLAs" in the Oracle Communications Services Gatekeeper Accounts and SLAs Guide.
This section describes the attributes and operations for configuration and maintenance:
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the authentication Distinguished Name (DN) for the LDAP server.
Example:
cn=admin,o=acompany,c=uk
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the password associated with "Attribute: AuthDN".
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the base Distinguished Name (DN) for the LDAP database in use.
Example:
o=acompany,c=uk
Scope: Cluster
Unit: Seconds
Specifies the maximum time to wait for an LDAP connection to be established. If the related timer expires, a retry is performed. See "Attribute: RecoverTimerInterval" for more information.
Any change to this setting must be followed by "Operation: updateLDAPSettings".
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the host name or IP address of the LDAP server to connect to.
Examples:
myldapserver.mycompany.org 192.168.0.14
Read-only.
Scope: Cluster
Unit: Not applicable
Format: String enumeration listed in Table 23-5.
Table 23-5 Status of the connection to the LDAP server
Status | Description |
---|---|
active |
The connection is active. The plug-in instance accepts requests. |
update_pending |
The connection is temporarily unavailable due to an update of the configuration settings. The plug-in instance does not accept requests. |
deactive |
The connection is inactive. The plug-in instance does not accept requests. Reasons for this entering this state include:
|
Scope: Cluster
Unit: Not applicable
Format: Integer
Specifies the maximum number of connections in the LDAP connection pool.
Any change to this setting must be followed by "Operation: updateLDAPSettings".
Scope: Cluster
Unit: Not applicable
Format: Integer
Specifies the minimum number of connections to establish using connections from the LDAP connection pool.
Any change to this setting must be followed by "Operation: updateLDAPSettings".
Scope: Cluster
Unit: Not applicable
Format: Integer
Specifies the port number of the LDAP server to connect to.
Scope: Cluster
Unit: Seconds
Format: Integer
Specifies the time to wait before performing an LDAP connection retry after an LDAP connection error. Should be at least twice the time defined in "Attribute: ConnTimeout".
Any change to this setting must be followed by "Operation: updateLDAPSettings".
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the LDAP schema to use.
Scope: Cluster
Refreshes the LDAP connection pool to use the new configuration.
During the update, the LDAP connection is temporarily unavailable and the connection status is update_pending. See Table 23-5, "Status of the connection to the LDAP server" for status values.
Signature:
updateLDAPSettings()
Scope: Cluster
Updates the schema to use when performing lookups in the LDAP database.
During the update, the LDAP connection is temporarily unavailable and the connection status is update_pending. See Table 23-5, "Status of the connection to the LDAP server" for status values.
Signature:
updateSchemaURL(SchemaURL:String)