SAML authentication

MunkiReport uses OneLogin's SAML PHP Toolkit. This is a straightforward, modern library that is easy to integrate with MunkiReport. All SAML configurations are different, below is a general configuration followed by an example used at a university.

Configuration

To configure MunkiReport for SAML authentication, you need at least add the following to .env:

AUTH_METHODS=SAML
AUTH_SAML_SP_NAME_ID_FORMAT=urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
AUTH_SAML_IDP_ENTITY_ID=https://app.onelogin.com/saml/metadata/xxx
AUTH_SAML_IDP_SSO_URL=https://xxx-dev.onelogin.com/trust/saml2/http-post/sso/xxx
AUTH_SAML_IDP_SLO_URL=https://xxx-dev.onelogin.com/trust/saml2/http-redirect/slo/xxx
AUTH_SAML_IDP_X509CERT=MIIDHzCCAgegAwIBAgIUF1A5OQ50ULddi80RkyMVt2S5...

Replace the values with the correct values for your environment.

• sp - This is the Service Provider array. You should at least add the NameIDFormat here. MunkiReport will automatically fill in the correct endpoints (metadata, acs and sls). You can also override entityId here which may be preferable over the default SP entityID.
• idp - This is the Identity Provider array. You need to add the proper connection details for your IdP.
• entityId - URI to the IdP metadata
• singleSignOnService - Array containing one or more URIs to the Single Sign On endpoints of the IdP.
• singleLogoutService - Array containing one or more URIs to the Single Sign Out endpoints of the IdP.
• x509cert - Public x509 certificate of the IdP
• disable_sso - boolean Force authentication allows you to force re-authentication of users even if the user has a SSO session at the IdP.

Metadata

The Identity Provider needs some information from the MunkiReport SAML Service. You can generate this via this endpoint:

https://your-munkireport-server/index.php?/auth/saml/metadata

Attribute Mapping

MunkiReport needs to know which attributes to map to user and to groups. You can add your own attribute mapping to .env:

AUTH_SAML_USER_ATTR=User.email
AUTH_SAML_GROUP_ATTR=memberOf # specify more attributes separated by `,`

Authorization

You can handle authorization in the IdP by only allowing users and or groups to authenticate for MunkiReport. But you can also handle authorization in the SAML configuration:

AUTH_SAML_ALLOWED_USERS="your_username, another_user"
AUTH_SAML_ALLOWED_GROUPS="admingroup, servicedesk"

Logout

If you can't use Single Logout, you can specify

AUTH_SAML_DISABLE_SSO=TRUE

This setting will use the identity provider for authentication, but not via Single Sign On. Logging out will not notify the IdP but just destroy the session.

More information/settings

Here is the complete list of settings:

Setting	Default
AUTH_SAML_SP_NAME_ID_FORMAT	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
AUTH_SAML_SP_ENTITY_ID
AUTH_SAML_IDP_ENTITY_ID	https://app.onelogin.com/saml/metadata/xxxx
AUTH_SAML_IDP_SSO_URL	https://yourorg.onelogin.com/trust/saml2/http-post/sso/xxxx
AUTH_SAML_IDP_SLO_URL	https://yourorg.onelogin.com/trust/saml2/http-redirect/slo/xxxx
AUTH_SAML_IDP_X509CERT
AUTH_SAML_USER_ATTR	User.email
AUTH_SAML_GROUP_ATTR	['memberOf']
AUTH_SAML_DISABLE_SSO	false
AUTH_SAML_DEBUG	false
AUTH_SAML_SECURITY_NAME_ID_ENCRYPTED	false
AUTH_SAML_SECURITY_AUTHN_REQUESTS_SIGNED	false
AUTH_SAML_SECURITY_LOGOUT_REQUEST_SIGNED	false
AUTH_SAML_SECURITY_LOGOUT_RESPONSE_SIGNED	false
AUTH_SAML_SECURITY_SIGN_METADATA	false
AUTH_SAML_SECURITY_WANT_MESSAGES_SIGNED	false
AUTH_SAML_SECURITY_WANT_ASSERTIONS_ENCRYPTED	false
AUTH_SAML_SECURITY_WANT_ASSERTIONS_SIGNED	false
AUTH_SAML_SECURITY_WANT_NAME_ID	true
AUTH_SAML_SECURITY_WANT_NAME_ID_ENCRYPTED	false
AUTH_SAML_SECURITY_REQUESTED_AUTHN_CONTEXT	true
AUTH_SAML_SECURITY_WANT_XML_VALIDATION	true
AUTH_SAML_SECURITY_RELAX_DESTINATION_VALIDATION	false
AUTH_SAML_SECURITY_SIGNATURE_ALGORITHM	http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
AUTH_SAML_SECURITY_DIGEST_ALGORITHM	http://www.w3.org/2001/04/xmlenc#sha256
AUTH_SAML_SECURITY_LOWERCASE_URLENCODING	false
AUTH_SAML_ALLOWED_USERS	[]
AUTH_SAML_ALLOWED_GROUPS	[]
AUTH_SAML_CERT_DIR	local_conf('certs/')

