What is SSO?

Single Sign On is a service that allows you to log in to Lumoa using your work email and directory. After SSO has been turned on, you will no longer need to invite people to join Lumoa. Assuming they are in your Azure Directory, they can navigate to the login page of Lumoa and immediately get access. This reduces manual invites and makes getting new users into Lumoa a faster, smoother process.

To get SSO up and running, you are required to go through an Installation process. After, we recommend that you set up Groups and Roles within your Azure Directory so that future users can have customer permissions. If you do not, all accounts in Lumoa will have the same roles and permissions.

Note: Completing the SSO installation does require a fee. Either before or after you take the steps outlined below, contact your CS manager for more information. If you are not sure of your CS manager, contact [email protected]

Installing SSO in your external systems

Installation for Microsoft Entra

1. Login to https://portal.azure.com with an account that has administrative rights

2. Search and open "App registrations" (part of Azure Active Directory)

3. Click "New registration", fill in the name (descriptive example: lumoa-nps-dashboard-prod) and set RedirectURI to "https://internal-api.lumoa.me/api/v1/sso/azuread" in the following form and press "Register":

4. When application is created in the Overview section write down TenantID and ApplicationID:

5. Open "Authentication" tab for the application and check "ID tokens" in "Implicit grants" section and click "Save":

6. Go to “Certificates & Secrets” and create a new client secret. Choose the longest expiration date that is available, ideally no expiration date:

7. Copy newly created client secret:

Installation for OKTA OIDC

Start by creating a new app integration in OKTA with the following settings:

A screenshot of a computer

Description automatically generated

Make sure the Grant type settings are as below:

Set the sign-in redirect URI to https://internal-api.lumoa.me/api/v1/sso/okta as seen below:

We also recommend that you enable the following settings:

And also:

After you have created the web app integration provide Lumoa with the client id, secret:

And company name:

Putting the SSO information into Lumoa

Once you have completed the above steps, you will need to go to your SSO page to input the information. The SSO page can be found from the link above, or by going to Settings-> SSO.

Note: For security reasons, the SSO page is hidden by default. If the above link does not take you to the SSO page, or if you cannot see the SSO page in the header like in the image above, please contact your CS manager or email [email protected].

The following info will need to be put into Lumoa.
1. TenantID
2. ApplicationID (also staging ApplicationID if relevant)
3. Client secret
4. what domains the SSO should include
  1. Right now Lumoa only accepts one domain through the UI. If you would like multiple domains, please email your CS manager or [email protected]
5. Create Users Automatically Toggle
  1. Tick this to have everyone associated with your Entra/Okta account to automatically get a Profile in Lumoa
  2. Leaving this unticked means people will only be given a profile after they manually login through the login page.

Note: After SSO is turned on, you no longer need to Invite people to join Lumoa. Simply have them access our Login Page, and after they input their email, they will be redirected if the SSO steps above were done correctly (and if the user exists within your Directory).

Creating Groups in Entra that map over to Lumoa

This next step is about defining roles in Lumoa. If you just completed the Installation steps above, then everyone who logs into Lumoa will have the same permissions and basic role of "User". Check out our list of roles and permissions for more info.

If you want some people to be added to Lumoa as "Admins", so that they can do things like upload data or manage settings, then you need to complete the below steps where you define SSO groups.

Note that any Groups created in your Azure Directory will map over to Lumoa. Meaning if you have a group in Entra called "Support Team" with 3 people in it, the same group will be created in Lumoa with the same 3 people. Additionally, if the group is updated in your Entra, Lumoa will reflect those changes.

This allows you to mange what your users can see and do within Lumoa directly through Entra. More information about Lumoa Groups can be found here.

To start, in your Azure portal, go to your Azure Active Directory. From the left menu select App registrations, search for the Lumoa application you have added and click on it.

In the left menu select App roles and click "Create app role" and create roles according to the below screenshot. The important column is value as these need to match so that roles are correctly mapped in Lumoa and allowed member types. Display name and descriptions are up to you have you want to name them.

Now if you don’t already have groups you want to use for Lumoa App roles, go to Azure Active Directory, select Groups from the left menu and create the groups you want by clicking New group. You can directly assign members or do that later.

Now go back to Azure Active Directory and select from the left menu Enterprise Applications. Search by the same application name as in App Registrations and click on it.

In the left menu you should now see the item Users and groups, click on it.

Click add user/group
First click on the "None Selected" under Users and groups, search for the user/group and click it. Remember to click "select" in the bottom of the screen. Next click "None Selected" under "Select a role" and select the role you want to assign this group. Remember again to click "select" in the bottom of the screen. After this click the "Assign" button in the bottom left.Note:

Note: After creating these roles, please check that in your API permissions there is the "openid" permission, and if not, please grant it (see image below):

Mapping the Group over to Lumoa

Assuming that you have a group created in Entra, you can map that Group over to Lumoa. The benefit of this is that anyone who joins Lumoa, now or in the future, will have the correct permissions without any input from you.

To start, find your Group in Entra. You will need to copy the OIDC value that is associated with each Entra Group, and paste it into an existing Lumoa Group. There is an official MS article on how to find and collect your OIDC, but the relevant bit is also below. Please consult the full Microsoft doc for more info:

Once you have your OIDC value, sign in to Lumoa, and then navigate to the Groups page. You will either need to edit an existing group, or create a new one, and add your OIDC value. There is a field at the bottom of the Groups popup where it can be added:

Note: The reason why you still need to have an existing Group in Lumoa is because you still need to define what collection permissions or Filters the people in this Lumoa Group should have access to. If you make a group in Entra for people who can look at data where "Country = Finland", then you need to have a group in Lumoa looking at "Country = Finland". Then, Entra will add people from the Entra Group to the Lumoa Group.

From there, thats it! Your Groups in Netra will map over to Lumoa. Let me give an example of how it works:

Lets say you make a group in Entra with "[email protected]" and "[email protected]", and you put that OIDC into a group in Lumoa. Bob already has Lumoa access, but Susan doesn't, and thats okay! Since they are both apart of the same group in Entra, when Susan gets invited to Lumoa, she will immediately be placed into the same Lumoa group as Bob!

Log out

Please note that Lumoa asks for refreshed user information every 10 minutes. If your Azure Directory (AD) recognize that the user is disabled or an admin revokes their access tokens, then the user is automatically logged out. This automatic log-out only applies to companies who have provided their Client Secret to Lumoa.

Get in touch

📧 Do you have any questions or comments about using Lumoa? Please don't hesitate to email Lumoa Support at [email protected].