Portal Setup
SSO - Portal Setup & Login
Last updated
SSO - Portal Setup & Login
Last updated
Upon setting up the IdP to use the BlueFletch Portal as a SAML SSO app, retrieve:
Federation Metadata XML (see example at the bottom of the page)
or all of the following:
Certificate in Base64
Login URL
Azure AD Identifier
In the BlueFletch Portal, select the Admin tab, which opens to the Organization sub-tab by default.
Select SSO Config and click + Add Configuration.
In Domain field, type the company email domain that all users' email addresses will use (for example, corporate.com). The fields Name and Provider Id will auto-populate their respective details. ACS URL (Callback URL) is auto-filled by BlueFletch for all configs.
Enter the value of entityID for IDP Entity Id, Location for SSO URL, and X509Certificate for Certificate. These values can be found in the metadata XML (example below). Note: when including the certificate contents, enclose within -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- tags.
Enter SP Entity Id; it is the same as the auto-populated Provider Id (saml.domain_name).
Click Save to save changes to the SSO configuration.
Optional setting that dynamically assigns BlueFletch Portal roles to users on first login based on their IdP groups.
Click Define IdP Group Mappings to associate an IdP user group with a role in the BlueFletch Portal; otherwise, all new SSO users will be assigned the "User" role by default.
Click Add New Row to add a new group-role mapping.
Enter an IdP group in the Group field (defining a group as "*" will apply a role to all users).
Select a Portal role from the Roles dropdown. For more information on Portal roles, see the Roles documentation).
Additional group-role mappings can be added by clicking Add New Row.
Click Update Groups to save group-role mappings.
Click Save to save changes to the SSO configuration.
The BlueFletch Portal has the capability to recognize a store/site location associated with a Portal user's session token. This, combined with the Portal's role-based dashboard assignment, opens up a lot of options for utilizing automatic site-assignment in the Portal.
For example:
Restricting user roles that do not have the Support Site Filter Manage permission (ability to edit site filters) to only see the site(s) assigned to them in the IdP or directory service and associated with their session token.
Automatically displaying for users with specific roles only their sites and only in the dashboards that have been allowed for their role.
Showing regional admin users that do have the Support Site Filter Manage permission their assigned sites automatically on login, but allowing them the flexibility to edit the filters to view other sites' devices.
The Portal is checking if there is an attribute "SiteId" (case-sensitive) coming in with the token when it receives from the IdP. All that is needed on the customer's side to integrate with this feature in the Portal is to add a "SiteId" attribute to their token that is associated with one or more numeric site IDs (i.e. IDs found in their sitelist.csv file) per user in their IdP or directory service.
On the login page, enter email address with company-owned domain. Press Continue.
Page will redirect to the associated IdP's login prompt (for example, Azure in the screenshot).
Enter login credentials and submit.
Page will redirect to the BlueFletch Portal's loading screen before opening the organization's main dashboard with the user logged in with their group-mapped permissions.
User cannot login with SSO because they do not have groups assigned Upon redirecting from the IdP to the BlueFletch Portal, the user receives the error message, "You do not have proper privileges for this organization."
Check that the IdP has groups assigned, and that the variable in the IdP is named "Groups" (with a capital "G" - the Portal only recognizes the variable if correctly capitalized).
Check that all IdP groups referenced in the Portal SSO Configuration match the user's groups and are spelled correctly in the Portal.
Email address is not already associated with IdP credentials The user enters email address with a company domain. The page redirects to the IdP's login prompt, but the user has no credentials for this IdP.
This user has not been set up by the IdP administrator yet.
Contact IdP administrator to create an account associated with the user's company-domain email address.
SSO account is linked to Google Workspace and user is currently logged into a different Google account The user receives a 403 error, "Error: app_not_configured_for_user," while attempting to login to the BlueFletch Portal.
If the company uses an SSO authentication through Google Workspace, the account must be currently logged in.
If no Google account is logged in, user will simply be prompted to indicate their account and login.
If user is not logged into the SSO account but is logged into another Google-linked account, the user will get a 403 error when logging into the BlueFletch Portal. The user must login to the account through Google.
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="http://www.idp.com/efgxxx1234xx5">
<md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.example.com/2000/09/xml#">
<ds:X509Data>
<ds:X509Certificate>MIIDpDCCAoygAwIBAgIGAYJL6BGHMA0GCSqGSIb3DQEBXXXXXXXXXXXXxxXXXxGEwJVUzETMBEG A1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU MBIGA1UECwwLU1NPUHJvdmlkZXIxEzARBgNVBAMMCmRldi0xOTk5OTcxHDAaBgkqhkiG9w0BCQEW DWluZm9Ab2t0YS5jb20wHhcNMjIwNzI5MjE0MDE2WhcNMzIwNzI5MjE0MTE2WjCBkjELMAkGA1UE BhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xDTALBgNV BAoMBE9rdGExFDASBgNVBAsMC1NTT1Byb3ZpZGVyMRMwEQYDVQQDDApkZXYtMTk5OTk3MRwwGgYJ KoZIhvcNAQkBFg1pbmZvQG9rdGEuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA 3+1WLQ5h4iHN1iWL02g4ddhcry3mNRsoyLTA/Ku7toJD1oaFEr557mAbDS9M85810RQHxsVqErNd JapFM5EemqDSYi34ucIX/qX4uxohjC1NEhQX8iTLX0FzVo16hh82KIPTX5F1yzFIrp1UBdLeEtVO KZs0NlBbjwR8DJ71111111111111111111ZWXwJpIuzw9DywRUrm//ai7pjZifVZ+xAZHl8qp/qY JpK+Hs/hlt8JXcRnjhgODsjo42dIuT6QzwA0iJnfnQqu227dPrDSgQPIXSA+fHjBSv1TfyqWR5Hk 8eGjSC+L1J4mQzK0AiJc2DQnT6YtA+deq7t0wwIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQDK1Avh DUsTBJrP80ocnI/0Zz6jRteYRtFrhFEQ7mPMO8hysx/Q55Z2Hq4a7voLX6FTPItbBQvT22RQrF5E hj80RiEuIffoD5Su+aRL3nZLEF6A0JIZBOAAgDX7XDAp6LnJcEkkxwtfsj+vkHgy8yDnXB51Yxko DRSL6OLH2Ch1bQ1v5cc2LgdY3387iMKLuUeCCYEH7rJvqIYI0ZNDlCuFY27u4GlTrsbdVTtjE1EL TT2KxotQSGQ/p7jGQN3V6YgdhBmBup10/FAd7B95QYBYOBDbQXfUCYsu+Bbb7MrT5OimzS+n+z6/ q1+AKolYFDP29E+daGYbdOahpa/teCrH</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://idp-123.com/app/idp-123_emsportal_1/efgxxx1234xx5/sso/saml"/>
<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp-123.com/app/idp-123_emsportal_1/efgxxx1234xx5/sso/saml"/>
</md:IDPSSODescriptor>
</md:EntityDescriptor>Apply the following values from the XML in the SSO settings within Portal:
entityID -> IDP Entity ID
e.g. http://www.idp.com/efgxxx1234xx5
X509Certificate -> Certificate
e.g. MIIDp...pa/teCrH is included as
-----BEGIN CERTIFICATE-----MIIDp...pa/teCrH-----END CERTIFICATE-----
HTTP-POST Location -> SSO URL
e.g. https://idp-123.com/app/idp-123_emsportal_1/efgxxx1234xx5/sso/saml
