Versions Compared

Version Old Version 15 New Version 16
Changes made by

wqx+qmnstigwu5kzxaiskxnikzy@idp.company.ja.net

wqx+qmnstigwu5kzxaiskxnikzy@idp.company.ja.net

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Numberedheadings
start-numbering-with1

Introduction

Deployers of moonshot enabled services may wish external users to authenticate to their service but control the user account that each particular user has access to. For example, mapping specific external users to specific local linux accounts when logging in through SSH, or specific external users to specific local mailboxes when logging in to Exchange, etc.

Additionally, it often is the case that a user may have multiple identities he/she would like to associate with their local account. For example, a scientist may wish to use their institutional identity (as issued by their home institution), as well as perhaps a Google or Facebook account, where allowed.

It is also the case that not all associations are trusted equally. In some cases, the institutional identity may have a higher level of assurance than a social platform like Google or Facebook, and the organisation may wish to restrict logging into more sensitive systems to identities with higher levels of assurance. For example, the scientist is allowed to use their Google or Facebook account to sign into reference libraries, user accounts, project and grant submission systems, but may only use their institutional identity to log into data libraries containing sensitive research data.

Based on these requirements, i.e. mapping external to internal identifiers, multiple identities and different levels of assurance, a database table with four columns is sufficient. 

The examples on this page use MySQL as the database dialect and RHEL or one of its derivatives as the operating system. If using a different database technology or OS, convert the commands or FreeRADIUS filesystem paths as relevant.

Where does the mapping happen?

In this scenario, the mapping from external user to internal happens on the Moonshot RP Proxy. A single Moonshot RP Proxy can handle mappings for multiple Moonshot-enabled services, as the database will record which service the mapping is associated with. However, this means that the administrator of the Moonshot RP Proxy (or rather, the administrator of the database) will need to either manage all of the mappings for all of the services that make use of their Moonshot RP Proxy, or give all administrators of those systems access to the database. An alternative would be for each system that wishes to make use of mappings run their own Moonshot RP proxy.

Configure the RP Proxy

The first thing needed is to configure your Moonshot RP Proxy (or Moonshot IdP if you are using that as both an IdP and an RP Proxy) to make use of the database of mappings that we will set up in the next step.

Enable the FreeRADIUS SQL module

To access the database from your Moonshot RP proxy (FreeRADIUS), you must configure FreeRADIUS to enable database support. FreeRADIUS by default supports SQLite, MySQL/MariaDB, PostgreSQL, and any database that supports Unix ODBC connections. However, depending on your database dialect, you may have to install the FreeRADIUS module for it to enable this support.

Example - adding support for MySQL to FreeRADIUS

To add support for MySQL in FreeRADIUS on RHEL, issue the following command:

bash

 

After installation, configure the SQL module:

  1. Edit /etc/raddb/mods-available/sql

  2. In the sql section, adjust the driver value to your database dialect as per the comments above it:

    true
  3. Depending on your database dialect, you may wish to adjust some of the options that are specific for your database dialect. 

  4. Adjust the dialect line to match your database dialect as per the comments above it:

    true

  5. Remove the comments from the server, port, login and password lines and adjust them to suit:

    true

    You must ensure that the login user and password are created in the database before you start the FreeRADIUS server. See your database documentation on how to create users in your database, or use the supplied FreeRADIUS setup scripts for your database dialect to create a default database.

  6. Adjust the radius_db line to suit your database dialect. Take note of the additional options documented that may be applicable to your database dialect.
  7. If you do not use RADIUS accounting, check or reply items, and/or don't store your users in a database, comment out any tables that are not applicable to you.

  8. Save the file and create a soft link to enable the SQL module:

    bash

    If your Moonshot RP Proxy is also your Moonshot IdP, and you make use of LDAP for authentication, you will have to comment out the call to sql in FreeRADIUS' inner-tunnel configuration.

Shared vs Different local identifiers

There are typically two deployment models for user mapping to multiple moonshot-enabled services managed by a single Moonshot RP Proxy:

  • Where all backends are separate and a single user might have different local user identifiers per system; or
  • Where all backends are related and a single user would have the same local user identifier across all of the backend systems.

Instructions differ depending on your particular deployment model, so follow the correct set of following instructions for you:

Option 1 - Different local user identifier per system

Configure the Database

The first thing that is needed is a database to store these mappings. In your favourite database server software, create a table with four columns:

gss_acceptortargeted_idlocal_uidauth_type
varchar(256)varchar(256)varchar(32)smallint
Example - Creating the mapping table in MySQL

