| Oracle® Communications Service Broker VPN Implementation Guide Release 6.0 Part Number E23531-02 |
|
|
View PDF |
| Oracle® Communications Service Broker VPN Implementation Guide Release 6.0 Part Number E23531-02 |
|
|
View PDF |
This chapter provides an overview of the VPN Provisioning Application Programming Interface (API), a REST-style API for configuring the services of the Oracle Communications Service Broker VPN application.
The VPN application exposes a RESTful API that clients use to access, create, and modify application data for Service Broker VPN.
The API provides operations for adding subscribers, configuring access rules, and adding users. In general, any configuration or provisioning task related to how the VPN application delivers services is performed with the VPN Provisioning API.
For most deployments, the primary clients for the API will be VPN self-management web interface. Administrators in the subscribing organization use the interface to perform the day-to-day provisioning and configuration tasks for that organization's VPN service instance.
The interface may be a dedicated web application that you create or GUI controls that you add to an existing customer portal.
The batch operation tools are also clients of the VPN Provisioning API. You can use the batch operation tools to populate application data for VPN services in bulk, based on contents of a CSV file. See "Using Batch Operation Tools" for information about the batch operation tools.
The specific functionality you choose to expose in the VPN self-management application depends on your specific requirements and those of your subscribers. Use cases for the subscriber application could include:
View and modify the general subscriber settings, including numbering plan attributes.
Enable or disable particular features, such as private calling.
Configure general roaming and home network policies for users and groups.
Manage access control policies for the subscriber, such as duration controls.
Add, modify, or remove closed user groups.
Manage on-net mobile user devices.
Manage on-net PBX users.
Register end users.
Configure VPN partner organizations.
You may also choose to create an application that provider administrators use to perform global management operations. Possible use cases for this application would be:
Configure the provider object attributes, such as the name, description, and address of the provider organization.
Configure global policies, such as call barring blacklists, and numbering properties.
Create, modify, and remove subscriber administrators.
Create and provide the initial configuration for the subscriber instances.
The VPN Provisioning API follows the style of a REST (Representational State Transfer) interface. Like any RESTful API, the VPN Provisioning API makes its services available to client applications through simple HTTP requests.
In a RESTful API, functions are distinguished by the combination of a particular URI and the HTTP method used to access it. In general, the URI identifies the resource on which to act, and the HTTP method identifies the type of action to perform.
The resource can be a generic resource or an instance-specific resource. A generic resource is equivalent to a factory creation function in a traditional API. The client application would use it, for example, to create a VPN instance or a new user in the VPN. After the resource is created, it can be modified or inspected at its unique URI.
For example, to create an object that represents a user in the VPN, the client application would send the following request to the API:
POST /vpn/subscriber/vpn_id/users
After the user object is created, the client application can inspect, modify, or delete the object by sending a GET, PUT, or DELETE request to the address associated with that object instance. For a user with the user name of alice, for example, the URI to access the user's object would be:
vpn/subscriber/vpn_id/user/alice
The methods in the HTTP protocol used in the VPN Provisioning API (POST, GET, PUT, and DELETE) correspond to the programming operations commonly known as CRUD operations. CRUD, which stands for create, read, update, and delete, represent the common operations applicable in data-oriented APIs. The equivalent function calls in a traditional API may be similar to createUser(), getUser(), setUser(), and deleteUser(). In this case, the instance on which the function operates is typically identified through an input parameter.
In a Service Broker deployment, the VPN Provisioning API is exposed by the managed server. Therefore, at least one managed server must be deployed and running in your environment before you can use the API to configure and provision VPN services.
Several types of clients connect to the managed server instance, including the Administration Console client process and JMX clients. The managed server listens for VPN Provisioning API at the port configured for client HTTP access. Before using the API, ensure that the managed server is configured to accept web requests. See "Opening an HTTP Listening Port for the VPN Provisioning Service" for information about configuring the managed server.
To test basic client connectivity to the API, you can try sending a GET request for one of several built-in resources in the system. For instance, you can send a GET request for the built-in admin administrator account, which is available at the following URI:
https://host:port/vpn/admin/admin
Replace host with the host name or IP address you specified for the HTTP listener in the Web Services SSU of the Signaling Tier domain, and replace port with the port number.
In a managed server cluster, all servers access the same data store. Therefore, it is not important which managed server the API client addresses.
If the request is successful, the properties associated with the admin user appear in the body of the response message.
Clients access the services of the VPN Provisioning API by sending HTTP requests to the managed server instance in the Service Broker managed domain. To use the API, the managed server must be configured and running.
The format of the URL to invoke operations in the Provisioning API is:
https://host:port/vpn/component/resourceId
Where:
host:port are the host name and port number of an HTTP listener you have configured in the Web Service SSU of the Service Broker Signaling Tier.
component is the data system component that you want to modify, create or query.
resourceId is the identifier of the instance on which the application operates.
VPN Provisioning API operations that are invoked with the GET or DELETE HTTP methods do not require input values other than what is provided in the URI and headers of the client request. That is, they do not require HTTP body content to be supplied in the invocation request.
However, VPN Provisioning API operations invoked with the POST and PUT methods require additional input data. The Provisioning API takes input parameters in the form of JSON (JavaScript Object Notation) data in the body of the request.
JSON is a data exchange format based on JavaScript that is commonly used to pass information between web clients and servers over HTTP. In the body of the request, JSON data appears as one or more name-value pairs. For example:
{adminUsername:"alice",password:"password"}
The example shows two name-value pairs for an object in the system that represents a person. The type of both parameters are String.
JSON defines the following data types:
number
string
boolean
object
Parameters can be composed of an array. The numberRange attribute in the service provider object is an example. The individual values of a JSON array are enclosed in brackets and separated by commas, as in the following example:
{ "numberRange":["5982*","5981*"] }
In addition to simple types, a parameter can be a complex type. A complex type is a parameter that contains a nested set of subparameters. The callScreeningList parameter is an example. It contains an array of access control rules, as shown in the following example.
"callScreeningList": [
{
"range":"13522928011",
"timeSpan":1,
"permit":true,
"type":1
},
{
"range":"136*",
"timeSpan":0,
"permit":true,
"type":0
}
]
In addition to validating the basic data type of a submitted parameter, the VPN application may validate the content of the parameter. For example, it may ensure that a number falls within an expected range or that dates meet the required format.
The values of certain parameters are limited to what are called word characters. Expressed in regular expression notation, the word character set is: [A-Za-z0-9_]. In other words, a value may contain upper-case or lower-case letters, numbers, and underscore characters.
Numeric values are expressed as digits. In some cases, a parameter may contain a range of numbers, such as the extension value for a PBX user. To specify a range of numbers, use the common numeric prefix for the number range followed by a wildcard. An example is 898*, which applies to all numbers that begin with the numbers 898, such as 89823 or 8981.
"VPN Provisioning API Reference" lists the data format requirements for each parameter.
To add users, devices, and subscribers to the VPN, you use the VPN Provisioning API to create the data objects that represent the entities you want to add.
The body of the POST request should contain the JSON-formatted data that describes the entity, such as the end user's name, phone number, extension, and so on.
Each type of object can have mandatory parameters and optional parameters. A mandatary parameter must be included in the create object request with a value that meets the content requirements for that parameter.
The value of a parameter may be a reference to another object. The VPN application checks object dependencies when it creates the object, ensuring that the objects upon which the new object depends, such as the profile or group definitions, exist.
When updating the object, you supply a new value for a modified setting in the body of a PUT request. In the body, you only supply the values for those parameters you want to modify, not for the entire object.
For example, to update a Subscriber object that currently has the following attribute values:
{
"callScreeningBlackList" : [ ],
"exclusionList" : [ ],
"maxExtensionNumberLength" : 4,
"callBarringBlackList" : [ "2894*", "499*" ],
"escapeCode" : "0",
"timeZone" : 8,
"vpnID" : "vpn002",
"privateNumberCLI" : false,
"forcedOnNet" : true,
"partnerVPNSwitch" : true,
"name" : "company002",
"partnerVPN" : [ ],
"privateCallEnable" : true,
"worktimeID" : ""
}
You would send an HTTP PUT request that contains only the new value for the field you want to change. Therefore, to add an item to the call barring black list and disable private calling, you would send a PUT request with the following body:
{"callBarringBlackList":["2894*", "499*", "498*"],"privateCallEnable" : false}
The operation would result in a Subscriber object of:
{
"callScreeningBlackList" : [ ],
"exclusionList" : [ ],
"maxExtensionNumberLength" : 4,
"callBarringBlackList" : [ "2894*", "499*", "498*" ],
"escapeCode" : "0",
"timeZone" : 8,
"vpnID" : "vpn002",
"privateNumberCLI" : false,
"forcedOnNet" : true,
"partnerVPNSwitch" : true,
"name" : "company002",
"partnerVPN" : [ ],
"privateCallEnable" : false,
"worktimeID" : ""}
By default, security is disabled for the VPN Provisioning API. That is, clients can submit requests to the API without providing user credentials. While this may be suitable for test and evaluation systems, for production-level systems, access to the VPN Provisioning API should be secured.
The isSecurity attribute of the built-in admin user controls security setting for the API. If isSecurity is true, the API authenticates user credentials supplied in the request.
If the credentials are valid, the API further ensures that the user is authorized to access the requested resource, as indicated by the role of the user. There are two types of administrative users:
Provider administrators have full access to the functions of the API. These users can modify data objects associated with any VPN subscriber.
Subscriber administrators can only access subscriber-specific operations, and only in the context of the VPN with which they are associated.
The VPN application includes a built-in provider administrator account named admin. You can use this account to create additional provider and subscriber administrator accounts.
Note:
The initial password for the built-in admin user is set during initial configuration of the database used to store VPN application data. See "Configuring Data Persistence" for more information.If security is enabled, client requests to the API must include the credentials of an administrator. The credentials should be supplied in the form of HTTP headers named name and password.
For example, a GET request submitted with user credentials would appear as follows:
GET /vpn/subscriber/vpn001/virtualusers HTTP/1.1
name: admin001
password: password
Host: 10.148.126.226
Accept: */*
A request that contains valid credentials but for a resource for which the administrator does not have privileges returns a 403 Forbidden error, as in the following example:
HTTP/1.1 403 Forbidden Content-Length: 0 Server: Jetty(8.0.1.0)
Note that the headers appear in HTTP requests in clear text. This may be acceptable in a test or evaluation system. However, in a production system, the connection should use Secure HTTP (HTTPS).
See "Opening an HTTP Listening Port for the VPN Provisioning Service" for information about using HTTPS to secure connections to the VPN Provisioning API.
When an operation succeeds, the VPN Provisioning API returns a response with HTTP status code 200.
An operation can fail for various reasons. For instance, an object you are creating may reference an object that does not yet exist; the JSON body of a request may be malformed; or field data may not match the expected form.
In general, if a request to the API fails, the VPN application returns an HTTP response with an error code that reflects the nature of the error. The error codes include:
400: The request body value is not correct. The response body contains detailed information about the error.
401: The user name or password is not correct.
403: The administrator does not have permission to access this object. (Such as an administrator for one VPN subscriber attempting to access settings for another.)
404: The URL style is unsupported or the resource does not exist in the system.
405: The method is not allowed.
406: The request method is not supported for this URL.
500: An internal system error occurred.
503: The service is unavailable.
An access control rule (AccessControlItem) is a common object in the VPN data model. It can be used by multiple types of other objects in the VPN data model.
An access control rule defines a particular type of restriction on the use of the VPN service. In general, you use it to match a telephone number to a time-based or call-type restriction. For example, an access control rule can specify call blocking to a number at a particular time or for a particular call type.
Each access control rule consists of these parameters:
type
range
timeSpan
permit
The type indicates the type of call to which the rule applies. Its value is an integer from 0 through 9, as follows:
0: A telephone number range, which is specified in the range value by using a wildcard (*) character
1: A single telephone number
2: Inside group
3: Outside group
4: Inside VPN
5: Outside VPN
6: Inside service provider
7: Outside service provider
8: National
9: International
The range value applies to type 0 or type 1 rules. It indicates the phone number to which the rule applies. For type 0 rules (a range), the range can include wildcard characters (*).
For type 1 rules (single), the range should indicate the specific phone number to which the rule applies. For the rule to apply, the specified number must fully match the actual number.
For other types of rules, the range value can be omitted.
The timeSpan parameter specifies the time of day that the rule applies. It takes an integer value, from 0 through 3, as follows:
0: All times
1: Within working hours for the subscriber
2: Outside working hours for the subscriber
The VPN application determines whether a particular time is within working hours based on the working time specified in the worktimeID parameter for the subscriber.
The permit value determines the effect of a rule match on the call. If permit is true, the call is allowed, if false, the call is blocked.
The following access control item permits access for the phone number "13522928011" during working hours:
{
"range":"13522928011",
"timeSpan":1,
"permit":true,
"type":1
}
The following example permits calls for numbers starting with 136 at any time:
{
"range":"136",
"timeSpan":0,
"permit":true,
"type":0
}
The following example forbids international calls outside of working hours:
{
"range":"",
"timeSpan":2,
"permit":false,
"type":9
}
In the context of an example profile, the access control items are defined as follows:
{
"description":"home profile",
"worktimeID":"busy",
"timeZone":8,
"callScreeningList":[
{
"range":"13522928011",
"timeSpan":1,
"permit":true,
"type":1
},
{
"range":"136*",
"timeSpan":0,
"permit":true,
"type":0
}],
"callBarringList":[
{
"range":"",
"timeSpan":2,
"permit":false,
"type":9
}],
"durationControlList":[99999;99999;99999;99999]
}
|
 Copyright © 2011, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|