Introducing TCXC AAA API

Introduction

The AAA server does just as its name suggests: it authenticates or validates subscribers and their credentials, verifies what services and QoS each subscriber is authorized to access, and ensures proper accounting so that customers are accurately billed for the services they use.

Authentication

The first step in AAA security is Authentication. It serves as the first line of defense in protecting network resources against fraud and identity theft, employing multimodal authentication methods.

Whenever anyone tries to access the network, the job of the Authentication function is identifying whether they are meant to be granted access, and also ensuring that the user is in fact who they claim to be. It does so by ensuring the user enters valid credentials, such as username, password, biometrics, or any other security measures that have been implemented by the operator. These credentials are stored in the operator’s database, against which the Auth server verifies the input given by the user. This database is constantly updated and monitored by network and system administrators.

If the user’s credentials are valid, they are granted access. Those with fraudulent or erroneous credentials are denied access. All network use of verified users is monitored and logged for future reference.

Authorization

Once authenticated, the next step for the AAA is determining what policies apply to the user. These policies will govern the user’s authorization levels, defining what resources, services, and QoS the user can access.

AAA policies can be defined on a host of parameters, such as the time or day, the user’s location, how often they’ve logged in, how much they’ve consumed, fair usage, and so on. These policies can also restrict certain actions, such as retrieving and/or changing passwords.

Accounting

The final step for the AAA server is to take stock of the network resources accessed by the user, such as network usage consumption and duration of their session.

These usage details serve two purposes. One, they ensure the user is accurately invoiced for their consumption. Another important aspect of accounting is to enable administrators to access audit logs to review how and by whom the network was accessed. This usage data is useful to gain valuable insights into customer behavior, usage patterns, and more. This business intelligence (BI) insights help operators create more contextual offerings and enable them to anticipate network use.

TCXC AAA API (Developer Preview)

Simple components and APIs for managing communication service providers AAA needs in one place: SIP, SMPP, HLR, Numbers NRC, MRC.

After over a decade of internally developing and using the TCXC AAA to Authenticate, Authorize and Account for billions of transactions accurately and successfully, we have decided to invest in exposing the AAA as an Application Programming Interface to trusted third-party telecom developers, to unlock new possibilities for operators modernizing their network using different flavors of CPaaS middleware.

How it works?

We have developed HTTP API endpoints according to TCXC’s existing AAA protocols/logics, TCXC platform administrator can create credentials for trusted developers, as soon they provide the client IP address for API (NAS IP address). The developer can use different IPs for different NAS types (SIP/SMPP), Below is the developer documentation for TCXC AAA API (Preview).

General

API requests are supposed to be sent using HTTP(S) towards supplied endpoints using the POST method. NAS (API client) is authorized using 2 supplied parameters “nas_login” and “nas_password” also the sender IP address is checked, so make sure it is authorized.

Parameters:
Parameters are supposed to be sent as HTTP parameters.

API Response:

The API response will be supplied in JSON format with different parameters supplied depending on the endpoint.

The only parameter supplied for all responses is “status” which may get three possible values:

• “error”, there was an API error, more details about an error may be found in the parameter “error_message”
• “failed”, API worked, and the result is “AAA operation failed”
• “accept”, API worked, and AAA operation is allowed. There may be other important information in “attributes” depending on the endpoint.

Endpoints:

1. /aaa_authenticate

Expected request parameters: “user_name”, “cld”.
This AAA endpoint is used to authenticate SIP/VoIP callers. The endpoint will return a cleartext password so that NAS can perform digest authentication. For remote IP authentication, “user_name” should contain an IP address cleartext password will be set to “cisco”.

Examples:

Remote ip authentication example:

curl -d "nas_login=AAASID&nas_password=AAATOKEN&user_name=192.168.3.1&cld=123" https://apiv2.tcxcpaasdomain.com/aaa_authenticate.php

{
"status": "accept",
"attributes": [
{
"attribute": "Cleartext-Password",
"value": "cisco"
}
]
}

Digest authentication example:

