Configuring SAML Single Sign-on

General SAML Configuration

Make sure ggrc_saml is one of the listed modules in the environment variable ZENGRC_EXTENSIONS.
Example:

ggrc_risks
ggrc_basic_permissions
ggrc_workflows
ggrc_stand_alone_login
ggrc_reporting_dashboard
ggrc_saml
Edit the saml_settings.json file with required SAML settings.
By default the ZenGRC container looks for the file /zengrc/settings/app/saml_settings.json

Place this file in a directory outside the container and then mount the directory into the container.

By default the settings directory is mounted as /zengrc/app/settings as shown:

volumes:
- "./settings:/zengrc/settings/app"

You can put the saml_settings.json file directly in the settings directory. To check if the file is appearing properly to the application you can shell into the container via docker exec -it ash

SAML Settings Overview

SAML Setting Name	Default	Description
strict	True	If strict is True, then ZenGRC will reject unsigned or unencrypted messages if it expects them to be signed or encrypted. It will also reject the messages if the SAML standard is not strictly followed. Destination, NameId, Conditions are validated as well.
debug	False	Enable debug mode and output errors to the console.
sp['entityId']	http://example.com:8080/saml/metadata	Identifier of the SP entity. Parameter must be a URI (but does not necessarily have to be resolvable)
sp['assertionConsumerService']['url'] sp['assertionConsumerService']['binding']		URL Location where the <Response> from the IdP will be returned. Additionally the SAML protocol binding to be used when returning the <Response> message. ZenGRC only supports the HTTP-POST binding.
sp['singleLogoutService']['url'] sp['singleLogoutService']['binding']		Where the <Logout Response> message will be sent. This is the URL location of the logout service of the service provider. ZenGRC supports the HTTP-Redirect binding only for this endpoint.
sp['NameIDFormat']	"urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified"	Constraints on the SAML NameID format. For ADFS this needs to be changed to “urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified”
sp['x509cert'] sp['privateKey']		Certificate and private key for ZenGRC. This can be the same certificate used by nginx though it does not necessarily have to be. This is the certificate that needs to be trusted by your SAML IdP (whether it is OneLogin, Ping Identity, Active Directory FS, etc). The format must be a single line PEM encoded with header, footer, and newlines stripped. Refer to “Generating a Self Signed Certificate” if needed.
idp["entityId"] idp["singleSignOnService"] idp["singleLogoutService"] idp["x509cert"]		These are the corresponding variables for the IdP. The x509 certificate here will be used to validate any assertions that are issued by the IdP (i.e. ZenGRC will trust this certificate)
security['nameIdEncrypted']	true	Indicates that the nameID of the <samlp:logoutRequest> sent by ZenGRC will be encrypted.
security['authnRequestsSigned'	false	Indicates whether the <samlp:AuthnRequest> messages sent by ZenGRC will be signed.
security['logoutRequestSigned']	false	Indicates whether the <samlp:logoutRequest> messages sent by ZenGRC will be signed.
security['logoutResponseSigned ']	false	Indicates whether the <samlp:logoutRequest> messages sent by this SP will be signed.
security['signMetadata']	false	Sign the metadata
security[wantMessagesSigned']	false	Requires the <samlp:Response>, <samlp:LogoutRequest> and <samlp:LogoutResponse> elements received by ZenGRC to be signed.
security['wantAssertionsSigned']	false	Requires the <saml:Assertion> elements received by ZenGRC to be signed.
security['wantNameIdEncrypted']	false	Indicates a requirement for the NameID received by ZenGRC to be encrypted.
security['requestedAuthnContext']	true	Set to false and no AuthContext will be sent in the AuthNRequest, Set to true or don't present thi s parameter and you will get an AuthContext 'exact' 'urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport' Set to an array with the possible auth context values: ['urn:oasis:names:tc:SAML:2.0:ac:classes:Password', 'urn:oasis:names:tc:SAML:2.0:ac:classes:X509']
security['signatureAlgorithm']	http://www.w3.org/2000/09/xmldsig#rsa-sha1	Algorithm that the toolkit will use on signing process. Options: 'http://www.w3.org/2000/09/xmldsig#rsa-sha1' 'http://www.w3.org/2000/09/xmldsig#dsa-sha1' 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256' 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha384' 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha512'

ZenGRC uses the Python-SAML library for SAML Authentication. For further reading regarding settings: https://github.com/onelogin/python-saml#how-it-works