sipwise
/
ngcp-panel
mirror of https://github.com/sipwise/ngcp-panel.git
1
0
Fork 0
Code Issues Releases Wiki Activity

TT#4334 adapt api documentation for subadmin

Browse Source 
Change-Id: I447c62903578a53c700b199f4e6ccbc7ea0585b9
changes/76/10676/3
Gerhard Jungwirth 9 years ago
parent 5ca51f930a
commit 893943d2fc
3 changed files with 121 additions and 94 deletions
Show Stats Download Patch File Download Diff File

12
lib/NGCP/Panel/Controller/API/Root.pm
Unescape View File

@ -31,7 +31,7 @@ __PACKAGE__->config(
action => {
map { $_ => {
ACLDetachTo => 'invalid_user',
AllowedRole => [qw/admin reseller/],
AllowedRole => [qw/admin reseller subscriberadmin subscriber/],
Args => 0,
Does => [qw(ACL CheckTrailingSlash RequireSSL)],
Method => $_,
@ -64,6 +64,7 @@ sub GET : Allow {
};
my $colls = NGCP::Panel::Utils::API::get_collections_files;
my %user_roles = map {$_ => 1} $c->user->roles;
foreach my $coll(@$colls) {
my $mod = $coll;
$mod =~ s/^.+\/([a-zA-Z0-9_]+)\.pm$/$1/;
@ -74,9 +75,9 @@ sub GET : Allow {
my $role = $full_mod->config->{action}->{OPTIONS}->{AllowedRole};
if(ref $role eq "ARRAY") {
next unless grep @{ $role }, $c->user->roles;
next unless grep { $user_roles{$_}; } @{ $role };
} else {
next unless $role && $role eq $c->user->roles;
next unless $user_roles{$role};
}
my $query_params = [];
@ -197,6 +198,11 @@ sub GET : Allow {
}
if ($user_roles{subscriber} || $user_roles{subscriberadmin}) {
$c->stash(is_subscriber_api => 1);
} else {
$c->stash(is_admin_api => 1);
}
$c->stash(template => 'api/root.tt');
$c->forward($c->view);
$c->response->headers(HTTP::Headers->new(

186
share/templates/api/root/auth.tt
Unescape View File

@ -8,7 +8,21 @@
[% END -%]
</h[% level %]>
Authentication and authorization on the Sipwise NGCP HTTP API is performed via <b>HTTP Basic Auth</b> or <b>SSL Client Certificates</b>.
<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 %].
</p>
<h[% level + 1 %]>HTTP Basic Auth</h[% level + 1 %]>
You can authenticate against the API using your normal <b>NGCP Panel</b> administrator or reseller login credentials with the realm <span>api_admin_http</span>.
@ -80,88 +94,90 @@ else {
</div>
<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>
[% 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 %]
[% # vim: set tabstop=4 syntax=html expandtab: -%]

17
share/templates/api/root/collection.tt
Unescape View File

@ -8,6 +8,11 @@
[% END -%]
</h[% level %]>
[%- curl_auth_string = '';
IF is_admin_api;
curl_auth_string = '--cert NGCP-API-client-certificate.pem --cacert ca-cert.pem ';
END; -%]
<h[% level + 1 %]>Description</h[% level + 1%]>
[% col.description %]
@ -109,7 +114,7 @@ See description how to obtain properties, if any.
<h[% level + 2 %]>Request available HTTP methods on the URI</h[% level + 2 %]>
<p>
[%
cmd = 'curl -i -X OPTIONS -H \'Connection: close\' --cert NGCP-API-client-certificate.pem --cacert ca-cert.pem https://example.org:1443' _ uri;
cmd = 'curl -i -X OPTIONS -H \'Connection: close\' '_ curl_auth_string _'https://example.org:1443' _ uri;
INCLUDE helpers/api_command.tt cmd=cmd level=level+3;
request =
@ -133,7 +138,7 @@ Accept-Post: application/hal+json; profile="http://purl.org/sipwise/ngcp-api/#re
To define the page number and the rows per page to return, you can pass the parameters <i>page</i> and <i>rows</i>. Default values are <i>page=1</i> and <i>rows=10</i>, if you do not provide them.
</p>
[%
cmd = 'curl -i -X GET -H \'Connection: close\' --cert NGCP-API-client-certificate.pem --cacert ca-cert.pem \'https://example.org:1443/api/' _ id _ '/?page=1&rows=1\'';
cmd = 'curl -i -X GET -H \'Connection: close\' '_ curl_auth_string _'\'https://example.org:1443/api/' _ id _ '/?page=1&rows=1\'';
INCLUDE helpers/api_command.tt cmd=cmd level=level+3;
props = get_props_plain() | indent(12);
@ -201,7 +206,7 @@ Content-Type: application/hal+json; profile="http://purl.org/sipwise/ngcp-api/"
<p>
[%
cmd = 'curl -i -X GET -H \'Connection: close\' --cert NGCP-API-client-certificate.pem --cacert ca-cert.pem \'https://example.org:1443/api/' _ id _ '/1\'';
cmd = 'curl -i -X GET -H \'Connection: close\' '_ curl_auth_string _'\'https://example.org:1443/api/' _ id _ '/1\'';
INCLUDE helpers/api_command.tt cmd=cmd level=level+3;
props = get_props_plain() | indent(3);
@ -277,7 +282,7 @@ Preference-Applied: return=minimal';
cmd = 'curl -i -X ' _ http_request _ ' -H \'Connection: close\' -H \'Content-Type: ' _ content_type _ '\'' _ request_headers_form _ ' --cert NGCP-API-client-certificate.pem --cacert ca-cert.pem \'https://example.org:1443/api/' _ id _ '/' _ item_id _ '\' ' _ request_form ;
cmd = 'curl -i -X ' _ http_request _ ' -H \'Connection: close\' -H \'Content-Type: ' _ content_type _ '\'' _ request_headers_form _ ' '_ curl_auth_string _'\'https://example.org:1443/api/' _ id _ '/' _ item_id _ '\' ' _ request_form ;
request =
http_request _ ' /api/' _ id _ '/' _ item_id _ ' HTTP/1.1
@ -348,7 +353,7 @@ END%]
END;
props = props.substr(0, props.length - 2);
cmd = 'curl -i -X PATCH -H \'Connection: close\' -H \'Content-Type: application/json-patch+json\' -H \'Prefer: return=minimal\' --cert NGCP-API-client-certificate.pem --cacert ca-cert.pem \'https://example.org:1443/api/' _ id _ '/2\' --data-binary \'[ ' _ props _ ' ]\'';
cmd = 'curl -i -X PATCH -H \'Connection: close\' -H \'Content-Type: application/json-patch+json\' -H \'Prefer: return=minimal\' '_ curl_auth_string _'\'https://example.org:1443/api/' _ id _ '/2\' --data-binary \'[ ' _ props _ ' ]\'';
INCLUDE helpers/api_command.tt cmd=cmd extended=1 level=level+3;
%]
@ -437,7 +442,7 @@ Preference-Applied: return=minimal';
<p>
[%
cmd = 'curl -i -X DELETE -H \'Connection: close\' --cert NGCP-API-client-certificate.pem --cacert ca-cert.pem \'https://example.org:1443/api/' _ id _ '/1\'';
cmd = 'curl -i -X DELETE -H \'Connection: close\' '_ curl_auth_string _'\'https://example.org:1443/api/' _ id _ '/1\'';
INCLUDE helpers/api_command.tt cmd=cmd level=level+3;
request =

Write Preview
Loading…
Cancel
Save