Piwik SAML authentication module allows users to login to Piwik using SAML Identity Provider (IdP).

If you have a federated environment with a SAML Identity Provider (OneLogin, Okta, Ping Identity, ADFS, Google, Salesforce, SharePoint…), you can use this plugin to inter-operate with it thereby enabling SSO for your Piwik Analytics users.

Installation

Requirements

Installation

Install the plugin according to our plugin installation guide

Configuration

To configure SAML authentication follow these steps:

  1. Login as a Super User

  2. On the Administration > Plugins page, activate the LoginSaml plugin.

  3. Navigate to Settings > SAML page
    image

  4. Enter and save settings for SAML: add the Identity Provider info, set the attribute mappings and configure the other options as applicable.

  5. Share Service Provider metadata with the IdP administrator
    image

  6. Enable the SAML authentication
    image

  7. You can now open a new browser session and try to login with the SAML Identity Provider.
    image

SAML Configuration support

Configuring SAML Authentication properly can be difficult so we offer our services to help you get Piwik Analytics successfully working with SAML and enjoy the great benefits of SSO. Learn more and contact us in the SAML Support page.

SAML plugin settings

Now that you know the main configuration steps, let’s provide details about the SAML configuration.

Status Settings

Once you activate the SAML plugin, you are able to access its settings panel.

image

In Status Settings section you see Enable SAML authentication is disabled. When disabled, all SAML actions are disabled and if a user tries to execute them, she will receive an error notifying that the SAML functionality is disabled.

You may only enable it when the rest of the SAML settings are properly configured.

In SAML, there are 2 different kind of entities:
1. the Identity Providers IdP (the 3rd party entity where the user is authenticated), and
2. the Service Provider SP (the service that protect the app, in this case Piwik).

A circle of trust is defined between IdP and the SP, allowing all IdP users to access the SP under some conditions. That circle of trust is based on the exchange of an XML, named metadata, that describes the Entity ID, the entity endpoints and the public certificates (that will allow validation of signed/encrypted SAML messages).

Identity Provider Settings

In the Identity Provider Settings section, you may register the Identity Provider metadata.

You can directly fill the form:

image

or click on the Import values from IdP metadata link:

image

This link will redirect to a form where two different methods are offered to let you import the Identity Provider metadata:

  1. By metadata URL
  2. By string XML

In case the imported metadata contains more than 1 Identity Provider entity description, you can use the IdP entity ID to identity the desired entity:

image

Option settings

In Option settings section you can define how Piwik SAML integration will act.

image

In some scenarios it makes sense to enable the Just-in-time provisioning when you want to automatically create user accounts based on the data provided by the Identity Provider on the SAMLResponse.

  • If just-in-time provisioning is disabled or the required user data is not provided, an error will happen during the SSO process since we will not be able to initiate any Piwik account.

  • If just-in-time provisioning is enabled, by default any new users (created with just-in-time provisioning) will have no access to Piwik. You may set a default view permission (What is the ‘view’ permission in Piwik?) to some Piwik websites. Use the Initial sites with view access for new users to set a list of the Piwik Website IDs that the users will be able to view by default (comma separated list of Website IDs).

In order to identify your Piwik user accounts you need to set a value on the Field to identify the user, by default the email field will be used, but you can select username and the Piwik username field will be used.

You may also enable or disable the single logout functionality. Note that if you disable it, the Single Logout Service data will be not published on the Service Provider metadata.

Attribute Mapping Settings

Depending on the values of Field to identify the user and just-in-time provisioning, the fields of the Attribute Mapping Settings section will be either required or optional.

image

  • If just-in-time is enabled, all mapping fields will be required.
  • If just-in-time provisioning is disabled then only the field related to the value of Field to identify the user will be required.

Identity Providers sends to the Service Provider the user data with custom attribute names, so you can use the previous form to map names between IdP and Piwik.

Access Synchronization settings

