System Administrator’s Guide

Managing OSA/Parlay Gateway Connections using Parlay_Access

The following sections describe how to add connections to OSA/Parlay Gateways:

Understanding OSA/Parlay Gateway and account mappings

Overall workflow when connecting to an OSA Gateway

Understanding OSA/Parlay Gateway and account mappings

Connection model

Oracle Communications Services Gatekeeper communication services use an internal service, Parlay Access, to manage all connections with OSA/Parlay Gateways. A plug-in that connects to an OSA/Parlay SCS asks the OSA Access service for a connection, and the service handles all of the details of Authentication, Service Discovery, and Load Management towards the OSA/Parlay Framework before returning the handle for the SCS to the plug-in

The following concepts are used when connecting a plug-in to an OSA/Parlay Gateway:

An OSA/Parlay Gateway, identified by a gatewayId, which represents the actual OSA/Parlay Gateway. Each OSA Gateway that is used is registered in Oracle Communications Services Gatekeeper. Any certificate to be used when authenticating with the OSA/Parlay framework is associated with the gatewayId.
Each OSA/Parlay Gateway has one or more OSA/Parlay Gateway Connections, identified by a connectionID. Multiple connections are used if the actual OSA/Parlay Gateway contains more than one Framework. The link between the OSA Gateway and the OSA Gateway connection is the gatewayID/gwID.
An OSA/Parlay client represents the account in the OSA/Parlay Gateway. An OSA client has the following attributes:

OSA client application ID, made up of the Enterprise Operator ID and the Application ID as provisioned in the OSA/Parlay Gateway,
Depending on the authentication method used, a private key (with associated password and keystore password) and public certificate to be used when authenticating.

An OSA/Parlay client mapping maps an OSA/Parlay client with OSA/Parlay SCSes. There must be (at least) one OSA/Parlay client mapping per OSA SCS being used. If the communication service uses n OSA/Parlay SCSs, n Client Mappings must be defined. Three different models are possible for the OSA/Parlay Client Mapping:

The client mapping can use wild cards for both the service provider and the application level, so all applications from all service providers are mapped to a single Client. In this case, transactions in the OSA/Gateway are traceable only to Oracle Communications Services Gatekeeper since Oracle Communications Services Gatekeeper, from the OSA/Parlay Gateway’s viewpoint, acts as one single application.
The client mapping can use a wildcard for the application level, but specify the service provider, so multiple Oracle Communications Services Gatekeeper applications that originate from a common service provider are mapped to a single OSA client. In this case, the transactions in the OSA/Gateway are traceable only to the service provider since Oracle Communications Services Gatekeeper, from the OSA/Parlay Gateway’s viewpoint, acts as one application per service provider.
The mapping may be set up per application level, so there is a one to one mapping between an Oracle Communications Services Gatekeeper service provider and application account combination and the equivalent Client. This means that every transaction originating from a specific application results in a transaction in the OSA/Parlay Gateway that is traceable to that specific application since Oracle Communications Services Gatekeeper, from the OSA/Parlay Gateway’s viewpoint, acts as one application per service provider and application combination.

Note:

Combinations of the above are not allowed. The Oracle Communications Services Gatekeeper administrator must choose one of these connection modes, and use the same mode for all Oracle Communications Services Gatekeeper applications In the first case, the connection is a system-wide configuration, in the other two cases, the connection is setup as a part of the provisioning chain for Oracle Communications Services Gatekeeper service providers and their applications.

Defining the OSA/Parlay client mapping is a part of the provisioning chain in when setting up service provider and application accounts if the client mapping is of type b. or type c.

Each OSA/Parlay Client mapping has a state. The state can be:

Active, which means that the connection between Oracle Communications Services Gatekeeper and a specific SCS in the OSA/Parlay Gateway is active and functional.
Inactive, which means that there is no active connection. This may be because the client mapping is not configured to be initialized at startup and no requests have yet been passed to it. It may also indicate that there is a problem with the connection.

