How to configure SAML
Path: Community Settings >> Security >> Single Signon Settings
Security Assertion Markup Language, or SAML, is one of IdeaScale’s several offerings for web browser Single Sign-On (SSO). SAML is an XML-based open-standard for exchanging authentication and authorization between security domains. There are two parties involved who exchange authentication information: first, there is the Identity Provider (IdP), who is the producer of assertions, and secondly, there is the Service Provider (SP) who consumes the assertions. IdeaScale uses SP-initiated SSO.
We recommend using a SAML tracer that will capture the SAML request and response. The tracer can be used for troubleshooting during set-up. To install SAML tracer click here and follow the directions.
-
Enable the setting and click ‘Add New’
2. Select SAML 2.0
3. On IdeaScale you will need to plug in the below data:
Display Name – name that will identify this SSO, can be anything (example: My companies SAML SSO)
SAML IdP Entity ID – this will most likely be a URL indicates that the content of the element is the identifier of an entity that provides SAML-based services (such as a SAML authority, requester, or responder) or is a participant in SAML profiles (such as a service provider supporting the browser SSO profile). It is available in IdP Metadata XML in entityID attribute of EntityDescriptor Tag.
SAML IdP Metadata --This is where you put in your providers Metadata. Generally, it can be accessed from a well-known URL for the IdP software or in IdP software admin/configuration section.
*Pro tip - look at the entity ID – this one needs to match our metadata’s ID
*We recommend always enabling the debugger tool which will be a useful tool for catching SSO issues.
Ensure you enable the ‘enabled’ toggle
4. On your database you will need to enter IdeaScale’s Metadata which can be found by clicking the link under type (see screenshot below). More information regarding IdeaScale's metadata can be found below.
a) You will also need to have the NameID
SAML General Settings:
Accessed by hitting 'Edit' on SSO configuration
-
IdP Login URL – your SSO login page that users will be redirected too
-
Logout Success URL - your SSO logout page that users will be redirected too
-
SSO Change Password URL – your SSO’s change password page
-
Change Password via popup (enable) – if you would like a popup to help users change their password
-
Blacklisted Email Domains – any email addresses (aka domains) that you do not want users logging in with (example – gmail).
Shibboleth
Shibboleth supports standard SAML 2.0 protocol. IdeaScale SAML support is built on SAML 2.0. Reference to protocol support for Shibboleth should be removed from IdP metadata XML to get IdeaScale SAML support working with Shibboleth IdP.
IdeaScale SP Metadata
The SP metadata has to be installed in IdP configurations. The method for configuring IdP may vary from different IdP software. The IdeaScale SP metadata can be accessed from
http://your-community.ideascale.com/a/saml/metadata
Some IdP may ask you to enter the metadata as XML and some may ask you to enter each field individually. All required fields are present in metadata XML. The fields present in the metadata XML are:
-
NameIDFormat accepted in preference order
-
AssertionConsumerService URL and Bindings
-
SingleLogoutService URL and Bindings.
-
Signing and Encryption Certificate in X.509 format, this certificate should be added to IdP trust store.
A valid IdP metadata is expected to provide following informations in XML:
a. EntityID: a unique entity ID for IdP, generally the base URL for IdP software
b. IDPSSODescriptor: this must support urn:oasis:names:tc:SAML:2.0:protocol
c. Signing and Encryption certificate in X.509 format. This certificate will be used to trust SAML messages originating from IdP software.
d. NameIDFormat list. Preferred NameID supported by IdeaScale is emailAddress ((urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)). IdeaScale also supports any persistent NameID that does not change between login.
e. SingleSignonService URL and Bindings, either or both of HTTP-Post and HTTP-Redirect must be present.
f. SingleLogoutServer URL and Bindings, both HTTP-Post and HTTP-Redirect Bindings supported
If a valid IdP metadata XML is not provided, the Single-Sign-On service will not operate correctly. The SingleLogoutService is optional.
UserID mapping
IdeaScale uses email address or any persistent NameID to map users from other security domain to IdeaScale communities. Its preferred that the email address is also passed along with NameID if NameID format is not email address. The email address can be passed in 2 ways:
1. Use email address as NameID, this works best
2. Add an AttributeStatement in SAML Response with Name/Friendly name as “mail”. The AttributeStatement should follow the AuthnStatement. Here is a XML snippet as example:
<saml:AttributeStatement>
<saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
Name="mail">
<saml:AttributeValue xsi:type="xs:string">[email protected] </saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
In case the email address is not passed along, users will be asked to provide it upon their first login. Though they have the option to not opt out for it by clicking on Skip.
Certificate & Trust
IdeaScale uses own certificate for signing and encrypting SAML messages. For incoming SAML messages from IdP the system checks the signing certificate provided in the IdP metadata XML in community setting and uses it as a trusted certificate.