Examples of Specific IdP Setups

The following are examples of how you could configure officially supported IdPs. They are based on the above generic step and the IdP’s configuration options as of 10/2021.

Okta

Create an Application

You need to create an application that Okta will be doing authentication on behalf of.

Note:You’ll need to know what the addresses of your Lighthouses before creating the application.

1. In the Okta web console go to Applications - > Applications

   1. Click Create App Integration

   2. Select SAML 2.0

2. Give the application a name: for example, Lighthouse and click Next

3. For the Single sign on URL enter
   https://{main lighthouse address}/api/v3.7/sessions/saml/sso/okta

   1. Select:

      1. Use this for Recipient URL and Destination URL

   2. Fill out the Other Requestable SSO URLs with the SSO URLs for every lighthouse address you want to be able to sign in with. i.e. IP addresses and DNS address for both your primary and secondary lighthouses.

      
      Example:

      https://{main lighthouse ip}/api/v3.7/sessions/saml/sso/okta
      https://{dependent lighthouse address}/api/v3.7/sessions/saml/sso/okta
      https://{dependent lighthouse ip}/api/v3.7/sessions/saml/sso/okta

       

4. For the Audience URI (SP Entity ID) enter lighthouse-okta

5. Set Name ID format to email.

6. Set to email.

7. There are many ways you could configure Okta to populate the LH_Groups attribute, our recommended way is to populate it from and manage it via the user’s Okta groups:

   1. Add a Group Attribute Statement

      1. Name: LH_Groups

      2. Name Format: Basic

      3. Filter: Matches Regex .*

8. Click Next and finish.

IdP Metadata

1. Open your Onelogin application.

2. Go to More Actions > SAML Metadata. This is the metadata xml file that you will need to configure lighthouse.

Configure Lighthouse

1. Copy the Identity Provider metadata XML to your primary lighthouse.

2. Using saml-idp-metadata on your primary lighthouse, configure each of your lighthouses to use your IdP

For example:

saml-idp-metadata -p {root password} create -m /path/to/okta_metadata.xml -P okta -n "My Okta display name" -l {LH id number}

Groups setup

After this initial setup, you will be able to login as a SAML user.

If you do not already have your own User groups setup in lighthouse:

1. Login to Lighthouse as a local user (or any non-SAML user) i.e. root

2. Create the User groups with the Roles and permission that you desire. See “Creating new user and group templates”.

3. In Okta go to Directory > Groups.

4. Click Add Group.

5. Enter the Group name that matches a Group name on lighthouse.

6. Open your new group.

7. Go to Manage Apps.

8. Search for your lighthouse app and click Assign.

9. Click Done.

10. Go to Manage People

11. Search for and click on the users you wish to add to the group.

The assigned users are now able to login to lighthouse with the permission levels which that group grants them.

Onelogin

Create an Application. You need to create an application that Onelogin will be doing authentication on behalf of.

1. Go to Applications > Add App > Search for and choose SAML Custom Connector (Advanced)

2. Name your connector, that is, Lighthouse.