See also https://github.com/onelogin/php-saml#settings

Example

You can use the free SAML test site at https://samltest.id. This site uses Shibboleth, a SAML implementation. To test if your site can use SAML, use the following settings:

AUTH_METHODS="SAML"
AUTH_SAML_SP_NAME_ID_FORMAT=urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
AUTH_SAML_IDP_ENTITY_ID=https://samltest.id/saml/idp
AUTH_SAML_IDP_SSO_URL=https://samltest.id/idp/profile/SAML2/Redirect/SSO
AUTH_SAML_IDP_X509CERT=MIIDEjCCAfqgAwIBAgIVAMECQ1tjghafm5OxWDh9hwZfxthWMA0GCSqGSIb3DQEBCwUAMBYxFDASBgNVBAMMC3NhbWx0ZXN0LmlkMB4XDTE4MDgyNDIxMTQwOVoXDTM4MDgyNDIxMTQwOVowFjEUMBIGA1UEAwwLc2FtbHRlc3QuaWQwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC0Z4QX1NFKs71ufbQwoQoW7qkNAJRIANGA4iM0ThYghul3pC+FwrGv37aTxWXfA1UG9njKbbDreiDAZKngCgyjxj0uJ4lArgkr4AOEjj5zXA81uGHARfUBctvQcsZpBIxDOvUUImAl+3NqLgMGF2fktxMG7kX3GEVNc1klbN3dfYsaw5dUrw25DheL9np7G/+28GwHPvLb4aptOiONbCaVvh9UMHEA9F7c0zfF/cL5fOpdVa54wTI0u12CsFKt78h6lEGG5jUs/qX9clZncJM7EFkN3imPPy+0HC8nspXiH/MZW8o2cqWRkrw3MzBZW3Ojk5nQj40V6NUbjb7kfejzAgMBAAGjVzBVMB0GA1UdDgQWBBQT6Y9J3Tw/hOGc8PNV7JEE4k2ZNTA0BgNVHREELTArggtzYW1sdGVzdC5pZIYcaHR0cHM6Ly9zYW1sdGVzdC5pZC9zYW1sL2lkcDANBgkqhkiG9w0BAQsFAAOCAQEASk3guKfTkVhEaIVvxEPNR2w3vWt3fwmwJCccW98XXLWgNbu3YaMb2RSn7Th4p3h+mfyk2don6au7Uyzc1Jd39RNv80TG5iQoxfCgphy1FYmmdaSfO8wvDtHTTNiLArAxOYtzfYbzb5QrNNH/gQEN8RJaEf/g/1GTw9x/103dSMK0RXtl+fRs2nblD1JJKSQ3AdhxK/weP3aUPtLxVVJ9wMOQOfcy02l+hHMb6uAjsPOpOVKqi3M8XmcUZOpx4swtgGdeoSpeRyrtMvRwdcciNBp9UZome44qZAYH1iqrpmmjsfI9pJItsgWu3kXPjhSfj1AJGR1l9JGvJrHki1iHTA==
AUTH_SAML_DISABLE_SSO=TRUE
AUTH_SAML_USER_ATTR=urn:oid:2.16.840.1.113730.3.1.241
AUTH_SAML_GROUP_ATTR=https://samltest.id/attributes/role
AUTH_SAML_ALLOWED_GROUPS="[email protected]"

You will need to let SAMLtest.id know about your site by linking to/uploading your metadata as mentioned above.

Authenticating as rick will let you in because he's in the [email protected] group, authenticating as morty and sheldon will result in an unauthorised message as they are not in a proper group.