The access level of this API user is [% SWITCH c.user.roles %] [%- CASE 'admin' %] admin [%- CASE 'reseller' %] reseller [%- CASE 'subscriberadmin' %] subscriberadmin [%- CASE 'subscriber' %] subscriber [%- CASE %] (unknown) [%- END %].
Authentication and authorization on the Sipwise NGCP HTTP API is performed via HTTP Basic Auth [% IF is_admin_api %] or SSL Client Certificates[% END -%] [% IF is_subscriber_api %] or JSON Web Token (JWT)[% END -%] .
With cURL, use --user 'username:password' option to specify your access credentials. Specifying the realm is not needed here.
curl -i -X GET --user 'myuser:mypassword' https://example.org:1443/api/
Additionally use the --insecure option if you are testing against a self-signed server certificate.
Read the Part SSL Certificates under the Chapter Security and Maintenance in the SPCE documentation
for more information about SSL Certificates.
With LWP::UserAgent, set the credentials using the credentials() function. The first parameter is your server (credentials are only sent if the host:port in the request matches the one specified here), the second one is the realm (always [% current_http_realm %]), the third one is your username, and the fourth is the password.
#!/usr/bin/perl -w
use strict;
use LWP::UserAgent;
my $ua = LWP::UserAgent->new();
# set to 0 if using a self-signed certificate
$ua->ssl_opts(verify_hostname => 1);
$ua->credentials('example.org:1443', '[% current_http_realm %]', 'myuser', 'mypassword');
my $res = $ua->get('https://example.org:1443/api/');
if($res->is_success) {
print $res->as_string;
} else {
print STDERR $res->status_line, "\n";
}
Same as with Perl's LWP::UserAgent described above, you have to set the credentials using curl_setopt_array() with the parameter CURLOPT_USERPWD specifying your username and password.
$ua = curl_init();
$options = array(
CURLOPT_USERPWD => "myuser:mypassword",
CURLOPT_RETURNTRANSFER => true,
// set to false if using a self-signed certificate
CURLOPT_SSL_VERIFYHOST => false,
CURLOPT_SSL_VERIFYPEER => false,
);
curl_setopt_array($ua , $options);
curl_setopt($ua, CURLOPT_URL, 'https://example.org:1443/api/');
$res = curl_exec($ua);
if(!$res) {
echo "Curl Error : " . curl_error($ua);
}
else {
echo $res;
}
openssl x509 -purpose -noout -in /path/to/ca-cert.pem
For the actual client authentication, you will need two files which you can download from the panel after creating the client certificates:
With cURL, use --cert /path/to/NGCP-API-client-certificate-xxxxx.pem to specify the client certificate, and --cacert /path/to/ca-cert.pem to specify the CA certificate in case of a self-signed server certificate.
curl -i -X GET --cert /path/to/NGCP-API-client-certificate-xxxxx.pem --cacert /path/to/ca-cert.pem https://example.org:1443/api/
Additionally use the --insecure option if you are testing against a self-signed server certificate.
With LWP::UserAgent, set up the SSL client certificates using the ssl_opts() function. Since the key file downloaded from the NGCP Panel combines both the client key and the certificate into one single file, use the same filename for the SSL_cert_file and SSL_key_file option.
#!/usr/bin/perl -w
use strict;
use LWP::UserAgent;
my $ua = LWP::UserAgent->new();
$ua->ssl_opts(
SSL_cert_file => '/path/to/NGCP-API-client-certificate-xxxxx.pem',
SSL_key_file => '/path/to/NGCP-API-client-certificate-xxxxx.pem',
SSL_ca_file => '/path/to/ca-cert.pem',
# set to 0 if using a self-signed certificate
verify_hostname => 1,
);
my $res = $ua->get('https://example.org:1443/api/');
if($res->is_success) {
print $res->as_string;
} else {
print STDERR $res->status_line, "\n";
}
Same as with Perl's LWP::UserAgent described above, you have to set the key and certificate paths using curl_setopt_array(), with the parameters CURLOPT_SSLCERT and CURLOPT_SSLKEY pointing to your client certificate.
$ua = curl_init();
$options = array(
CURLOPT_SSLCERT => '/path/to/NGCP-API-client-certificate-xxxxx.pem',
CURLOPT_SSLKEY => '/path/to/NGCP-API-client-certificate-xxxxx.pem',
CURLOPT_CAINFO => '/path/to/ca-cert.pem',
CURLOPT_RETURNTRANSFER => true,
// set to false if using a self-signed certificate
CURLOPT_SSL_VERIFYPEER => true,
CURLOPT_SSL_VERIFYHOST => true,
);
curl_setopt_array($ua , $options);
curl_setopt($ua, CURLOPT_URL, 'https://example.org:1443/api/');
$res = curl_exec($ua);
if(!$res) {
echo "Curl Error : " . curl_error($ua);
}
else {
echo $res;
}
Send a POST request with a JSON body, containing your valid credentials.
curl -i -X POST -H 'Content-Type: application/json' 'https://example.org/login_jwt/' --data-binary '{"username":"myuser","password":mypassword}'
Response (Example):
{"subscriber_id":1,"jwt":"eyJhbGciOiJIUzI1NiJ9.eyJzdWJzY3JpYmVyX3V1aWQiOiIyZDU3YjYwNC0zZjViLTQ2N2UtYjRjMC1lNjhlOWI0N2JhZTAiLCJ1c2VybmFtZSI6IjQzOTkxMDAyIn0.boNrKnCjbh4MyxpcDi8dmnFzWwFh4xm8-aWuKv08SKM"}
As you can see, the subscriber_id of the logged in user is sent along. This can be used by the API consumer to fetch further details about the subscriber from the appropriate collection.
Then authenticate to any API requests using the Authorization Header with the Bearer scheme.
curl -i -H 'Authorization: Bearer <json_web_token>' -X GET --header 'Accept: application/hal+json' 'https://10.15.17.196/api/collection/
Additionally use the --insecure option if you are testing against a self-signed server certificate.