Skip to main content
This page explains how to put Lumos behind a single login, either Google or Microsoft login or SAML SSO through your identity provider (IdP). For how SAML login works once it is in place, see Logging into Lumos with SAML SSO.

Choose a login provider

Lumos only supports logins through SSO. You choose which providers your employees can use in the “Login Providers” section of Settings → Source of Truth. How the options combine:
  • “Identity Provider” cannot be selected together with “Google” or “Microsoft”.
  • “Google” and “Microsoft” can both be selected. Employees then see both options on the login page.
  • If no option has been saved, Lumos accepts Google and Microsoft logins.
Saving “Identity Provider” turns off Google and Microsoft logins right away, and Lumos accepts SAML logins only after it is saved. You can’t test a SAML login before you switch, so tell Lumos Support when you plan to switch so they can help if the first SAML login fails.

Before you start

  • You need the Organization Admin role in Lumos to change login providers. See Lumos Roles.
  • For SAML, you need admin access to your IdP to create an application and assign users to it.
  • Lumos Support provides the SAML values for your IdP app, such as the ACS URL and SP Entity ID. These values are not self-service. Request them at support@lumos.com.
  • Your email domain must be bound to your Lumos tenant. Lumos Support handles this.
  • Each person who logs in must be an active user in Lumos with access to Lumos. Lumos matches a SAML login to that user by the email in the SAML response, or by the id attribute against the user’s account in your source of truth.

Set up SAML SSO

Every SAML IdP follows the same overall flow. The sections below give the field names for each IdP.
  1. Request the SAML configuration values for your IdP from Lumos Support.
  2. Create a SAML application for Lumos in your IdP and enter the values from Lumos Support.
  3. Map the id, email, firstName, and lastName attributes.
  4. Assign the users or groups that should be able to log into Lumos.
  5. Send your IdP’s metadata (a metadata URL or an XML file) to Lumos Support.
  6. After Lumos Support confirms the connection, tell them when you plan to switch over.
  7. Go to Settings → Source of Truth. Under “Login Providers”, clear “Google” and “Microsoft”, select “Identity Provider”, and click “Save”.
  8. Log in from your IdP’s Lumos tile and from the Lumos login page to confirm SAML works. If it doesn’t, contact Lumos Support at support@lumos.com.
A Lumos logo is available if you want to add one to the app in your IdP.
Lumos logo

Okta

  1. Log in to Okta, open the admin dashboard, and select “Applications”.
  2. Create a new SAML 2.0 application for Lumos.
  3. Request the Single sign on URL (ACS URL) and Audience URI (SP Entity ID) from Lumos Support.
  4. Enter both values in the SAML settings of the app, then add these attribute statements.
  5. Complete the remaining form (its content does not matter) and click “Finish”.
  6. On the “Assignments” tab, click “Assign to People” or “Assign to Groups” and assign the users who should log into Lumos.
  7. On the “Sign On” tab, copy the Metadata URL and send it to Lumos Support.
  8. After Lumos Support confirms the connection, switch over as described in steps 6 to 8 of the overall flow.
To manage Lumos roles from Okta group membership, add a roles attribute statement. See How to use SAML to configure Lumos user roles.

JumpCloud

  1. Log in to the JumpCloud Admin console.
  2. Create a custom SAML app for Lumos. See JumpCloud’s guide, SSO using Custom SAML Application Connectors.
  3. Request the Single sign on URL (ACS URL) and Audience URI (SP Entity ID) from Lumos Support.
  4. In the app’s “Single Sign-On Configuration” section, enter the ACS URL in “ACS URL”. Enter the SP Entity ID in both “IdP Entity ID” and “SP Entity ID”, then save.
  5. Add these attribute mappings.
  6. On the “SSO” tab, select “Sign Assertion” and click “Save”.
  7. On the “SSO” tab, select “Declare Redirect Endpoint”.
  8. Under “JumpCloud Metadata” on the “SSO” tab, click “Export Metadata” and send the downloaded XML file to Lumos Support.
  9. Assign users to the Lumos app. See JumpCloud’s guide, Authorize Users to an SSO Application.
  10. After Lumos Support confirms the connection, switch over as described in steps 6 to 8 of the overall flow.
A JumpCloud misconfiguration to watch for is entering the SP Entity ID in only one field. It must go in both “IdP Entity ID” and “SP Entity ID”.

OneLogin

  1. Request the ACS URL for your OneLogin custom SAML app from Lumos Support.
  2. In the OneLogin admin dashboard, select “Applications” and create a custom SAML application for Lumos.
  3. Fill in the app configuration fields.
  4. Add these attribute mappings and select “Include in SAML assertion” for each one.
  5. Select “SSO” in the left navigation, open the “More Actions” menu, and click “SAML Metadata”. Send the downloaded XML file to Lumos Support.
  6. Assign users to the Lumos application in OneLogin.
  7. After Lumos Support confirms the connection, switch over as described in steps 6 to 8 of the overall flow.

Microsoft Entra ID

Microsoft Entra ID customers can use the “Microsoft” login provider, which needs no SAML app. Employees log in with their Microsoft work accounts. If you need SAML SSO through Microsoft Entra ID instead, follow the overall SAML flow above with the values Lumos Support sends you.

Google Workspace

Google Workspace customers can use the “Google” login provider, which needs no SAML app. Employees log in with their Google Workspace accounts.

BambooHR and other SAML identity providers

Lumos supports SAML SSO through other IdPs, including BambooHR. Follow the overall SAML flow above. In your IdP, create a SAML application, enter the values from Lumos Support, and send the id, email, firstName, and lastName attributes.

Troubleshooting

Employees can no longer log in with Google or Microsoft. “Identity Provider” is selected under “Login Providers”, which turns those options off. If SAML logins aren’t working yet and no admin can log in, contact Lumos Support at support@lumos.com. If your tenant allows Lumos Support access, Lumos Support can change the login provider back so your admins can log in. An Organization Admin who can still log in can also switch back. Clear “Identity Provider”, select “Google” or “Microsoft”, and click “Save”. SAML login succeeds in the IdP but Lumos does not log the user in. Lumos matches the login to an active Lumos user by the email in the SAML response, or by the id attribute against the user’s account in your source of truth. Check these things:
  • “Identity Provider” is saved under “Login Providers”. Until it is, Lumos refuses SAML logins.
  • The user is active in Lumos and has access to Lumos.
  • The IdP sends the user’s work email in the email attribute and a stable id.
  • Your email domain is bound to your tenant.
Users lose their Lumos roles, or can’t log in, after you add a roles attribute. When your IdP app sends a roles attribute, Lumos overwrites each user’s roles with it on every login. The value must be a comma-separated list that includes USER, and a login whose roles value leaves out USER fails. See How to use SAML to configure Lumos user roles.