Information and Certificate Exchange With OSA/Parlay Gateway Administrator

The OSA/Parlay Gateway administrator must provide the following information with regard to the OSA/Parlay Gateway account and OSA/Parlay Framework:

The entOpId (Enterprise Operator ID) - Depending on how the OSA/Parlay operator administers applications (OSA/Parlay clients) the entOpId can be valid for:

All applications registered in Oracle Communications Services Gatekeeper
All applications connected to a service provider account
A single application account

The appId (Application ID) to be used for the application account (clientAppId=entOpId + \ + appId)
The OSA/Parlay service types for the OSA/Parlay SCSs to which the application is to be mapped
The encryption method used
The signing algorithm used
Connection information for the OSA/Parlay Framework, either:

name service reference file to the OSA/Parlay Gateway Framework’s Parlay IpInitial object.
The name of the initial object in the name service and the file containing the IOR to the IpInitial object.

If the authentication method towards the OSA/Parlay Framework requires a certificate, the Oracle Communications Services Gatekeeper administrator must generate one, and distribute it to the OSA/Parlay Gateway administrator. The associated key must be stored in the Oracle Communications Services Gatekeeper keystore, this is done when the OSA client is created, see Creating an OSA client.

For non-production environments, the WebLogic Server CertGen utility can be used to create certificates and keys.

Overall workflow when connecting to an OSA Gateway

Follow the steps below to connect an application account to an OSA/Parlay Gateway:

Create a logical representation of the OSA/Parlay Gateways to connect to: see Adding an OSA/Parlay Gateway.
For each Framework in the OSA/Parlay Gateway, create a logical representation of the Framework: see Adding an OSA Gateway Connection.
Define how Oracle Communications Services Gatekeeper connects to the OSA/Parlay Gateway.

If Oracle Communications Services Gatekeeper connects to the OSA/Parlay Gateway as one single user, register this user: see Creating an OSA client.
If Oracle Communications Services Gatekeeper connects to the OSA/Parlay Gateway as several users, the registration of users is a part of the provisioning flow for service providers and applications.

The registration of which SCSes to use in the OSA/Parlay Gateway is done either as a part of the configuration flow for the communication services, or as a part of the provisioning flow for service providers and application. The procedure is described in Mapping the OSA client to an OSA Gateway and an OSA/Parlay SCS, and the data to be used is described in the configuration section for each communication service.

Adding an OSA/Parlay Gateway

An OSA/Parlay Gateway is the entity representing an OSA/Parlay Gateway. One or more OSA Gateway Connections can be associated with the OSA Gateway.

If authenticating using certificates, get the certificate for the OSA/Parlay Gateway from the administrator of the OSA/Parlay Gateway and store it on the local file system of the Oracle Communications Services Gatekeeper’s administration server.
Starting in the configuration and operations page for Plugin_Parlay_Access_<communication service>, select addGw from the Select An Operation drop-down list.

The parameters for the operation are displayed.

Enter the information specified in Operation: addGw
Click Invoke.

The OSA Gateway is created. An ID for the OSA Gateway is returned.

Adding an OSA Gateway Connection

An OSA Gateway connection is the entity representing an individual Framework in an OSA/Parlay Gateway.

Get either information about how to obtain a reference to the OSA/Parlay Framework from the administrator of the OSA/Parlay Gateway. These options are possible:

The name service reference file. Store the file on the local file system of the Oracle Communications Services Gatekeeper administration server.
The name of the initial object in the name service and the file containing the IOR to the Parlay initial object. Store the file on the local file system of the Oracle Communications Services Gatekeeper administration server.
The IOR is provided as a String.

Starting in the configuration and operations page for Plugin_Parlay_Access_<communication service>, select:

If the IOR is provided as a file: use Operation: addConnection

If the IOR is provided as a String: use Operation: addConnectionIOR

Click Invoke.

The OSA Gateway Connection is created. An ID for the OSA Gateway Connection is returned.

