POST. Authentication. API/1111. Parameters: The excepted return result is:
Example 3 – Unlocking a user. Unlocking the user Joe. Page=UserEdit. Modify=1
.
Aradial User Management HTTP API Specification
Aradial User Management HTTP API Specification
©2008 Aradial This document contains proprietary and confidential information of Aradial and shall not be reproduced or transferred to other documents, disclosed to others, or used for any purpose other than that for which it is furnished, without the prior written consent of Aradial. It shall be returned to the Aradial upon request. The trademark and service marks of Aradial, including the Aradial logo, are the exclusive property of Aradial, and may not be used without permission. All other marks mentioned in this material are the property of their respective owners.
Document Information Software Version: Document Version: Publication Date:
Page 2
3.8 1.3 September 2008
Aradial User Management HTTP API Specification
Contents 1.
Introduction.......................................................................................................................... 4 Document Purpose and Scope ................................................................................................... 4 2. Principles of the API ........................................................................................................... 5 HTTP Server............................................................................................................................... 5 HTTP Method............................................................................................................................. 5 URL Format................................................................................................................................ 5 Security........................................................................................................................................ 5 The Page Parameter.................................................................................................................... 6 Query Mechanism ...................................................................................................................... 6 Date and time formats ................................................................................................................ 8 3. User Management API ....................................................................................................... 9 Create User.................................................................................................................................. 9 Update User .............................................................................................................................. 12 Delete User................................................................................................................................ 19 Get User List ............................................................................................................................. 21 Get Single User......................................................................................................................... 24 Get User Online Sessions......................................................................................................... 26 Get User Session History ......................................................................................................... 29 4. Group management API .................................................................................................. 32 Create a group........................................................................................................................... 32 Update Group............................................................................................................................ 37 Delete a group........................................................................................................................... 40 Get Group List .......................................................................................................................... 42 Get a Single Group ................................................................................................................... 45 5. Dynamic Authorization APIs .......................................................................................... 47 Passive Disconnect a Session................................................................................................... 47 Radius Forwarder ..................................................................................................................... 49 Disconnect Session................................................................................................................... 50 Change of Authorization .......................................................................................................... 52 RADIUS User Request ............................................................................................................ 54 Disconnect User........................................................................................................................ 56
Page 3
Aradial User Management HTTP API Specification
1. Introduction Document Purpose and Scope This document describes the HTTP variant of Aradial User Management API. This API is used to manage user profiles in Aradial user database. The API provides CRUD (Create/Read/Update/Delete) operations for the user profile entity, and specifically it provides the following operations: • Add a user • Modify a user • Delete a user • Search for a user • Get user online sessions • Get user session history The document includes the following chapters: • • • • •
Chapter 1 – Introduction Chapter 2 – Principles of the API Chapter 3 – Provides a detailed description of the User Management API Chapter 4 – Group management APIs Chapter 5 – Miscellaneous APIs
Page 4
Aradial User Management HTTP API Specification
2. Principles of the API HTTP Server The API is implemented by the Aradial Admin web server. This is the same server that implements the Aradial Admin application, although a separate instance of the server can be deployed to serve the API.
HTTP Method The API has the form of an HTTP request, with a POST or GET method. Except for the Add/Modify user operations, which must use the POST method, all other operations can use either POST or GET.
URL Format The API request should use the following URL format: http://{address of Aradial Admin}:{Port Of Aradial Admin}/Admin Example: http://localhost:8000/Admin
Security All API requests must include authentication information, according to the HTTP basic authentication scheme. The authentication information must point to an Aradial user with the “API” administration rights, which is a special type of user role that is used for the user management API. Example: Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== Note: The user name and password are base64 encoded.
Page 5
Aradial User Management HTTP API Specification NOTE: Aradial default database does not contain any user with an API admin rights. Therefore, before using the API, such a user must be created in the Aradial user database and used in all API invocations.
The Page Parameter The page parameter is used in all the API operations and is used determine the type of operation used by the request. Examples: • In order to update user information, the page name is "UserEdit" • In order to get user sessions, the page name is "UserSessions".
Query Mechanism The User Management API provides a mechanism for performing complex queries. A complex query is described using one or more HTTP parameters as described below: Name qdb_XXX
op_XXX
qdb_clause
Page 6
Description A Parameter with the "qdb_" prefix describes an expression to be included in the "where" clause of the query SQL statement that will be performed on the Aradial database. The XXX is the field name for which the value is checked. The relation operation associated with the parameter is equality (Match for Strings), except if specified otherwise (See the op_XXX parameter). The Field name may have on of the following formats: • fieldname – No type is specified, considered to be string • $fieldType$fieldName – The field type is specified, and may be one of the following: o S – String o N – An integer number o F – Floating point number o D – Date. The date format should be according to the "DateFormat" setting in the "Misc" configuration section, or "MM-DD-YY" if not specified. o T – Time of day, should be in "hh[:mm][:ss] format o I - IP Address, should be in numeric format (xxx.yyy.zzz.aaa) A parameter with the "op_" prefix describes the relational operation to do for a single qdb_ parameter. This parameter must be placed before the qdb_XXX parameter to which it relates. The operator should be one of the following: ">", "{Session1-InTime}
{Session1-Service} | {Session1-CallerId} | {Session1-OutputOctets} | {Session1-InputOctets} | {Session1-FramedAddress} | . .
The result contains a set of …
elements, one for each session in the result set. Failure Result Following is the format of a failure result:
Example Fetch all sessions for DemoUser1 between the dates 1-1-2005 and 1-31-2005. The following HTTP request will be used: HTTP Variable Value URL http://localhost:8000/Admin Method GET Authentication API/1111
Page 30
Aradial User Management HTTP API Specification Parameters: Page=UserSessions qdb_Users.UserId=DemoUser1 op_$D$AcctDate=> qdb_$D$AcctDate=1/1/2005 op_$D$AcctDate=< qdb_$D$AcctDate=1/31/2005
The excepted return result is: | DemoUser1 | NasSim | 1 | 01/07/05 20:46:41 | PPP | | 0 | 0 | 255.255.255.254 |
| DemoUser1 | NasSim | 1 | 01/14/05 19:14:41 | PPP | | 0 | 0 | 255.255.255.254 |
Page 31
Aradial User Management HTTP API Specification
4. Group management API Create a group Description Create a new group in the Aradial database.
Http Method Must be POST.
Parameters Name Page Add db_$RS$GroupName db_$N$IsSubGroup db_$N$NASIndex db_$N$Active db_$N$Service db db_$N$EnableCallback db_IPPool db_$N$MultiSessionAsMultiLnk db_$RN$PasswordSource
db_$N$AutoAddOnFirstConnect
Page 32
Description Type Selects the Create Group operation. Must be M “GroupEdit”. Indicates that this is an add operation. Must M have a value of “1”. The Group name. M Indicate whether its SubGroup: 1- SubGroup, M 0-Group The NAS Index, should be 0 if not SubGroup. O Indicate whether the group is Active (1O Active, 0-Not Active). The default service ID that associated with this O group. A Flag indicating whether to enable callback O (1 – Enable, 0 – Disabled) The list of IP Pools that are used by this group. O Indicate whether to treat multi session as O multilink (1 – Enable, 0 – Disabled) The Password source: O 0 - According to default settings. 1- Aradial users database 2 - From OS 3 - From LDAP database 4 - From as Secure ID device 5 - No Password Determine whether to AutoAdd the users on O 1st connect. (1 – Enable, 0 – Disabled)
Aradial User Management HTTP API Specification db_$I$RemoteIP db_FilterName db_CallerIDTemplate db_NASAttributes db_$N$MaxTotGroupSess db_$N$MaxSameUserSess db_$N$NoAccessBySesLimit db_$F$SessionLimit db_$F$IdleTime db_$N$BusinessEntityIndex db_$RN$AutoExpirePolicy
db_$N$AutoExpireTime db_$D$AcctStartDate db_$D$AcctExpireDate db_AfterAddUserCommand db_$N$BlackList db_$N$WhiteList db_OnUpdateCommand db_AfterDelUserCommand db_OnPasswordChangeCommand db_OnDeActiveCommand db_OnReActiveCommand
Page 33
The remote IP of the user. The filter name. The CallerID template. Group level parameters used for personalized authorization definitions. The maximum number of sessions for this group (0 – No Limit) The maximum number of sessions for each user in this group (0 – No Limit) A flag to determine whether to apply the session limit setting (1 = Yes, 0 =No) The session limit in seconds. The session idle time The index of a business entity that is related to this group. The AutoExpire Policy: 0 - None 1- Minutes 2 - Hours 3 - Days The AutoExpire time (According to Policy). The start date to accept this group. The end date to accept this group. An operation to do when adding a user to this group. The Black List Id The White List Id An operation to do when updating a user from this group. An operation to do when deleting a user from this group An operation to do when changing a password of a user in this group. An operation to do when deactivating a user in this group. An operation to do when reactivating an user in this group
O O O O O O O O O OV O
O O O O O O O O O O O
Aradial User Management HTTP API Specification
Return Result Success Result Following is the format of a success result:
Failure Result Following is the format of a failure result:
Example – Create a group Add a group with the name "Series1" that has Service of PPP (number 1) and limit the maximum user sessions to 1 The following HTTP request will be used: HTTP Variable Value URL http://localhost:8000/Admin Method POST Authentication API/1111
Page 34
Aradial User Management HTTP API Specification Parameters: Page=GroupEdit Add=1 db_$RS$GroupName=Series1 db_$N$IsSubGroup=0 db_$N$Active=1 db_$N$Service=1 db_$N$MaxSameUserSess=1 db_$N$MaxTotGroupSess=0 The excepted return result is:
Example – Create a sub group Add a sub group to series1 for NAIndex 1. For that NAS, allow users to login twice. The following HTTP request will be used: HTTP Variable Value URL http://localhost:8000/Admin Method POST Authentication API/1111 Parameters: Page=GroupEdit Add=1 db_$RS$GroupName=Series1 db_$N$NASIndex=1 db_$N$Active=1 db_$N$Users.UserService=1 db_$N$MaxSameUserSess=2
Page 35
Aradial User Management HTTP API Specification The excepted return result is:
Page 36
Aradial User Management HTTP API Specification
Update Group Description Update a group in the Aradial database.
Http Method Must be POST.
Parameters Name Page Modify GroupName NASIndex db_$RS$GroupName db_$N$IsSubGroup db_$N$NASIndex db_$N$Active db_$N$Service db db_$N$EnableCallback db_IPPool db_$N$MultiSessionAsMultiLnk db_$RN$PasswordSource
db_$N$AutoAddOnFirstConnect db_$I$RemoteIP db_FilterName db_CallerIDTemplate Page 37
Description Type Selects the Update Group operation. Must be M “GroupEdit”. Indicates that this is an update operation. Must M have a value of “1”. The original Group name. M The original NAS Index O The Group name. O Indicate whether it is a SubGroup: 1O SubGroup, 0-Group The updated NAS Index, should be 0 if not O SubGroup. Indicate whether he group Active (1- Active, O 0-Not Active). The default service ID that associated with this O group. A Flag indicating whether to enable callback O (1 – Enable, 0 – Disabled) The list of IP Pools that are used by this group. O Indicate whether to treat multi session as O multilink (1 – Enable, 0 – Disabled) The Password source: O 0 - According to default settings. 1- Aradial users database 2 - From OS 3 - From LDAP database 4 - From as Secure ID device 5 - No Password Determine whether to Auto Add the users on O 1st connect. (1 – Enable, 0 – Disabled) The remote IP of the user. O The filter name. O The CallerID template. O
Aradial User Management HTTP API Specification db_NASAttributes db_$N$MaxTotGroupSess db_$N$MaxSameUserSess db_$N$NoAccessBySesLimit db_$F$SessionLimit db_$F$IdleTime db_$N$BusinessEntityIndex db_$RN$AutoExpirePolicy
db_$N$AutoExpireTime db_$D$AcctStartDate db_$D$AcctExpireDate db_$N$BlackList db_$N$WhiteList db_AfterAddUserCommand db_OnUpdateCommand db_AfterDelUserCommand db_OnPasswordChangeCommand db_OnDeActiveCommand db_OnReActiveCommand
Group level parameters used for personalized authorization definitions. The maximum number of sessions for this group (0 – No Limit) The maximum number of sessions for each user in this group (0 – No Limit) A flag to whether to apply the session limit setting (1 = Yes, 0 =No) The session limit in seconds. The session idle time The index of a business entity that is related to this group. The Auto Expire Policy: 0 - None 1 - Minutes 2 - Hours 3 – Days The Auto Expire time (According to Policy). The start date to accept this group. The end date to accept this group. The Black List Id The White List Id An operation to do when adding a user to this group. An operation to do when updating a user from this group. An operation to do when deleting a user from this group An operation to do when changing a password to a user in this group. An operation to do when deactivating a user in this group. An operation to do when reactivating a user in this group
Return Result Success Result Following is the format of a success result: Page 38
O O O O O O OV O
O O O O O O O O O O O
Aradial User Management HTTP API Specification
Failure Result Following is the format of a failure result:
Example 1 – Modify user service Modify the service of the Group “Series1” to Rlogin (number 7 according to NasCfgDbs). The following HTTP request will be used: HTTP Variable Value URL http://localhost:8000/Admin Method POST Authentication API/1111 Parameters: Page=GroupEdit Modify=1 GroupName=Series1 db_$N$Service=7 The excepted return result is:
Page 39
Aradial User Management HTTP API Specification
Delete a group Description Delete a group from the Aradial database.
Http Method Get or POST.
Parameters Name Page ConfirmDelete GroupName NASIndex
Description Selects the Update Group operation. Must be “GroupEdit”. Indicates that this is a delete operation. Must have a value of “1”. The group name to delete The NASIndex if SubGroup
Return Result Success Result Following is the format of a success result:
Failure Result Following is the format of a failure result:
Page 40
Type M M M O
Aradial User Management HTTP API Specification
Example Delete the group “Series1”. The following HTTP request will be used: HTTP Variable Value URL http://localhost:8000/Admin Method GET Authentication API/1111 Parameters: Page=GroupEdit ConfirmDelete=1 GroupName=Series1 The excepted return result is:
Page 41
Aradial User Management HTTP API Specification
Get Group List Description Fetch all the groups or all subgroups of a group
Http Method Get.
Parameters Name Page MainGroup
Description Selects the get group list operation. Must be “GroupHit”. The main group, in case of fetch a sub group.
Type M O
Return Result Success Result Following is the format of a success result: | {Group1-Id} | {Group1-Service} | {Group1- IPPoold} | . .
. . | {GroupN-Id} | {GroupN-Service} | {GroupN- IPPoold} | . .
The result contains a set of …
elements, one for each user in the result set. Each such element contains all the fields of the Group table.
Page 42
Aradial User Management HTTP API Specification
Failure Result Following is the format of a failure result:
Example – Fetch All main groups Fetch all Groups The following HTTP request will be used: HTTP Variable Value URL http://localhost:8000/Admin Method GET Authentication API/1111 Parameters: Page=GroupHit The excepted return result is: | Wifi 1 | 1 | Pool1 | . .
. . | Analog | 1 | Pool2 | . .
Page 43
Aradial User Management HTTP API Specification
Example – Fetch a sub group Fetch all SubGroups of the group "Analog" The following HTTP request will be used: HTTP Variable Value URL http://localhost:8000/Admin Method GET Authentication API/1111 Parameters: Page=GroupHit MainGroup=Analog The excepted return result is: | Analog | 1 | 1 | Poo3 | . .
. . | Analog | 2 | 1 | Pool4 | . .
Groups>
Page 44
Aradial User Management HTTP API Specification
Get a Single Group Description Fetch a single group based on the GroupName or GroupName and NASIndex
Http Method Get.
Parameters Name Page GroupName NASIndex
Description Selects the get user details operation. Must be “UserEdit”. The group name to fetch. The NAS Index, if Sub Group
Return Result Success Result Following is the format of a success result: {Name} | {Service} | {Pools} | . .
The result contains a set of … | elements, one for each column of the group. Failure Result Following is the format of a failure result:
Example Fetch the Group “Wifi”. Page 45
Type M M O
Aradial User Management HTTP API Specification
The following HTTP request will be used: HTTP Variable Value URL http://localhost:8000/Admin Method GET Authentication API/1111 Parameters: Page=GroupEdit GroupName=Wifi The excepted return result is: Wifi | 1 | Pool1 | . .
Page 46
Aradial User Management HTTP API Specification
5. Dynamic Authorization APIs Passive Disconnect a Session Description Do a passive disconnect to a specific session. See "Get User Online Sessions" in order to fetch the correct session.
Http Method Get or Post.
Parameters Name Page NasId NasPort AcctSessId
Description Selects the "Session Delete" operation. Must be “SessionDelete”. The NAS ID (From the fetch) The NAS Port (From the fetch) The Accounting session ID (From the fetch)
Return Result Success Result Following is the format of a success result:
Failure Result
Page 47
Type M M M M
Aradial User Management HTTP API Specification Following is the format of a failure result:
Example Delete the Session with NASId= 127.0.0.1, NasPort=200 and Account session ID=Sess00001. The following HTTP request will be used: HTTP Variable Value URL http://localhost:8000/Admin Method GET Authentication API/1111 Parameters: Page= SessionDelete NasId = 127.0.0.1 NasPort=20 AcctSessId=Sess00001 The excepted return result is:
Page 48
Aradial User Management HTTP API Specification
Radius Forwarder Description A generic method to send a Radius request on the Radius server.
Http Method Get or Post.
Parameters Name Page Rad_ReqCode Rad_SuccessCode RadAttr_{Attribute Name}
Description Type Selects the "Radius Forwarder" operation. Must be M “RadForward”. The radius request code. M The response code to consider as success M A radius attribute to populate in the request. O Where: • Attribute Name – The Radius Attribute name.
Return Result Success Result Following is the format of a success result:
Failure Result Following is the format of a failure result: Page 49
Aradial User Management HTTP API Specification
Disconnect Session Description Causes to disconnect a single session. This is done using a PoD request from the server to the NAS.
Http Method Get or Post.
Parameters Name Page Rad_ReqCode Rad_SuccessCode RadAttr_User-Name RadAttr_Client-Id RadAttr_NAS-Port-Id RadAttr_Acct-Session-Id
Description Type Selects the "Radius Forwarder" operation. Must be M “RadForward”. The radius request code. Must be "40" for this M case. The response code to consider as success, Must be M "41" for this case. The UserName to disconnect. M The Client Identifier M The NAS port ID O The Accounting Session ID M
Return Result Success Result Following is the format of a success result:
Failure Result Following is the format of a failure result: Page 50
Aradial User Management HTTP API Specification
Example – Send POD request to a single user session Send a PoD request for the session "Session001", Port "200", Client Identifier "127.0.0.1" and user "Joe". The following HTTP request will be used: HTTP Variable Value URL http://localhost:8000/Admin Method GET Authentication API/1111 Parameters: Page= RadForward Rad_ReqCode =40 Rad_SuccessCode=41 RadAttr_User-Name=joe RadAttr_Client-Id=127.0.0.1 RadAttr_NAS-Port-Id=200 RadAttr_Acct-Session-Id=Session001 The excepted return result is:
Page 51
Aradial User Management HTTP API Specification
Change of Authorization Description Sends a Change of Authorization (CoA) message to the NAS to change the authorization parameters of a specific session. This is done using a CoA request from the RADIUS server to the user session.
Http Method Get or Post.
Parameters Name Page Rad_ReqCode Rad_SuccessCode RadAttr_User-Name RadAttr_Client-Id RadAttr_Acct-Session-Id CoA-Service
RadAttr_NAS-Port-Id
Description Type Selects the "Radius Forwarder" operation. Must be M “RadForward”. The radius request code. Must be "43" for this M case. The response code to consider as success. Must be M "44" for this case. The UserName associated with the session. M The Client Identifier M The Accounting Session ID M The name of the CoA service to use for the CoA M message. This service is defined in NasCfgDbs as a System Service. The NAS port ID O
Return Result Success Result Following is the format of a success result:
Page 52
Aradial User Management HTTP API Specification
Failure Result Following is the format of a failure result:
Example – Send CoA request for system service “CoA-Session-Timeout” Send a CoA request to the session "Session001", Port "200", Client Identifier "127.0.0.1" and user "Joe" using the “CoA-Session-Timeout” system service. The following HTTP request will be used: HTTP Variable Value URL http://localhost:8000/Admin Method GET Authentication API/1111 Parameters: Page= RadForward Rad_ReqCode =43 Rad_SuccessCode=44 RadAttr_User-Name=joe RadAttr_Client-Id=127.0.0.1 RadAttr_NAS-Port-Id=200 RadAttr_Acct-Session-Id=Session001 CoA-Service=CoA-Session-Timeout The excepted return result is:
Page 53
Aradial User Management HTTP API Specification
RADIUS User Request Description A generic method to send a RADIUS request to all of the sessions of a given user. This method loops over the user sessions and for each one, sends a RADIUS request that contains the “User-Name”, “Client-Id", “NAS-Port-Id”, “Acct-Session-Id” RADIUS attributes and a set of custom attributes according to the HTTP parameters with the “RadAttr_” prefix.
Http Method Get or Post.
Parameters Name Page Rad_ReqCode UserId RadAttr_{Attribute Name}
Description Type Selects the "Radius Forwarder" operation. Must be M “RadForward”. The radius request code. M The UserId M A RADIUS attribute to populate in the request in O addition to “User-Name”, “Client-Id", “NAS-PortId” and “Acct-Session-Id”. Where: • Attribute Name – The RADIUS Attribute name.
Return Result Success Result Following is the format of a success result:
Page 54
Aradial User Management HTTP API Specification Failure Result Following is the format of a failure result:
Page 55
Aradial User Management HTTP API Specification
Disconnect User Description Causes to disconnect all users sessions using RADIUS User Request. This is done using POD from the server to all User Sessions.
Http Method Get or Post.
Parameters Name Page Rad_ReqCode UserId
Description Selects the "RADIUS User Request" operation. Must be “RadUserRequest”. The RADIUS request code. Must be "40" for this case. The User Name to disconnect.
Return Result Success Result Following is the format of a success result:
Failure Result Following is the format of a failure result:
Example 1 – Send POD request to all user sessions Send POD request to all sessions of the user "Joe" Page 56
Type M M M
Aradial User Management HTTP API Specification
The following HTTP request will be used: HTTP Variable Value URL http://localhost:8000/Admin Method GET Authentication API/1111 Parameters: Page=RadUserRequest Rad_ReqCode =40 UserId=joe
The excepted return result is:
Page 57