3. In the Configuration tab for your new app

   1. Set Audience (EntityID) to lighthouse-onelogin

   2. Set Recipient to lighthouse-onelogin

   3. Set ACS (Consumer) URL to: https://{main lighthouse address}/api/v3.7/sessions/saml/sso/onelogin

   4. Set ACS (Consumer) URL Validator to a regex expression that matches only all your lighthouses' SSO addresses (IP & DNS for Primary & Secondary lighthouses).

      1. Ensure it begins with ^ and ends with $ to match the whole url.

      2. Recommended pattern:
         ^https:\/\/ {lighthouse addresses} \/api\/v3\.7\/sessions\/saml\/sso\/onelogin$

      3. For example to allow Onelogin login for lighthouse addresses 192.168.1.10 and lighthouse.example.com , you could use the following: (note the additional () around your hostnames and the | separating them.

^https:\/\/(192\.168\.1\.10|lighthouse\.example\.com)\/api\/v3\.7\/sessions\/saml\/sso\/onelogin$

   5. Set Login URL to
      https://{main lighthouse address}/api/v3.7/sessions/saml/sp_init/onelogin

   6. Set SAML initiator to Service Provider

   7. Set SAML signature element to Assertion

4. The recommended method to populate LH_Groups is with Onelogin Roles.

   1. Go to Parameters then click Add.

   2. Set Field Name to LH_Groups

   3. Check Include in SAML assertion

   4. Check Multi-value parameter

   5. Click Save.

   6. Set Default value to User Roles

   7. If you intend on filtering the Roles that are sent to lighthouse (using a Rule) set no transform otherwise set semicolon delimited.

   • An example Rule to filter roles:

   • “Set LH_Groups in”

   • for each role

     • with a value that matches LH_.*

   8. Save the parameter.

5. Save the connector.

IdP Metadata

1. Open your Onelogin application.

2. Go to More Actions > SAML Metadata. This is the metadata xml file that you will need to configure lighthouse.

Configure Lighthouse

1. Copy the metadata xml to your primary lighthouse.

2. Using saml-idp-metadata on your primary lighthouse, configure each of your lighthouses to use your IdP., For example
   saml-idp-metadata -p {root password} create -m /path/to/metadata.xml -P onelogin -n "My Onelogin display name" -l {LH id number}

Roles Setup

After this initial setup, you will be able to login as a SAML user.

If you do not already have your own Usergroups setup in lighthouse:

1. Login to Lighthouse as a local user (or any non-SAML user) for example, root.

2. Create the Usergroups with the Roles and permission that you desire. See Creating New Groups and Roles.

3. In Onelogin Go to Users > Roles

4. Click New Role.

   1. Set the Role’s name to match the lighthouse group you want it to map to.

   2. Select your Lighthouse app to associate the role with.

   3. Click Save.

5. Open the newly created role.

6. Go to the Users tab on the left.

7. Search for and add your users or create a mapping to automatically add multiple users.

8. Click Save.

   1. If you used a mapping then go to Users > Mappings and run Reapply All Mappings.

9. Click Done

The assigned users are now able to login to lighthouse with the permission levels that the Onelogin Role/Lighthouse group grants them.

Azure Active Directory

Lighthouse can be added as an Enterprise application to Azure Active Directory. This example uses “App roles” to grant users permissions.

To create an Application (Enterprise applications)

1. Go to Azure Active Directory.

2. Go to Enterprise applications.

3. Click New Application.

4. Click Create your own application.

5. Select Integrate any other application you don't find in the gallery (Non-gallery).

6. Name your Application, for example, Lighthouse, then click Create.

7. Click Properties

   1. Set Assignment required to Yes.

   2. Set Enabled for users to sign-in to Yes.

   3. Click Save.

8. Go to Single sign-on

   1. Select SAML

   2. Edit Basic Configuration

      1. Add an Entity Id lighthouse-azure_ad and set it as default.

      2. In Reply URL (Assertion Consumer Service URL) add the SSO URL for each address of each lighthouse that you want to be able to sign in on. i.e. IP addresses and DNS address for both your primary and secondary lighthouses.
         https://{primary lighthouse address}/api/v3.7/sessions/saml/sso/azure_ad https://{primary lighthouse IP address}/api/v3.7/sessions/saml/sso/azure_ad https://{secondary lighthouse address}/api/v3.7/sessions/saml/sso/azure_ad https://{secondary lighthouse IP address}/api/v3.7/sessions/saml/sso/azure_ad
         

      3. Set Sign on URL to https://{main lighthouse address}/api/v3.7/sessions/saml/sp_init/azure_ad

      4. Click Save.

   3. Edit Attributes & Claims

      1. Remove the default claims from Additional claims.

      2. Click Add new claim and Enter:

         • Name: LH_Groups

         • Source Attributes: user.assignedroles

IdP Metadata

1. Go to the Azure Active Directory.

2. Go to Enterprise applications and open your application.

3. Go to Single sign-on.

4. Navigate to 3. SAML Signing Certificate and find and download Federation Metadata XML.

Configure Lighthouse

1. Copy the Federation metadata XML to your primary lighthouse.

2. Using saml-idp-metadata on your primary lighthouse, configure each of your lighthouses to use your IdP as follows:
   For example, saml-idp-metadata -p {root password} create -m /path/to/metadata.xml -P azure_ad -n "My Azure display name" -l {LH id number}

App Roles Setup

After this initial setup, you will be able to login as a SAML user. If you do not already have your own Usergroups setup in Lighthouse, you can set them up as follows:

1. Login to Lighthouse as a local user (or any non-SAML user) i.e. root

2. Create the Usergroups with the Roles and permission required. See Creating New Groups and Roles.

See Add app roles and get them from a token - Microsoft identity platform for up to date documentation on how to create and assign App Roles.

1. Go to Azure Active Directory.

2. Go to App registrations.

3. Open your app (Use the All Applications tab to see Enterprise apps).

4. Go to App Roles.

5. Click Create App Role.

   1. Set the value to match your usergroup on Lighthouse.

   2. Set Allowed member types to Both (Users/Groups + Applications).

   3. Set the other fields as required.

6. Go to Azure Active Directory.

7. Go to Enterprise applications.

8. Open your App, that is, Lighthouse.

9. Go to Users and groups.

10. Click Add user/group.

11. Select a user and one of your App roles then click Assign.

The assigned users are now able to login to lighthouse with the permission levels which that App Role/Lighthouse group grants them.