***** 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]
*** 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]
--- /dev/null
+= 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 <<EOF > /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 <<EOF > /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
+----
--- /dev/null
+= Base configuration
+
+include::howto:partial$pre_test.adoc[]
+
+== Editing mods-available/rest
+
+[source,config]
+----
+rest {
+ # example - "http://localhost"
+ connect_uri = 'http://<http_server_fqdn>' <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[]
--- /dev/null
+= 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.
projects / thirdparty / freeradius-server.git / commitdiff
