h2. radsecproxy
h3. Goals and Prerequisites\\
This section describes how to set up radsecproxy to act as a federation-level RADIUS+RadSec server. It can then completely replace other RADIUS server products on the federation level.
More precisely, it will enable a server to:
* Accept requests from connected service providers via RADIUS and RadSec.
* Forward requests to connected identity providers via RADIUS and RadSec.
* Forward requests from international visitors to the European eduroam confederation root servers via RadSec.
* Accept requests from the root servers via RadSec for the own federation's users when they are roaming in another federation.
The prerequisites for this deployment are:
* radsecproxy version 1.2 or higher
* A server certificate and * [Base configuration / logging / F-Ticks|display/H2eduroam/How+to+deploy+eduroam+at+national+level#Howtodeployeduroamatnationallevel-Baseconfiguration%2Flogging%2FFTicks]
* [Client definition|display/H2eduroam/How+to+deploy+eduroam+at+national+level#Howtodeployeduroamatnationallevel-Clientdefinition]
* [Request forwarding|display/H2eduroam/How+to+deploy+eduroam+at+national+level#Howtodeployeduroamatnationallevel-Requestforwarding]
* [Caveats|display/H2eduroam/How+to+deploy+eduroam+at+national+level#Howtodeployeduroamatnationallevel-Caveats]
h3. Version information
The prerequisites for this deployment are:
* radsecproxy version 1.4.2 or higher
* A server certificate and a private key for that certificate to establish the RadSec connection which
designates the server as a federation proxy:
urn:geant:eduroam:component:proxy:Europe:<FedName>:<id>an IdP+SP.
h3. Sample configurationInstallation
Most ofOn UNIX-like systems, the radsecproxyinstallation configuration file is static. Therefore, a template configuration file is provided at very simple:
# Download the code from [http://wwwsoftware.eduroamuninett.orgno/downloads/docs/eduroam-cookbook-scripts.zip]. A detailed explanation of this configuration file follows. However, the comments included in the file should make its action almost self\- explanatory. This means you can start and experiment with it right after installation.
h3. Installation
On UNIX-like systems, the installation is very simple:
# Download the code from [http://software.uninett.no/radsecproxy/].
# Unpack the code.
# Navigate into the unpacked directory (the base directory) and type:
_make_radsecproxy/].
# Unpack the code.
# Navigate into the unpacked directory (the base directory) and type:
_make_
The code is ISO C and should compile cleanly. It usually does not require a ./configure.
4. After compiling, the executable
{code}
radsecproxy
{code}
is in the base directory. Either run this executable here or copy it to a convenient location (e.g. /usr/local/bin) and run it there. Execution does not require root rights.
The code is ISO C and should compile cleanly. It usually does not require a ./configure.
5. Copy the template configuration file below into
{code}
/etc/radsecproxy.conf
{code}
46. AfterCreate compiling,the the executable:radsecproxy is in the base directory.
directory _/etc/radsecproxy.d/certs/ca/_. The template configuration file requires this directory to contain the accredited CA root certificates and the corresponding Certificate Revocation Lists (CRLs) in their OpenSSL hash form. See the section xyz for information about the CA download.
Either7. runFill thisthe executablelines heremarked or copy it to a convenient location (e.g. /usr/local/bin) and run it therewith __STUFF__ with the required information as explained below.
Execution does not require root rights. It expects its configuration file to be in:
_/etc/radsecproxy.conf_
5. Create the directory _/etc/radsecproxy.d/certs/ca/_. The 8. Start radsecproxy and enjoy (for first-time use, starting it with the \--f option is recommended, it will start radsecproxy in the foreground and show some verbose startup messages).\\
h3.
h3. Sample config file
Most of the radsecproxy configuration file is static. Therefore, a template configuration file requiresis this directory
to contain the accredited CA root certificates and the corresponding Certificate Revocation Lists (CAs)
in their OpenSSL hash form.
6. Currently, two CAs are accredited for eduroam. These two certificates and their CRLs need to be copied
into this directory. For your convenience, we have prepared a script at
[http://www.eduroam.org/downloads/docs/eduroam-cookbook-scripts.zip], which you can execute in the
directory. It will download and hash the appropriate files. In this case you can skip steps 7 and 8.
7. If you want to download the files manually, download them from these URLs:
* [http://sca.edugain.org/cacert/eduGAINCA.pem]
* [http://sca.edugain.org/cacert/eduGAINSCA.pem]
* [http://pki.edugain.org/edugainca/crl/cacrl.pem]
* [https://sca.edugain.org/crl/cacrl.pem]
8. After downloading, execute the following command in the /etc/radsecproxy.d/certs/ca/ directory:
\_c_rehash\_ .
(including the dot) to generate OpenSSL hashes of the downloaded files.
9. Make sure that the CRL files are regularly re-downloaded. This can for example be done by executing the
download script regularly with cron. CRLs have a limited validity time themselves -- not regularly refreshing
the CRLs will eventually cause certificate validation to fail\!
10. Copy the template configuration file into /etc/radsecproxy.conf.
11. Fill the lines marked with __STUFF_\_.
12. Start radsecproxy and enjoy (for first-time use, starting it with the \--f option is recommended, it will start
radsecproxy in the foreground and show some verbose startup messages).
h3. Detailed explanation of configuration
This walk-through goes through the template radsecproxy.conf line by line and explains the meaning of each
stanza.
_ListenUDP \*:1812{_}{_}ListenTCP \*:2083_
radsecproxy will receive requests from all connected Service Providers via both RADIUS and RadSec. Therefore it has to listen on the appropriate ports on its network interfaces (the * meaning: all interfaces). If you want radsecproxy to listen only on specific interfaces, enter the interface names here. Beware: in this case you may also have to set the more exotic options SourceUDP and/or SourceTCP (see the man page of radsecproxy for details).
_LogLevel 3_
\_LogDestination [file:///var/log/radsecproxy.log\_|file:///var/log/radsecproxy.log_]
A logging level of 3 is the default and recommended log level. Radsecproxy will then log successful and failed authentications on one line each. The log destination is a typical POSIX-compliant log location.
_LoopPrevention On_
This enables a semi-automatic prevention of routing loops for RADIUS connections. If you connect a client {...\] and a server {...} and give them the same descriptive name, the proxy will prevent proxying.
_tls default {_
_ CACertificatePath /etc/radsecproxy/certs/ca/_
_ CertificateFile /etc/radsecproxy/certs/_{_}CERT_PEM_\_\_
_ CertificateKeyFile /etc/radsecproxy/certs/_{_}CERT_KEY_\_\_
_ CertificateKeyPassword \__CERT_PASS_\_\_
_CRLCheck On_
_}_provided at [http://www.eduroam.org/downloads/docs/eduroam-cookbook-scripts.zip|http://www.eduroam.org/downloads/docs/eduroam-cookbook-scripts.zip]. A detailed explanation of this configuration file follows. However, the comments included in the file should make its action almost self\- explanatory. This means you can start and experiment with it right after installation.
h3. Base configuration / logging / F-Ticks
This walk-through goes through the template radsecproxy.conf line by line and explains the meaning of each stanza.
{code}
ListenUDP *:1812
ListenTCP *:2083
{code}
radsecproxy will receive requests from all connected Service Providers via both RADIUS and RadSec. Therefore it has to listen on the appropriate ports on its network interfaces (the * meaning: all interfaces). If you want radsecproxy to listen only on specific interfaces, enter the interface names here. Beware: in this case you may also have to set the more exotic options SourceUDP and/or SourceTCP (see the man page of radsecproxy for details).
{code}
LogLevel 3
LogDestination x-syslog:///LOG_LOCAL0
{code}
A logging level of 3 is the default and recommended log level. Radsecproxy will then log successful and failed authentications on one line each. The log destination is the local syslog destination.
{code}
LoopPrevention On
{code}
This enables a semi-automatic prevention of routing loops for RADIUS connections. If you define a client {...\] and a server {...} (see below) and give them the same descriptive name, the proxy will prevent proxying from the client to that same server.
{code}
tls default {
CACertificatePath /etc/radsecproxy/certs/ca/
CertificateFile /etc/radsecproxy/certs/CERT_PEM__
CertificateKeyFile /etc/radsecproxy/certs/CERT_KEY__
CertificateKeyPassword __CERT_PASS__
# CRLCheck On
}
{code}
This section defines which TLS certificates should be used by default. This installation of radsecproxy always uses the same certificates, so this is the only TLS section. CACertificatePath contains the eduroam-accredited CA certificates with filenames in the OpenSSL hash form. The parameters below need to be adapted to point to your server certificate in PEM format, the private key for this certificate and the password for this private key if needed, respectively. If no password is needed for the private key, you can comment this line (precede it with a # sign). The option CRLCheck validates certificates against the Certificate Revocation List (CRL) of the CAs. It requires a valid CRL in place, or else the certificate validation will fail. Therefore, it is important to regularly update the CRLs by re-downloading them as described above.
_rewrite defaultclient {_
_ removeAttribute 64_
_ removeAttribute 65_
_ removeAttribute 81_
_}_
This section deletes attributes from RADIUS requests that convey VLAN assignment information. If VLAN information is sent inadvertently, it can cause a degraded or non-existent service for the end user because he might be put into the wrong VLAN. Connected service providers should filter this attribute on their own. Connected Identity Providers should not send this attribute at all. Checking for the existence of these attributes on the federation server is just an optional additional safety layer. If you do have a roaming use for cross\- institution VLAN assignment, you may want to delete this stanza.
_client 127.0.0.1 {_
_ type udp_
_ secret testing123_
_}_
_client ::1 {_
_ type udp_
_ secret testing123_
_}_
There is no other RADIUS server running on localhost, which makes these client definitions almost superfluous. They may be of some use however to initiate debugging requests and tests from the server itself, so it is considered good practice to list localhost as a client. If your system is not IPv6-enabled, simply delete the stanza about client ::1.
_client \__SP_IP_ADDR__ {\__ type UDP{_}_ secret \__SP_SECRET_\_\__}_
Stanzas like this one are used for each connected service provider that is connected via RADIUS. You need to know the IP address of every SP's RADIUS server and negotiate a shared secret with the SP.
_client incoming {_
_ host *_
_ type TLS_
_ secret mysecret_
_ matchcertificateattribute_
\_SubjectAltName:URI:/\^[https://registry.edugain.org/resolver?urn=urn:geant:eduroam:\_|https://registry.edugain.org/resolver\?urn=urn:geant:eduroam:_]
_component:(sp\|proxy\|confederation-root).*$/_
_}_
All incoming RadSec connections can be handled with this stanza. It does not need to be modified. The eduroam trust model requires that a SP that tries to connect has:
* A X.509 certificate from an eduroam-accredited CA (configured above in block *tls default*).
* A URN proving its eligibility (this is achieved with the matchcertificateattribute option).
The traditional RADIUS *shared secret* has no meaning in RadSec and can be statically set without security implications. In current eduroam deployments, it is set to *mysecret*. This may change in the future.
Please note that the client and server stanza for the Service Activity 5 (SA5) monitoring have the same host address, but different stanza names. This is important: it disables the LoopDetection for this host, and the SA5 monitoring deliberate uses loops to do its tests.
_client SA5-monitoring-incoming {_
_ host 161.53.2.204_
_ type UDP_
_ secret \__MONITORING_SECRET_\_\_
_}_
This is the eduroam Service Activity's monitoring client. Negotiate a shared secret for monitoring with the operators in SA5 and enter it here.
_server \__DESCRIPTIVE_NAME__ {\__ host \__IP_ADDR_\_\__ type UDP{_}_ secret \__SERVER_SECRET_\_\__}_
To deliver requests to your connected IdPs, their servers need to be configured. This stanza is for IdP servers using RADIUS.
_server \__RADSEC_PEER_DNS_NAME__ {\__ type TLS{_}_ secret mysecret{_}_ statusserver on{_}_ matchcertificateattribute_\_SubjectAltName:URI:/\^[https://registry.edugain.org/resolver?urn=urn:geant:eduroam:\_|https://registry.edugain.org/resolver?urn=urn:geant:eduroam:_]_component:(idp\|proxy\|confederation-root):.*$/i{_}_}_
This is the equivalent stanza for IdP servers using RadSec.
_server etlr1.eduroam.org {_
_ type TLS_
_ secret mysecret_
_ statusserver on_
\_ matchcertificateattribute _
\_SubjectAltName:URI:/\^[https://registry.edugain.org/resolver?urn=urn:geant:eduroam:component:confederation-root:Europe:ETLR:.*$/i\_|https://registry.edugain.org/resolver\?urn=urn:geant:eduroam:component:confederation-root:Europe:ETLR:.*$/i_]
_}_
_server etlr2.eduroam.org {_
_ type TLS_
_ secret mysecret _
_ statusserver on_
\_ matchcertificateattribute _
\_SubjectAltName:URI:/\^[https://registry.edugain.org/resolver?urn=urn:geant:eduroam:component:confederation-root:Europe:ETLR:.*$/i\_|https://registry.edugain.org/resolver\?urn=urn:geant:eduroam:component:confederation-root:Europe:ETLR:.*$/i_]
_}_
These are the European eduroam Confederation root servers. This entry can be kept as it stands and doesn't need any further configuration.
_server SA5-monitoring-outgoing {_
_ host 161.53.2.204_
_ type UDP_
_ secret \__MONITORING_SECRET_\_\_
_}_
_server TODO:add SRCE RadSec server here {_
_ type TLS_
_ secret mysecret_
_ statusserver on_
\_ matchcertificateattribute _
_SubjectAltName:URI:/^urn:geant:eduroam:component:confederation-root:Europe:Monitoring:.*/i_
_}_
SA5 monitoring works both ways. The client entry near the beginning of the configuration file was needed for incoming requests from the monitoring servers. The two entries here specify the outgoing connections to the monitoring servers. Outgoing connections can use either RADIUS (first entry) or RadSec (second entry) at your discretion. You can configure both, and select the preferred way later in the special monitoring realm *eduroam.TLD*.
Finally, the IdP realms need to be defined. This is done in the remainder of the configuration file:
_realm /myabc\.com$ {_
_ replymessage "Misconfigured client: default realm of Intel PRO/Wireless supplicant\! Rejected by <TLD>."_
_}_
\_realm /^\[radsecproxy-flr^@\]*$ { replymessage "Misconfigured client: empty realm! Rejected by <TLD>."__}_
There are some known client-side misconfigurations. If they were not already caught by the SP local RADIUS server, it does not make sense for the proxy to send these requests up to the eduroam infrastructure. These requests are immediately rejected.
*Note:* if you need to blacklist an existing realm for some reason, you can follow the myabc.com example, copying and replacing it with the realm to be blacklisted.
_realm /_{_}IDP_REALM{_}_$ {_
_ server \__FROM_SERVER_STANZAS_ABOVE_\_\_
_ server \__BACKUP_NAME_\_\_
_}_
Requests that are coming in from upstream and are supposed to be handled by an identity provider are listed in stanzas like this. __IDP_REALM__ contains the realm of the connected IdP. Create one such stanza for each IdP realm. If an IdP has multiple servers for a failover configuration, you can list all servers in a row, as in the example above.
_realm /eduroam\._{_}YOUR_TLD__ {\__ server SA5-monitoring-outgoing{_}_ server TODO:SRCE RadSec server{_}_}_
The configuration stanza above is for outgoing SA5 monitoring connections. You can select your preference for RADIUS or RadSec for the outgoing connections by changing the order of the server stanzas.
_realm /\._{_}YOUR_TLD{_}_$ {_
_ replymessage "Misconfigured supplicant or downstream server: uses known\- bad realm in <TLD> federation\!"_
_}_
All the valid realms were listed earlier in the configuration file, and this server is authoritative for the own TLD. If a supplicant or downstream servers sends a realm with the own TLD, but also with a realm name that is not registered, this request is unauthorised and bound to fail. It will be rejected immediately to prevent routing loops.
_realm \* {_
_ server etlr1.eduroam.org_
_ server etlr2.eduroam.org_
_}_
Finally, all realms that do not belong to the own federation are forwarded to the European eduroam Confederation root servers. |