Creating an OSA client

The OSA client is the entity being used when creating the OSA client mapping.

If authenticating using certificates, create, or get from a a Certificate Authority, the private key and certificate for the client and store them on the local file system of the Oracle Communications Services Gatekeeper administration server.
Starting in the configuration and operations page for Plugin_Parlay_Access_<communication service>, select addClient from the Select An Operation drop-down list.

The parameters for the operation are displayed.

Enter the information specified in Operation: addClient
Click Invoke.

The OSA client is created.

Mapping the OSA client to an OSA Gateway and an OSA/Parlay SCS

The mapping may be applied on service provider account, application account, or Oracle Communications Services Gatekeeper level.

Note:

One mapping must be created for each OSA/Parlay SCS (network service) the Oracle Communications Services Gatekeeper application is using in the OSA/Parlay gateway.

Starting in the configuration and operations page for Plugin_Parlay_Access_<communication service>, select addMapping from the Select An Operation drop-down list.

The parameters for the operation are displayed.

Enter the information specified in Operation: addMapping
Click Invoke.

The OSA Client Mapping is created.

Reference: Attributes and Operations for Parlay _Access

Managed object: Container ServicesParlay_Access_<Communication Service>

Where Communication Service is one of:

audio_call_px30
call_notification_px30
third_party_call_px30

Note:

There are three MBeans, one for each communication service of Parlay type. It does not matter which one you use, they all operate on the same data.

MBean: com.bea.wlcp.wlng.parlay.access.ParlayAccessMBean

Below is a list of attributes and operations for configuration and maintenance:

Attribute: EricssonAuthentication

Scope: Cluster

Unit: n/a

Format: Boolean

Set to:

True if connecting to an Ericsson OSA/Parlay Gateway
False if connecting to other gateways.

Operation: activateMapping

Scope: Cluster

Activates an existing mapping.

Signature:

activateMapping(id: String)

Table 36-1 activateMapping
activateMapping
Parameter	Description
id	ID of the OSA/Parlay client mapping to activate. See Operation: listMappings.

Operation: addClient

Scope: Cluster

Adds an OSA/Parlay Client.

Signature:

addClient(osaClientAppId: String, clientKeyFile: String, clientCertFile: String, clientKeyPwd: String, keystorePwd: String)

addClient

Parameter

Description

osaClientAppId

The Enterprise Operator ID and Application ID registered for the OSA/Parlay Client in the OSA/Parlay Gateway. This value must be unique. The format is:

<Enterprise Operator>\<Application ID>

Example:

myEntopId\myAppId

clientKeyFile

The directory path (including file name) to the private key for the OSA Client.

Note:

This path is on the file system of the Oracle Communications Services Gatekeeper Network Tier server.

Leave empty if not authenticating using certificates.

clientCertFile

The directory path (including file name) to the certificate for the OSA Client. The certificate is provided in order to verify the private key is correct.

Note:

This path is on the file system of the Oracle Communications Services Gatekeeper Network Tier server.

Leave empty if not authenticating using certificates.

clientKeyPwd

The password for the private key.

Leave empty if not authenticating using certificates.

keystorePwd

The keystore’s password as defined when configuring the Oracle Communications Services Gatekeeper, see Operation: setKeyStorePassword.

Operation: addConnection

Scope: Cluster

Adds a connection to a Framework in the OSA/Parlay Gateway using a file that contains the name service IOR.

Signature:

addConnection(gwId: int, nsRef: String, nsName: String,initialRef: String, priority: int)

 
Table 36-3  addConnection



       
addConnection



       
Parameter


     
Description



       
gwId 


     
The ID of the OSA/Parlay Gateway, as returned when the OSA Gateway was created. See Operation: addGw. Also see Operation: listGw.



       
nsRef 


     
The directory path (including file name) for the file containing the name service IOR. 

 
Leave blank if initialRef is specified.



       
nsName 


     
The name of the initial object in the name service. Example:

 
parlay_initial. 

 
Use path syntax to specify recursive naming contexts. Example: /parlay/fw/parlay_inital

 
Leave blank if initialRef is specified.



       
initialRef 


     
The directory path, including file name, for the file containing the IOR to the Parlay initial object. 

 
Leave blank if nsRef and nsName is specified.



       
priority


     
Priority of this connection. Should be unique across all connections. The lower the number, the higher the priority.