curl -d "nas_login=aaatest&nas_password=aaatest&user_name=6XEDOma3&cld=123" https://apiv2.tcxcpaasdomain.com/aaa_authenticate.php
{
"status": "accept",
"attributes": [
{
"attribute": "Cleartext-Password",
"value": "XXXpasswordXXX"
},
{
"attribute": "Auth-Type",
"value": "Digest"
}
]
}

2. /aaa_authorize

Expected request parameters: “user_name”, “cld”, “cli”, “call_id”, “client_remote_ip”.
This AAA endpoint can authorize a SIP call. In case of successful authorization, the response will contain an indexed list of SIP routes in sippy b2bua format (details of this format may be found here https://github.com/sippy/b2bua/blob/master/documentation/documentation.md).

An indexed list means that there could be more than 1 route, for example, Route1, Route2, and Route3.
It is expected that NAS will try these routes sequentially in the specified order, first Route1 then Route2, and finally Route3 until one of the calls gets answered on a route.

It is also expected that NAS will manipulate SIP call id in the following way:

Route1 originate call leg will be “original client call_id” (supplied as call_id parameter) suffixed with “-b2b_1”.

Route2 originate call leg will be “original client call_id” (supplied as call_id parameter) suffixed with “-b2b_2”.

Route3 originate call leg will be “original client call_id” (supplied as call_id parameter) suffixed with “-b2b_3”.

Note, that actual SIP call Id manipulation is not required to happen for SIP calls ( but desired), it is only required in parameters supplied to TCXC AAA API.
Note, that in case of successful authorization “Stop Accounting” API call is required for the SIP call attempt using the following logic:

in case there was just 1 route (Route1) stop accounting API call is required for it, even if the call failed.
If there were multiple routes, say Route1, Route2, and Route3, a stop accounting API call is required for all attempted SIP routes. So if the SIP call was connected on Route2, a stop accounting API call is not required only for Route3 ( because it was not attempted).

Examples:

The single route in result:

curl -d "nas_login=aaatest&nas_password=aaatest&user_name=12.34.56.78&cld=32376#18661234567&cli=1234567&call_id=11122233&client_remote_ip=12.34.56.78" https://apiv2.tcxcpaasdomain.com/aaa_authorize.php
{
"status": "accept",
"attributes": [
{
"attribute": "Route1",
"value": "Routing:666618661234567@1.2.3.4:5060;cli=1234567;credit-time=3600;rid=-1;expires=60;np_expires=10"
}
]
}

Multiple routes:

curl -d "nas_login=aaatest&nas_password=aaatest&user_name=12.34.56.78&cld=44444012#18661234567&cli=1234567&call_id=11122233&client_remote_ip=12.34.56.78" https://apiv2.tcxcpaasdomain.com/aaa_authorize.php
{
"status": "accept",
"attributes": [
{
"attribute": "Route1",
"value": "Routing:18661234567@1.2.3.4:6088;cli=1234567;credit-time=3600;rid=-1;expires=60;np_expires=10"
},
{
"attribute": "Route2",
"value": "Routing:10578#18661234567@12.23.56.78;cli=1234567;credit-time=3600;rid=-1;auth=VLOGIN:VPASSWORD;expires=59;np_expires=9"
},
{
"attribute": "Route3",
"value": "Routing:18661234567@11.22.33.44;cli=1234567;credit-time=3600;rid=-1;expires=60;np_expires=10"
},
{
"attribute": "Route4",
"value": "Routing:18661234567@127.0.0.1:1111;cli=1234567;credit-time=3600;rid=-1;auth=VVVLOGIN:VVVPASSWORD;expires=60;np_expires=10"
},
{
"attribute": "Route5",
"value": "Routing:18661234567@192.168.7.1:53000;cli=1234567;credit-time=3600;rid=-1;auth=SECRETLOGIN:SECRETPASSWORD;expires=60;np_expires=10"
}
]
}

3. /aaa_accounting_start

Expected request parameters: “setup_time”, “connect_time”, “call_id”.

This API call is expected upon the call to get into the connected state. Setup time is the tie of the original INVITE from the client, and connect time is the time when the call is counted as connected.
Both dates/times are expected in the following format: 12:35:26.032119 GMT Fri Oct 21 2022

Examples:

curl -d "nas_login=aaatest&nas_password=aaatest&setup_time=12:35:26.032119 GMT Fri Oct 21 2022&connect_time=12:36:26.032119 GMT Fri Oct 21 2022&call_id=11122233-b2b_2" http://apiv2.tcxcpaasdomain.com/aaa_accounting_start.php
{
"status": "accept"
}

4. /aaa_accounting_stop.php

Expected request parameters:
“call_origin” – may take 1 out of 2 values “originate” or “answer”. “originate” is for the calls that has been attempted to termination partner. “answer” is for calls canceled by the caller without an attempt to terminate with a partner.

"setup_time" - time of call setup (SIP INVITE) received by NAS (format 12:35:26.032119 GMT Fri Oct 21 2022)

"connect_time" - time of call connect (SIP 200 OK) sent to clitn (format 12:35:26.032119 GMT Fri Oct 21 2022)

"disconnect_time" - time of call disconnect (BYE or SIP error code) received (format 12:35:26.032119 GMT Fri Oct 21 2022)

"call_id" - SIP call id of the call (must conform call id suffix guidelines explained in 2) )