In MySQL, you can achieve this with the following command:

bash

The first column will contain the gss_acceptor name for the service, made up of the GSS-Acceptor-Service-Name and GSS-Acceptor-Host-Name of the service (e.g. host/ssh-server.example.com).

The second column will store the incoming targeted identifier. The incoming value will generally be qualified, i.e. it will be a value with the incoming realm appended to it (i.e. value@REALM). The width is limited to the maximum length of the SAML eduPersonTargetedID attribute. Alternatively, you may wish to use the maximum length of any RADIUS attribute (253 octets).

The third column is the local account name. The width is limited to the maximum length of useradd(8) on Unix. On Windows, underlying usernames are limited to 20 characters for compatibility purposes (see Microsoft TechNet: Active Directory Maximum Limits - Scalability for more information on this).

The fourth column is for information (and possibly integration) purposes and contains an identifier that identifies the service used. Suggested values are zero, indicating a local-to-local mapping, one indicating a Moonshot mapping, and any other value thereafter for clearly defined values as per your organisation's choice. This field could also indicate the level of assurance.

The primary key is made up of the tuple of gss_acceptor and targeted_id, meaning that for a particular service and a particular external user, only one mapping can exist.

 

Configure the RP Proxy

The second thing needed is to configure your Moonshot RP Proxy (or Moonshot IdP if you are using that as both an IdP and an RP Proxy) to make use of the database of mappings.

Enable the FreeRADIUS SQL module

To access the database from your Moonshot RP proxy (FreeRADIUS), you must configure FreeRADIUS to enable database support. FreeRADIUS by default supports SQLite, MySQL/MariaDB, PostgreSQL, and any database that supports Unix ODBC connections. However, depending on your database dialect, you may have to install the FreeRADIUS module for it to enable this support.

Example - adding support for MySQL to FreeRADIUS

To add support for MySQL in FreeRADIUS on RHEL, issue the following command:

bash

 