Operation: addConnectionIOR

Scope: Cluster

Adds a connection to a Framework in the OSA/Parlay Gateway using an IOR string.

Signature:

addConnectionIOR(gwId: int, ior: String, ns: String, priority: int)

 
Table 36-4  addConnectionIOR



       
addConnection



       
Parameter


     
Description



       
gwId 


     
The ID of the OSA/Parlay Gateway, as returned when the OSA Gateway was created. See Operation: addGw. Also see Operation: listGw.



       
ior


     
IOR string of either the NS or the initial object.



       
ns 


     
The name of the initial object in the name service. Example:

 
parlay_initial. 

 
Use path syntax to specify recursive naming contexts. Example: /parlay/fw/parlay_inital

 
Leave blank if IOR to the initial object is specified.



       
priority


     
Priority of this connection. Should be unique across all connections. The lower the number, the higher the priority.

Operation: addGw

Scope: Cluster

Adds an OSA/Parlay Gateway to be used by the OSA/Parlay type plug-ins. More than one Gateway can be added.

Signature:

addGw(name: String, osaFwCert: String, reAuthWaitTime: int, keystorePwd: String)

Returns the ID for the OSA Gateway. This ID is used when creating an OSA/Parlay Gateway Connection, see Operation: addConnection and when creating an OSA/Parlay Client Mapping, see Operation: addMapping.

Table 36-5 addGw
addGw
Parameters	Description
gateway.name	Descriptive name of the OSA Gateway.
osaFwCert	The certificate to use when connecting to the OSA Gateway’s Framework. The certificate is supplied by the OSA Gateway administrator. Leave empty if not authenticating using certificates.
reAuthWaitTime	The time to wait before reattempting to authenticate and obtain OSA Service Managers if all connections to the OSA Gateway are lost. Given in seconds
keystorePwd	The password for the Oracle Communications Services Gatekeeper keystore.

Operation: addMapping

Scope: Cluster

Adds an OSA client mapping.

Signature:

addMapping(serviceProviderID: String, applicationID: String, serviceType: String, osaClientAppId: String, properties: String, authType: String, encryptionMethod: String, signingAlgorithm: String, gatewayId: int, initConnection: boolean)

addMapping

Parameter

Description

serviceProviderID

ID of the service provider account the application is associated with.

Note:

If left empty, the mapping will not be applied on service provider account and application account level.

applicationID

ID of the application account.

Note:

If left empty, the mapping will not be applied on application account level.

serviceType

OSA/Parlay service type name (TpServiceTypeName) of the OSA/Parlay SCS to which the OSA Client is to be mapped.

See the specification for the OSA/Parlay Framework for a list of recommended service type names.

osaClientAppId

The OSA/Parlay account’s clientAppID, a string consisting of the entOpId followed by \, followed by the appId. Example: sp1\app1.

The entOpId and appId is provided by the OSA Gateway administrator.

properties

OSA/Parlay service properties to be used in the look up (service discovery) phase when requesting a service (OSA/Parlay SCS) from the OSA/Parlay Gateway.

The properties are specified as a space separated list in the following way: <propname1> <propval1> <propname2> <propval2>

The properties varies between OSA/Parlay Gateway implementations.

authType

Authentication type to be used. The type is defined according to the OSA/Parlay standard. P_AUTHENTICATION is the only supported.

Note:

When P_AUTHENTICATION is used, no encryption or signing algorithm will be used and the parameters encryptionMethod and signingAlgorithm can be left empty.