In the Access Synchronization settings section you can enable the user access synchronization from SAML attributes.

image

LoginSAML supports synchronizing access levels using attributes found in the SAMLResponse provided by the Identity provider. To use this feature, be sure that the IdP is providing access data in 3 different SAML attributes:

Note: You can choose whatever names you want for these attributes. You will then tell LoginSaml about these names in the SAML settings page.

Identity provider access data example:

<saml:Attribute Name="view" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xsi:type="xs:string">all</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="admin" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xsi:type="xs:string">1,2,3</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="superuser" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xsi:type="xs:string">1</saml:AttributeValue>
</saml:Attribute>

Then in the SAML settings page, check the Enable User Access Synchronization from SAML checkbox and fill out the settings that appear below it.

User access synchronization occurs before the user logs in.

Managing Access for Multiple Piwik Instances

LoginSaml supports using a single IdP SAML server to manage access for multiple Piwik instances. If you’d like to use this feature, you must specify special values for SAML access attributes. For example:

  • view: mypiwikserver.whatever.com:1,2,3;myotherserver.com:all
  • admin: mypiwikserver.whatever.com:all;mythirdserver.com:3,4
  • superuser: myotherserver.com;myotherserver.com/otherpiwik

If you don’t want to use URLs in your access attributes, you can use the Special Name For This Piwik Instance setting to specify a special name for each of your Piwik instances. For example, if you set it to piwikServerA in one Piwik and piwikServerB in another, your SAML attributes might look like:

  • view: piwikServerA:1,2,3;piwikServerB:all
  • admin: piwikServerA:4,5,6
  • superuser: piwikServerC

Using a custom access attribute format

You can customize the separators used in access attributes by setting the User Access Attribute Server Specification Delimiter and User Access Attribute Server & Site List Separator settings.

If you set the User Access Attribute Server Specification Delimiter option to #, access attributes can be specified as:

view: piwikServerA:1,2,3#piwikServerB:all

If you set the User Access Attribute Server & Site List Separator option to #, access attributes can be specified as:

view: piwikServerA#1,2,3;piwikServerB#all

Advanced Settings

In the Advanced Settings section you can enable/disable the debug mode and also configure advanced SAML and security parameters.

Those settings match php-saml settings (the underlying PHP library in use in the SAML plugin and provided by OneLogin inc.), so you can review its documentation for more information.

image

Debugging

LoginSAML uses debug logging extensively so problems can be diagnosed quickly. Some logs entries contain sensitive information, so be sure to disable DEBUG logging in production and also switch off the Debug Mode in the Advanced Settings section of the SAML settings panel.

By default logs related with SAML will be found in Piwik folder tmp/logs/saml.log but can be changed defining a new value for the logger_file_path setting in the [LoginSaml] section of config/config.ini.php

The log level can be configured with the ‘log_level’ parameter and possible values are:

  • ERROR
  • WARN
  • INFO
  • DEBUG

The higher level, the smaller number of entries in logs. The highest level is ERROR level (the lowest is DEBUG).

If no log_level parameter defined in [LoginSaml] section then the default Piwik log_level value will be used (WARN).

How does SAML plugin for Piwik work?

This plugin adds the ability to execute SAML Single Sign On (SSO) and Single Logout (SLO) on the Service Provider side, but also on the Identity Provider. This section describes the SAML authentication flows.

SP-initiated SSO authentication process