After installation, configure the SQL module:

  • Edit /etc/raddb/mods-available/sql

    • In the sql section, adjust the driver value to your database dialect as per the comments above it:

    true
  • Depending on your database dialect, you may wish to adjust some of the options that are specific for your database dialect. 

    • Adjust the dialect line to match your database dialect as per the comments above it:

    true

    Remove the comments from the server, port, login and password lines and adjust them to suit:

    true

    You must ensure that the login user and password are created in the database before you start the FreeRADIUS server. See your database documentation on how to create users in your database, or use the supplied FreeRADIUS setup scripts for your database dialect to create a default database.

  • Adjust the radius_db line to suit your database dialect. Take note of the additional options documented that may be applicable to your database dialect.
  • If you do not use RADIUS accounting, check or reply items, and/or don't store your users in a database, comment out any tables that are not applicable to you.

    • Save the file and create a soft link to enable the SQL module:

    bashIf your Moonshot RP Proxy is also your Moonshot IdP, and you make use of LDAP for authentication, you will have to comment out the call to sql in FreeRADIUS' inner-tunnel configuration.

    Using the Moonshot-Host-TargetedId attribute in a database lookup

    A typical Moonshot deployment uses three pseudonymous targeted identifiers as issued by a Moonshot IdP - the Moonshot-Host-TargetedId, Moonshot-Realm-TargetedId, and Moonshot-TR-COI-TargetedId. These are carried as ordinary RADIUS attributes - see for further information on these identifiers and how an IdP is configured to issue them.

    To use these identifiers as the incoming attribute to be used as the remote identifier for the user, do the following:

     Create a mapping policy configuration

    1. In FreeRADIUS' /etc/raddb/policy.d directory, create a file named "moonshot".

    2. In this file place the following content:

      truecpp

      The logic of the code above is simple but very constrained:

      1. You receive a reply from an ID Provider (including your own) in the Moonshot system.
      2. If it is a trust router request, don't do anything.
      3. If that reply contains the Moonshot-Host-TargetedId, execute a SQL query in your database for the Moonshot-Host-TargetedId.
        1. If there is a local account mapping for the Moonshot-Host-TargetedId, set the Tmp-String-1 attribute to the local account for it.
        2. If there is no local account mapping for Moonshot-Host-TargetedId, set the Tmp-String-1 attribute to the Moonshot-Host-TargetedId
      4. If the reply does not contain the Moonshot-Host-TargetedId, do nothing and Tmp-String-1 will not be set to anything.
      5. Next, delete any SAML assertion contained in the SAML-AAA-Assertion attributes in the reply.
      6. Finally, create a new SAML Assertion, but this time use the value of Tmp-String-1, if it exists. If it does not, use 'moonshot'.

    Option 2 - Same local user identifier across all systems

    Configure the Database

    The first thing that is needed is a database to store these mappings. In your favourite database server software, create a table with three columns:

    targeted_idlocal_uidauth_type
    varchar(256)varchar(32)smallint
    Example - Creating the mapping table in MySQL

    In MySQL, you can achieve this with the following command:

    bash

    The first column will store the incoming targeted identifier. The incoming value will generally be qualified, i.e. it will be a value with the incoming realm appended to it (i.e. value@REALM). The width is limited to the maximum length of the SAML eduPersonTargetedID attribute. Alternatively, you may wish to use the maximum length of any RADIUS attribute (253 octets).

    The second column is the local account name. The width is limited to the maximum length of useradd(8) on Unix. On Windows, underlying usernames are limited to 20 characters for compatibility purposes (see Microsoft TechNet: Active Directory Maximum Limits - Scalability for more information on this).

    The third column is for information (and possibly integration) purposes and contains an identifier that identifies the service used. Suggested values are zero, indicating a local-to-local mapping, one indicating a Moonshot mapping, and any other value thereafter for clearly defined values as per your organisation's choice. This field could also indicate the level of assurance.

    The primary key is the targeted_id, meaning that for a particular external user, only one mapping can exist.

     

    Using the Moonshot-Host-TargetedId attribute in a database lookup

    A typical Moonshot deployment uses three pseudonymous targeted identifiers as issued by a Moonshot IdP - the Moonshot-Host-TargetedId, Moonshot-Realm-TargetedId, and Moonshot-TR-COI-TargetedId. These are carried as ordinary RADIUS attributes - see for further information on these identifiers and how an IdP is configured to issue them.

    To use these identifiers as the incoming attribute to be used as the remote identifier for the user, do the following:

     Create

     Create a mapping policy configuration

    1. In FreeRADIUS' /etc/raddb/

    policy

    1. policy.d directory, create a file named "moonshot".

    2. In this file place the following content:

      truecpp

      The logic of the code above is simple but very constrained:

      1. You receive a reply from an ID Provider (including your own) in the Moonshot system.
      2. If it is a trust router request, don't do anything.
      3. If that reply contains the Moonshot-Host-TargetedId, execute a SQL query in your database for the Moonshot-Host-TargetedId.
        1. If there is a local account mapping for the Moonshot-Host-TargetedId, set the Tmp-String-1 attribute to the local account for it.
        2. If there is no local account mapping for Moonshot-Host-TargetedId, set the Tmp-String-1 attribute to the Moonshot-Host-TargetedId
      4. If the reply does not contain the Moonshot-Host-TargetedId, do nothing and Tmp-String-1 will not be set to anything.
      5. Next, delete any SAML assertion contained in the SAML-AAA-Assertion attributes in the reply.
      6. Finally, create a new SAML Assertion, but this time use the value of Tmp-String-1, if it exists. If it does not, use 'moonshot'.

    Enabling the mapping policy

    To use the policy, it has to be enabled by using it.

    1. In /etc/freeradius/sites-enabled/abfab-tr-idp, find the post-auth section. At the top, insert onto its own line the following:

      true

      You can adjust where you want to call the policy that inserts the Moonshot policy, as long as it is called in the post-auth section of abfab-tr-idp.

      If you use non-TLS connections for Moonshot, you may wish to repeat Step 2 in /etc/freeradius/sites-enabled/default.

    2. Restart FreeRADIUS.

    Testing the mapping

    Create a manual mapping entry in your database with a test user from Janet (please contact us for it).

    1. Run FreeRADIUS in debug mode.
    2. Execute an authentication request with the Janet test user. The debug output will include the Moonshot-Host-TargetedId that can be copied.

    3. Insert the TargetedId together with the chosen username on your local systems with SQL:

      Option 1 - Different user identifiers per systemOption 2 - Same user identifier across all systems
    4. Execute another authentication request with the Janet user. You should now see the local username in the SAML-AAA-Assertion.

    Populating the mapping database

    To populate the mapping database in a production environment, you will need to create a system that will require the user to log in twice, once with their local user (which should give you access to the local username), and once with Moonshot to gain access to one (or more) of the Moonshot TargetedIds. Then you will be able to create an entry in the database that contains the mapping.