From: Arran Cudbard-Bell Date: Wed, 23 Oct 2019 10:36:55 +0000 (-0400) Subject: Add some basic resources for the REST module X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=be1cdd5c330a21279110e5ffae3cf22e5f3e373f;p=thirdparty%2Ffreeradius-server.git Add some basic resources for the REST module --- diff --git a/doc/antora/modules/howto/nav.adoc b/doc/antora/modules/howto/nav.adoc index 653731acdb3..c5e6ebaff79 100644 --- a/doc/antora/modules/howto/nav.adoc +++ b/doc/antora/modules/howto/nav.adoc @@ -18,7 +18,7 @@ ***** xref:modules/ldap/ldapsearch/locating_objects.adoc[Locating objects] ***** xref:modules/ldap/ldapsearch/translating_to_the_ldap_module.adoc[Translating ldapsearch arguments to LDAP configuration items] -**** xref:modules/ldap/configuration.adoc[Enabling the LDAP module] +**** xref:modules/ldap/base_configuration/index.adoc[Base configuration] **** xref:modules/ldap/authorization/index.adoc[Configuring authorization] ***** xref:modules/ldap/authorization/locating_the_user.adoc[Locating the user] @@ -33,6 +33,11 @@ *** xref:modules/pam/index.adoc[PAM] *** xref:modules/passwd/index.adoc[Passwd] *** xref:modules/python/index.adoc[Python] + +*** xref:modules/rest/index.adoc[REST] +**** xref:modules/rest/bootstrap_nginx.adoc[Installing and Configuring NGINX] +**** xref:modules/rest/configuration.adoc[Base configuration] + *** xref:modules/soh/index.adoc[SoH] *** xref:modules/sql/index.adoc[SQL] *** xref:modules/sqlcounter/index.adoc[SQL-Counter] diff --git a/doc/antora/modules/howto/pages/modules/rest/bootstrap_nginx.adoc b/doc/antora/modules/howto/pages/modules/rest/bootstrap_nginx.adoc new file mode 100644 index 00000000000..51104ab62d6 --- /dev/null +++ b/doc/antora/modules/howto/pages/modules/rest/bootstrap_nginx.adoc @@ -0,0 +1,71 @@ += Bootstrap NGINX + +NGINX itself should be installed from packages provided with your OS. + +After installing NGINX you should locate its configuration and virtual server directories. + +On RHEL and Centos, the main configuration directory is located at `/etc/nginx`, with the +default virtual server loading endpoint definitions from `/etc/nginx/conf.d`. + +We will be making no changes to the main NGINX configuration, and will instead be placing +stub endpoints in `/etc/nginx/conf.d`. + +== Static endpoint + +No special logic or server side processing needs to be implemented for simple APIs. + +Serving files with static JSON data is often sufficient for testing purposes. + +[source,shell] +---- +cat < /usr/share/nginx/html/reply_message.json +{ +"reply:Reply-Message": "Hello from NGINX!" +} +EOF +---- + +== Basic authentication endpoint (`default.d/authenticate.conf`) + +=== Create a htpasswd file + +In order to enabled HTTP Basic Authentication, we first need to create a file containing user +credentials. + +Ensure that the `apache2-utils` (Debian, Ubuntu) or `httpd-tools` (RHEL/CentOS) +package is installed. This will provide the `htpasswd` utility. + +[source,shell] +---- +sudo htpasswd -cb /etc/nginx/.htpasswd john password +---- + +If you `cat /etc/nginx/.htpasswd` you should see that an entry has been created for john. + +[source,shell] +---- +sudo cat /etc/nginx/.htpasswd +john:$apr1$Mvht.qj2$/o8yV5T9RnAYEnqNtXBfM0 +---- + +=== Define an endpoint for HTTP auth + +[source,shell] +---- +sudo -s + +cat < /etc/nginx/default.d/authenticate.conf +location /authenticate { + auth_basic "FreeRADIUS user authentication"; + auth_basic_user_file /etc/nginx/.htpasswd; + add_header Content-Type text/plain; +} +EOF + +# create an empty file to serve +touch /usr/share/nginx/html/authenticate + +systemctl reload nginx + +exit +---- diff --git a/doc/antora/modules/howto/pages/modules/rest/configuration.adoc b/doc/antora/modules/howto/pages/modules/rest/configuration.adoc new file mode 100644 index 00000000000..76e7f9b4740 --- /dev/null +++ b/doc/antora/modules/howto/pages/modules/rest/configuration.adoc @@ -0,0 +1,145 @@ += Base configuration + +include::howto:partial$pre_test.adoc[] + +== Editing mods-available/rest + +[source,config] +---- +rest { + # example - "http://localhost" + connect_uri = 'http://' <1> +} +---- + +<1> A common URL prefix for all REST API endpoints called by this module instance. + Connect URI is used to reduce repetition in the config, and as a URI to check + connectivity to the REST API on startup, and to warm the connection pool before + processing requests. + +== Enabling mods-available/rest + +The `ldap` module is enabled by creating a soft link from the +`mods-enabled/` directory to the `mods-available/` directory. + +[source,shell] +---- +cd raddb/mods-enabled && ln -s ../mods-available/rest +---- + +== Calling the rest module + +=== Calling a generic API endpoint + +The REST module allows a different REST API endpoint to be configured for each +type of section it can be called in. + +If called in `recv Access-Request` (≥ v4.0.x) or `authorize { ... }` (≤ v3.0.x) +the `rest.authorize` module section will be evaluated. + +[source,config] +---- +server default { + ... + recv Access-Request { + rest + ... + } + ... +} +---- + +[source,config] +---- +rest { + ... + authorize { + uri = "${..connect_uri}/user/%{User-Name}?action=authorize" <1> + method = 'get' <2> + } + ... +} +---- +<1> The URL to authenticate against. Will be expanded (if required). +<2> The HTTP 'verb' to use. + +If called in `recv Accounting-Request` (≥ v4.0.x) or `accounting { ... }` (≤ v3.0.x) +the `rest.authorize` mould section will be evaluated. + +[source,config] +---- +server default { + ... + recv Accounting-Request { + rest + ... + } + ... +} +---- + +[source,config] +---- +rest { + ... + accounting { + uri = "${..connect_uri}/user/%{User-Name}/sessions/%{Acct-Unique-Session-ID}?action=accounting" <1> + method = 'post' <2> + } + ... +} +---- +<1> The URL to authenticate against. Will be expanded (if required). +<2> The HTTP 'verb' to use. + +=== Authenticating a user with HTTP basic auth + +The REST module can also authenticate users by performing HTTP basic access +authentication against a REST API endpoint. + +With HTTP Basic Auth, the user's credentials will be base64 encoded and +submitted in the clear. + +It is strongly recommended to use `https://` with HTTP basic auth, to prevent +snooping. + +[source,unlang] +---- +server default { + ... + recv Access-Request { + if (&User-Password) { + update control { + &Auth-Type := rest + } + } + } + + authenticate rest { + rest + } + ... +} +---- + +[source,config] +---- +rest { + ... + authenticate { + uri = "${..connect_uri}/authenticate" <1> + username = "%{User-Name}" <2> + password = "%{User-Password}" <3> + method = 'get' <4> + tls = ${..tls} <5> + } + ... +} +---- +<1> The URL to authenticate against. Will be expanded (if required). +<2> Username to submit for HTTP Basic Auth. Will be expanded. +<3> Password to submit for HTTP Basic Auth. Will be expanded. +<4> The HTTP 'verb' to use. +<5> HTTP(s) settings for the module instance. + +include::howto:partial$post_test.adoc[] diff --git a/doc/antora/modules/howto/pages/modules/rest/index.adoc b/doc/antora/modules/howto/pages/modules/rest/index.adoc new file mode 100644 index 00000000000..87db280ca77 --- /dev/null +++ b/doc/antora/modules/howto/pages/modules/rest/index.adoc @@ -0,0 +1,30 @@ += REST +== Introduction + +FreeRADIUS can be used to communicate with REST APIs. + +== REST base configuration + +This section describes the basic configuration needed to configure the REST +module to communicate with a REST service. + +== xref:modules/rest/fixed_data.adoc[Calling REST endpoints with fixed data formats] + +The REST module was developed to allow business logic to be separated out into a +separate discreet service. This reduces the role of FreeRADIUS to a translation +daemon, receiving packets from the network and presenting them in JSON or POST +format for consumption by the API, then parsing a JSON or POST response, and +translating that back into a network packet. + +If you will be developing a new REST API to implement business logic for a AAA +service, you should follow the guide in this section, and accept and return +data in that format the REST module expected. + +== xref:modules/rest/custom_data.adoc[Calling REST endpoints with a custom data format] + +The REST module can also communicate with arbitrary REST endpoints, +and versions ≥ v4.0.x include a JSON module xref:raddb/mods-available/json[JSON] +which allows mapping elements of a JSON response to FreeRADIUS. + +If you're attempting to integrate an existing REST API, this section will provide +hints on how to accomplish this.