"duration" - call duration in seconds (integer values expected, 0 for failed calls)

"disconnect_code" - Q.931 disconnect cause code (integer value expected)

"client_remote_ip" - call remote ip address.

This API call is called after call disconnect/failure. For multiple routes attempted NAS should have multiple accounting stop calls.

Examples:

curl -d "nas_login=aaatest&nas_password=aaatest&setup_time=12:35:26.032119 GMT Fri Oct 21 2022&connect_time=12:37:26.032119 GMT Fri Oct 21 2022&disconnect_time=12:38:26.032119 GMT Fri Oct 21 2022&call_id=11122233-b2b_1&duration=60&disconnect_code=16&client_remote_ip=12.34.56.78" https://apiv2.tcxcpaasdomain.com/aaa_accounting_start.php
{
"status": "accept"
}

5. /aaa_bind
   

Expected request parameters:

• “user_name” – SMPP System ID
• “password” – SMPP Password
• “client_remote_ip” – remote IP address of the client

This endpoint controls whether to allow or disallow incoming SMPP BIND.
Upon success, the endpoint will return the session_id token and i_account.
The token is expected to be provided back to API using the “/aaa_unbind.php” endpoint upon client session unbind.
The value of i_account on a certain BIND session is expected to be provided for the “/aaa_smpp_authorize.php” endpoint for the authorization/routing step.

Example:

curl -d "nas_login=aaatest&nas_password=aaatest&user_name=V6FT9iZj&password=ZxIdeloR&client_remote_ip=12.34.56.78" https://apiv2.tcxcpaasdomain.com/aaa_bind.php
{
"status": "accept",
"session_id": "JMSFelp8N3",
"i_account": "4"
}

6. /aaa_unbind
   Expected paramets: “session_id”
   This endpoint should be notified upon client session UNBIND or close. Session Id parameter should be the same as the one returned by API upn BIND.

Example:

curl -d "nas_login=aaatest&nas_password=aaatest&session_id=JMSFelp8N3" https://apiv2.tcxcpaasdomain.com/aaa_unbind.php
{
"status": "accept"
}

7. /aaa_smpp_authorize

Expected request parameters:

“session_id” – session-id token received from a successful call to “/aaa_bind.php”,
“i_account” – account id received from a successful call to “/aaa_bind.php”,
“source_addr” – sender address of the SMS,
“destiation_addr” – destination address of the SMS,
“short_message” – text of the short message

This AAA endpoint can authorize/route an SMS. In case of successful authorization, the response will contain an indexed list of SIP routes in a format similar to the b2bua format.

An indexed list means that there could be more than 1 route, for example, Route1, Route2, and Route3.
It is expected that NAS will try these routes sequentially in the specified order, first Route1 then Route2, and finally Route3 until one of the SMS gets successfully sent on a route.

Parameters of the route explained:

• “destination” – host: port where to send SMS
• “login” – system ID to be used for outgoing BIND
• “pass” – password to be used for outgoing BIND
• “session_timeout” – SMPP session timeout for a route (seconds), after which BIND may be closed due to inactivity
• “smpp_ka_interval” – SMPP enquire_link interval for a route (seconds)
• “submit_sm_timeout” – SMPP submit_sm operation timeout in seconds
• “destination_number” – destination address in vendor format
• “source_addr” – source address for sending SMS