encryptionMethod

Method used for encryption. The type is defined according to OSA/Parlay standard. If the type is not specified, enter P_RSA_1024.

signingAlgorithm

Signing algorithm. The type is defined according to OSA/Parlay standard.

If the type is not specified, enter P_MD5_RSA_1024.

gatewayId

OSA/Parlay Gateway ID. This ID was generated when the OSA/Parlay Gateway was created, see Operation: addGw, and Operation: listGw.

initConnection

Indicating if the connection to OSA/Parlay Gateway should be initialized immediately. That is, if authentication should performed when the Operation: addClient operation is invoked.

Operation: listActiveMappings

Scope: Cluster

Lists the IDs for active OSA/Parlay Client Mappings.

Signature:

listActiveMappings()

Returns a list of IDs for active mappings.

Table 36-7 listActiveMappings
listActiveMappings
Parameter	Description
-	-

Operation: listActiveMappingsForGw

Scope: Cluster

Lists the IDs of all active OSA/Parlay Client Mappings for a specific OSA/Parlay Gateway.

Signature:

listActiveMappingsForGw(gwId: int)

Returns a list of IDs for active mappings for the Gateway.

Table 36-8 listActiveMappingsForGw
listActiveMappingsForGw
Parameter	Description
gwId	The ID of the OSA Gateway.

Operation: listGw

Scope: Cluster

Lists the IDs of all registered OSA/Parlay Gateways.

Signature:

listGw()

Table 36-9 listGw
listGw
Parameter	Description
-	-

Operation: listMappings

Scope: Cluster

Lists the configured OSA/Parlay Client Mappings.

Signature:

listMappings()

Table 36-10 listMappings
listMappings
Parameter	Description
-	-

Operation: removeClient

Scope: Cluster

Removes an OSA/Parlay client.

Signature:

removeClient(osaClientAppId: String, keystorePwd: String)

Table 36-11 removeClient
removeClient
Parameter	Description
osaClientAppId	The OSA/Parlay client application ID (and alias in keystore). See Operation: addClient.
keystorePwd	Oracle Communications Services Gatekeeper keystore password.

Operation: removeConnection

Scope: Cluster

Removes an OSA/Parlay Gateway Connection

Signature:

removeConnection(gatewayId: int, connectionId: int)

Table 36-12 removeConnection
removeConnection
Parameter	Description
gatewayId	The ID of the OSA/Parlay Gateway.
connectionId	The ID of the connection. The ID was returned when the connection was setup, see: Operation: addConnection Operation: listActiveMappings Operation: listMappings

Operation: removeGw

Scope: Cluster

Removes an OSA/Parlay Gateway.

Signature:

removeGw(id: int, keystorePwd: String)

Table 36-13 removeGw
removeGw
Parameter	Description
id	The ID of the OSA/Parlay Gateway to remove. The ID was returned when the OSA Gateway was created, see Operation: addGw Operation: listGw
keystorePwd	The Oracle Communications Services Gatekeeper keystore password.

Operation: removeMapping

Scope: Cluster

Removes an OSA/Parlay client mapping.

Signature:

removeMapping(id: int)

Parameters:

Table 36-14 removeMapping
removeMapping
Parameter	Description
id	ID of the OSA/Parlay Client Mapping to remove.

Operation: setKeyStorePassword

Scope: Cluster

Sets the password that protects the keystore.

Signature:

setKeyStorePassword(newPassword: String, oldPassword: String)

Table 36-15 setKeyStorePassword
setKeyStorePassword
Parameter	Description
newPassword	The new password for the keystore.
oldPassword	The old password for the keystore.

Operation: viewActiveMappingState

Scope: Cluster

Displays the state of an active mapping OSA/Parlay Client Mapping.

Signature:

viewActiveMappingState(mappingId: int)

Table 36-16 viewActiveMappingState
viewActiveMappingState
Parameter	Description
mappingId	The ID of the OSA Client Mapping.