image

  1. Redirect to Identity Provider (when “SAML Login” button on login screen is clicked):
    • Log message: Initiated the Single Sign On, Redirecting to the IdP (Log level: info)
  2. When response from Identity Provider has come to Assertion Consumer Service endpoint:
    • Log message: Initiated the Assertion Consumer Service (Log level: info)
  3. SAML validation successful:
    • Log message: SAMLResponse validated (Log level: info)
    • Log message: Attributes + NameId + NameIDFormat + SessionIndex (Log level: debug)
  4. Or SAML validation returned some errors in response from Identity Provider:
    • Log message: SAMLResponse rejected. + Cause (Log level: error)
    • Log message: SAML Response XML (Log level: debug)
  5. User creation (Optional step, if account was not found):
    • If user does not exist but Just-In-Time provisioning is enabled and required attributes are provided: Log message: Added user (Log level: info)
    • If user has no default sites access: Log message: SAML settings does not define default sites to provide access to new users in ‘Options’ section (Log level: warning)
    • If user has default sites access: Log message: Adding to user USER access to sites: SITES (Log level: info)
    • If user does not exists and Just-In-Time provisioning is enabled but process has failed: Log message: Just-in-time provisioning error // X mapping is required // X was not provided ( Log level: error)
    • If user does not exists and Just-In-Time provisioning disabled: Log message: User does not exists and just-in-time provisioning is disabled (Log level: error)
  6. Sync access (Optional step, if sync access enabled):
    • If user has no data access: Log message: User has no access in SAML, but access synchronization is enabled. (Log level: warning)
    • If access data defines that user should be assigned as superuser: Log message: PiwikAccess synchronised. User is now superuser ( Log level: info)
    • If access data defines user access on sites: *Log message**: PiwikAccess synched. Access of user updated (Log level: info)
  7. Successful login:
    • Log message: User with login authenticated in Piwik (Log level: info)

IdP-initiated SSO authentication process

image

Similar to SP-initiated SSO but without step 1.

SP-initiated Single Logout authentication process (SLO enabled)

image

  1. Redirect to Identity Provider. (Logout Request sent). When “logout” link clicked and user session initiated with SAML flow:
    • Log message: Initiated the Single Log Out for user with login USER (Log level: info)
  2. When Logout Response from Identity Provider has come to Single Logout Service endpoint:
    • Log message: Initiated the Single Logout Service for user with login USER (Log level: info )
  3. SAML validation:
    • If SAML Logout Response is valid: Log message: Single Logout Service executed. User with login USER logged out ( Log level: info )
    • If there are some errors in Logout Response from Identity Provider: Log message: Error at Single Logout Service endpoint. User with login USER. + Error reason ( Log level: error)

IdP-initiated Single Logout authentication process (SLO enabled)

image

  1. When Logout Request from Identity Provider has come to Single Logout Service endpoint:
    • Log message: Initiated the Single Logout Service for user with login USER (Log level: info)
  2. SAML validation:
    • If there are some errors in Logout Request from Identity Provider: Log message: Error at Single Logout Service endpoint. User with login USER. + Error reason (Log level: error)
  3. Redirect to Identity Provider (Logout Response sent)
  4. When Logout Response from Identity Provider has come to Single Logout Service endpoint:
    • Log message: Initiated the Single Logout Service for user with login USER ( Log level: info )
  5. SAML validation is successful:
    • Log message: Single Logout Service executed. User with login USER logged out (Log level: info )
  6. Or SAML validated failed: errors returned in Logout Response from Identity Provider:
    • Log message: Error at Single Logout Service endpoint. User with login USER. + Error reason (Log level: error)

To learn more about how SAML flows works, visit:

Security Considerations

User passwords

LoginSAML’s generates for new users random hashed passwords. If those users want to use the normal login process, they should assign a valid password for them once authenticated via SAML.

Token Auths

SAML has no concept of authentication tokens, so a user’s token_auth is stored exclusively in Piwik database. If a token_auth is compromised, you can re-generate the token in Piwik > Administration > Personal Settings.

Logging

LoginSAML uses debug logging extensively so problems can be diagnosed quickly. Some logs entries contain sensitive information, so be sure to disable DEBUG logging in production and also switch off the “debug” mode on the advanced settings section of the SAML settings panel.

Learn more on the LoginSaml for Piwik Analytics – SAML authentication plugin page.

Any questions?

Many answers and more information about Piwik You can find here:

We are social

Follow us: