From 629f215dae2622e246a671f6660e76c2d36628ed Mon Sep 17 00:00:00 2001 From: Andreas Granig Date: Wed, 30 Apr 2014 12:26:53 +0200 Subject: [PATCH] MT#6695 Specify ssl config dir and document auth Allow to specify path to dir containing opensslcnf.cnf Document usage of basic auth for API --- share/templates/api/root/auth.tt | 90 ++++++++++++++++++++++++++++++-- tools/generate_ssl_keys.sh | 2 +- 2 files changed, 87 insertions(+), 5 deletions(-) diff --git a/share/templates/api/root/auth.tt b/share/templates/api/root/auth.tt index 9beaa4fe33..56d756dc05 100644 --- a/share/templates/api/root/auth.tt +++ b/share/templates/api/root/auth.tt @@ -8,16 +8,91 @@ [% END -%] -Authentication and authorization on the Sipwise NGCP HTTP API is performed via SSL Client Certificates. You can generate and download certificates for administrators and resellers via the NGCP Panel in the Administrators view. +Authentication and authorization on the Sipwise NGCP HTTP API is performed via HTTP Basic Auth or SSL Client Certificates. -You will need two files: +HTTP Basic Auth +You can authenticate against the API using your normal NGCP Panel administrator or reseller login credentials with the realm api_admin_http. + +Examples +
+ +
Using cURL on the Shell
+

+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. +

+ +
Using Perl LWP::UserAgent
+

+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 api_admin_http), 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', 'api_admin_http', '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"; +} + +

+ +
Using PHP cURL
+

+ +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; +} + +

+ +
+ +SSL Client Certificates +You can generate and download client certificates for administrators and resellers via the NGCP Panel in the Administrators view. In order to do so, your server certificate MUST support SSL client CA and SSL client CA. You can verify it with the following command: + + +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:
  1. The client certificate generated via the NGCP Panel. This is usually labelled NGCP-API-client-certificate-xxxxx.pem.
  2. 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.
-Examples +Examples
Using cURL on the Shell
@@ -27,6 +102,8 @@ With cURL, use --cert /path/to/NGCP-API-client-certificate-xxxxx.pem 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.

Using Perl LWP::UserAgent
@@ -43,7 +120,10 @@ $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; @@ -64,8 +144,10 @@ $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_SSL_VERIFYPEER => true, 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/'); diff --git a/tools/generate_ssl_keys.sh b/tools/generate_ssl_keys.sh index 9e9998e2c9..2968199965 100755 --- a/tools/generate_ssl_keys.sh +++ b/tools/generate_ssl_keys.sh @@ -1,6 +1,6 @@ #!/bin/sh -BASE="/usr/share/ngcp-panel-tools" DEST=${1:-/etc/ngcp-panel/api_ssl} +BASE=${2:-/usr/share/ngcp-panel-tools} mkdir -p ${DEST}