Mapping Configuration File

Under Resources/Private/sample-config.txt you find a sample config file. It makes use of the Typoscript parser to achieve maximum flexibility. To better understand, what it does, let’s examine it’s structure.

tx_shibboleth {
    FE {
        // definitions for frontend authentication and authorization
    }
    BE {
        // definitions for backend authentication and authorization
    }
}

Explanations:

As you can see, there are two different sections for frontend and backend authentication and authorization. Both work identically. However, you might need to set different fields in the respective TYPO3 user table.

Let’s start with a backend example.

tx_shibboleth {
    BE {
        IDMapping {
            // Map Shibboleth ID to TYPO3 username
            shibID = TEXT
            shibID.field = eppn
            typo3Field = username
        }
        userControls {
            // Control, how the user is imported and logged in
            // 'allowUser' decides, if the user is accepted by TYPO3. Set to 0 or 1.
            allowUser = TEXT
            allowUser.value = 1
            createUserFieldsMapping {
                // Set additional fields, when the user is imported for the FIRST TIME
                email = TEXT
                email.field = REMOTE_USER

                admin = TEXT
                admin.value = 0
            }
            updateUserFieldsMapping {
                // Update the user with these field values at EVERY LOGIN
                admin = TEXT
                admin.value = 0
            }
        }
    }
}

Explanations:

Within IDMapping you have to tell TYPO3, where in the Shibboleth data it finds the username. Set shibID to the desired value by referencing the appropriate Shibboleth attribute (REMOTE_USER in our example). In standard TYPO3 installations typo3Field must be set to username. Take care to select a unique Shibboleth field.

Hint: Make sure your selection of the identifier field ist appropriate for your use case. As all components of Shibboleth are highly configurable and use cases my vary, we cannot give a final advise here. However, in most cases you will probably choose a field that is unique, persistent and global. A typical choice could be eppn. For more information on properties of name identifiers, see https://wiki.shibboleth.net/confluence/display/CONCEPT/NameIdentifiers!

Within userControls there are three parts. For simplicity, in our example we use just one-to-one mappings and hard-coded values. In real world, you might want to use the full toolset of Typoscript (e.g. CASE, COA, noTrimWrap etc.) to set values.

• allowUser represents (your) decision to accept the user for TYPO3. If this evaluates to 1, the user will be accepted.
• createUserFieldsMapping is a section that is applied only once, i.e. when a user is auto-imported for the first time.
• updateUserFieldsMapping is a section that is applied each time shibboleth authenticates an user that is already in the TYPO3 database. It is not run for new users.

In our example, we accept all Shibboleth users. ( allowUser.value = 1 )

In both *UserFieldsMapping sections you can use basically any TYPO3 field that exists in the user table. Take care of the few differences between fe_users and be_users (e.g. admin only exists in be_users).

On auto-import, we set the email address field of the new TYPO3 user to the value transferred in REMOTE_USER. However, we do not update this field later on. This makes sense here, as the source field is also the user ID.

On each subsequent authentication the user record is updated. In our example, only the admin flag is affected by the update. The idea here is to make sure a user is not given the “admin” privilege manually. (Again, this is a decision to be made in accordance to your requirements.)

Important hint: If you want a field to be set in all cases, you have to put the configuration in both sections, createUserFieldsMapping and updateUserFieldsMapping.

Now to a frontend example:

tx_shibboleth {
        FE {
                IDMapping {
                        shibID = TEXT
                        shibID.field = eppn
                        typo3Field = username
                }
                userControls {
                        allowUser = TEXT
                        allowUser.value = 1
                        createUserFieldsMapping {
                                email = TEXT
                                email.field = mail

                                usergroup = TEXT
                                usergroup.value = 1

                                name = TEXT
                                name.field = Shib-realname
                        }
                        updateUserFieldsMapping {
                                email = TEXT
                                email.field = mail

                                name = TEXT
                                name.field = Shib-realname
                        }
                }
        }

Important to note: You have to set the usergroup field for FE users. Creating a user without a usergroup entry doesn’t work, as the user will not be accepted by TYPO3.