<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 &lt;json_web_token&gt;' -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: -%]