below parameters are required only for accounting purposes, and should be provided to “/aaa_smpp_accounting” exactly as they were received from authorization:

"i_customer", "i_purchased_route", "i_connection", "i_vendor", "smpp_commission", "i_rate", "billed_msgs_cnt", "billing_prefix", "billing_i_account", "price".

Unlike for the VoIP authorization where only the routes that were attempted must be reported with “accounting stop” for SMPP authorizations all the returned routes must be reported to the “/aaa_smpp_accounting.php” endpoint.

Examples:

curl -d "nas_login=aaatest&nas_password=aaatest&session_id=JMSFelp8N3&i_account=4&source_addr=O2App&destination_addr=380911234567&short_message=aaa" https://apiv2.tcxcpaasdomain.com/aaa_smpp_authorize.php
{
"status": "accept",
"attributes": [
{
"attribute": "Route1",
"value": "destination:108.61.167.86:9870;login:perftest;pass:perftest;session_timeout:30;smpp_ka_interval:0;submit_sm_timeout:120;destination_number:380911234567;i_customer:1;i_purchased_route:150;i_connection:43;i_vendor:8;smpp_commission:0;i_rate:226997;billed_msgs_cnt:1;billing_prefix:380;billing_i_account:4;price:0.015"
}
]
}

curl -d "nas_login=aaatest&nas_password=aaatest&session_id=JMSFelp8N3&i_account=4&source_addr=O2App&destination_addr=123#380911234567&short_message=aaa" https://apiv2.tcxcpaasdomain.com/aaa_smpp_authorize.php
{
"status": "failed"
}

8. /aaa_smpp_accounting

Expected request parameters:

• “session_id” – session-id token received from a successful call to “/aaa_bind.php”,
• “i_account” – account id received from a successful call to “/aaa_bind.php”,
• “source_addr” – sender address of the SMS,
• “destiation_addr” – destination address of the SMS,
• “short_message” – text of the short message,
• “attempted” – 0 or 1 expected, whether the route was attempted by NAS or not,
• “sent” – whether SMS was successfully sent to the route (with command_statu=0 returned),
• “message_id” – message_id returned by the route (empty value expected for failed/non-attempted routes),
• “error_text” – error text explanation in case of failure, for example ‘host is down’ returned by the route (empty value expected for successful/non-attempted routes),
• “i_connection” – value should be taken from the authorization parameter,
• “i_vendor” – value should be taken from the authorization parameter,
• “smpp_commission” – value should be taken from the authorization parameter,
• “i_rate” – value should be taken from the authorization parameter,
• “billed_msgs_cnt” – value should be taken from the authorization parameter,
• “billing_prefix” – value should be taken from the authorization parameter,
• “billing_i_account” – value should be taken from the authorization parameter,
• “price” – value should be taken from the authorization parameter

This call is required to report the result of every Route returned by authorization even if the route was not attempted, as it will release the reserved amounts for it.

Examples:

curl -d "nas_login=aaatest&nas_password=aaatest&session_id=JMSFelp8N3&i_account=4&source_addr=O2App&destination_addr=380911234567&short_message=aaa&sent=1&attempted=1&i_customer=1&i_purchased_route=150&i_connection=43&i_vendor=8&smpp_commission=0&i_rate=226997&billed_msgs_cnt=1&billing_prefix=380&billing_i_account=4&price=0.015&message_id=12121212&error_text=" https://apiv2.tcxcpaasdomain.com/aaa_smpp_accounting.php
{
"status": "accept"
}

9. “/aaa_smpp_delivered.php”

Expected request parameters:
“message_id” – message_id of the delivered message

This endpoint may be called upon receiving the delivery report (stat:DELIVRD) to mark the SMS as delivered. The only parameter of message-id is required.

Examples:

curl -d "nas_login=aaatest&nas_password=aaatest&message_id=12121212" https://apiv2.tcxcpaasdomain.com/aaa_smpp_delivered.php
{
"status": "accept"
}