You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
228 lines
8.5 KiB
228 lines
8.5 KiB
<h[% level %] id="[% id %]">
|
|
[% IF uri -%]
|
|
<a href="[% uri %]" rel="collection">
|
|
[% END -%]
|
|
[% title %]
|
|
[% IF uri -%]
|
|
</a>
|
|
[% END -%]
|
|
</h[% level %]>
|
|
|
|
[%- current_http_realm = IF is_admin_api ; 'api_admin_http' ; ELSE ; 'api_subscriber_http' ; END -%]
|
|
|
|
<p>
|
|
The access level of this API user is
|
|
<b>[% SWITCH c.user.roles %]
|
|
[%- CASE 'admin' %] admin
|
|
[%- CASE 'reseller' %] reseller
|
|
[%- CASE 'subscriberadmin' %] subscriberadmin
|
|
[%- CASE 'subscriber' %] subscriber
|
|
[%- CASE %] (unknown)
|
|
[%- END %]</b>.
|
|
</p>
|
|
<p>
|
|
Authentication and authorization on the Sipwise NGCP HTTP API is performed via
|
|
<b>HTTP Basic Auth</b>
|
|
[% IF is_admin_api %] or <b>SSL Client Certificates</b>[% END -%]
|
|
[% IF is_subscriber_api %] or <b>JSON Web Token (JWT)</b>[% END -%]
|
|
.
|
|
</p>
|
|
|
|
<h[% level + 1 %]>HTTP Basic Auth</h[% level + 1 %]>
|
|
You can authenticate against the API using your normal <b>NGCP Panel</b> [% IF is_admin_api %]administrator or reseller[% ELSE %]subscriber[% END %] login credentials with the realm <span>[% current_http_realm %]</span>.
|
|
|
|
<h[% level + 2 %]>Examples</h[% level + 2 %]>
|
|
<div class="examples">
|
|
|
|
<h5>Using cURL on the Shell</h5>
|
|
<p>
|
|
With cURL, use <span>--user 'username:password'</span> option to specify your access credentials. Specifying the realm is not needed here.
|
|
|
|
<code>
|
|
curl -i -X GET --user 'myuser:mypassword' https://example.org:1443/api/
|
|
</code>
|
|
|
|
Additionally use the <span>--insecure</span> option if you are testing against a self-signed server certificate.<br/>
|
|
Read the Part <em>SSL Certificates</em> under the Chapter <em>Security and Maintenance</em> in the SPCE documentation
|
|
for more information about SSL Certificates.
|
|
</p>
|
|
|
|
<h5>Using Perl LWP::UserAgent</h5>
|
|
<p>
|
|
With LWP::UserAgent, set the credentials using the <span>credentials()</span> 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 <span>[% current_http_realm %]</span>), the third one is your username, and the fourth is the password.
|
|
|
|
<code>
|
|
#!/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";
|
|
}
|
|
</code>
|
|
</p>
|
|
|
|
<h5>Using PHP cURL</h5>
|
|
<p>
|
|
|
|
Same as with Perl's LWP::UserAgent described above, you have to set the credentials using <span>curl_setopt_array()</span> with the parameter <span>CURLOPT_USERPWD</span> specifying your username and password.
|
|
|
|
<code>
|
|
$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;
|
|
}
|
|
</code>
|
|
</p>
|
|
|
|
</div>
|
|
|
|
[% IF is_admin_api %]
|
|
<h[% level + 1 %]>SSL Client Certificates</h[% level + 1 %]>
|
|
You can generate and download client certificates for administrators and resellers via the <b>NGCP Panel</b> in the <b>Administrators</b> view. In order to do so, your server certificate MUST support <span>SSL client CA</span> and <span>SSL client CA</span>. You can verify it with the following command:
|
|
|
|
<code>
|
|
openssl x509 -purpose -noout -in /path/to/ca-cert.pem
|
|
</code>
|
|
|
|
For the actual client authentication, you will need two files which you can download from the panel after creating the client certificates:
|
|
|
|
<ol>
|
|
<li>The client certificate generated via the NGCP Panel. This is usually labelled <span>NGCP-API-client-certificate-xxxxx.pem</span>.</li>
|
|
<li>The CA certificate used to sign the server certificate, in case it as been self-signed or the CA is not recognized by the client host environment.</li>
|
|
</ol>
|
|
|
|
<h[% level + 2 %]>Examples</h[% level + 2 %]>
|
|
<div class="examples">
|
|
|
|
<h5>Using cURL on the Shell</h5>
|
|
<p>
|
|
With cURL, use <span>--cert /path/to/NGCP-API-client-certificate-xxxxx.pem</span> to specify the client certificate, and <span>--cacert /path/to/ca-cert.pem</span> to specify the CA certificate in case of a self-signed server certificate.
|
|
|
|
<code>
|
|
curl -i -X GET --cert /path/to/NGCP-API-client-certificate-xxxxx.pem --cacert /path/to/ca-cert.pem https://example.org:1443/api/
|
|
</code>
|
|
|
|
Additionally use the <span>--insecure</span> option if you are testing against a self-signed server certificate.
|
|
</p>
|
|
|
|
<h5>Using Perl LWP::UserAgent</h5>
|
|
<p>
|
|
With LWP::UserAgent, set up the SSL client certificates using the <span>ssl_opts()</span> 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 <span>SSL_cert_file</span> and <span>SSL_key_file</span> option.
|
|
|
|
<code>
|
|
#!/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";
|
|
}
|
|
</code>
|
|
</p>
|
|
|
|
<h5>Using PHP cURL</h5>
|
|
<p>
|
|
|
|
Same as with Perl's LWP::UserAgent described above, you have to set the key and certificate paths using <span>curl_setopt_array()</span>, with the parameters <span>CURLOPT_SSLCERT</span> and <span>CURLOPT_SSLKEY</span> pointing to your client certificate.
|
|
|
|
<code>
|
|
$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;
|
|
}
|
|
</code>
|
|
</p>
|
|
|
|
</div>
|
|
[% END %]
|
|
|
|
[% IF is_subscriber_api %]
|
|
<h[% level + 1 %]>JSON Web Token (JWT)</h[% level + 1 %]>
|
|
Using a dedicated URL, you can request a JSON Web token, which can subsequently be used to authenticate/authorize further API requests. The body of the token contains the following data:
|
|
<ul>
|
|
<li><b>subscriber_uuid</b>: a unique identifier of the logged in entity</li>
|
|
<li><b>username</b>: The web username of the logged in user (without domain)</li>
|
|
</ul>
|
|
|
|
For a detailed introduction and more information see the <a href="https://jwt.io/">JWT Website</a>.
|
|
|
|
<h[% level + 2 %]>Examples</h[% level + 2 %]>
|
|
<div class="examples">
|
|
|
|
<h5>Using cURL on the Shell</h5>
|
|
<p>
|
|
Send a POST request with a JSON body, containing your valid credentials.
|
|
|
|
<code>
|
|
curl -i -X POST -H 'Content-Type: application/json' 'https://example.org/login_jwt/' --data-binary '{"username":"myuser","password":mypassword}'
|
|
</code>
|
|
Response (Example):
|
|
<code>
|
|
{"subscriber_id":1,"jwt":"eyJhbGciOiJIUzI1NiJ9.eyJzdWJzY3JpYmVyX3V1aWQiOiIyZDU3YjYwNC0zZjViLTQ2N2UtYjRjMC1lNjhlOWI0N2JhZTAiLCJ1c2VybmFtZSI6IjQzOTkxMDAyIn0.boNrKnCjbh4MyxpcDi8dmnFzWwFh4xm8-aWuKv08SKM"}
|
|
</code>
|
|
|
|
As you can see, the <i>subscriber_id</i> 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.
|
|
|
|
<code>
|
|
curl -i -H 'Authorization: Bearer <json_web_token>' -X GET --header 'Accept: application/hal+json' 'https://10.15.17.196/api/collection/
|
|
</code>
|
|
|
|
Additionally use the <span>--insecure</span> option if you are testing against a self-signed server certificate.
|
|
</p>
|
|
|
|
</div>
|
|
[% END %]
|
|
|
|
[% # vim: set tabstop=4 syntax=html expandtab: -%]
|