Articles in this section

See more

Configuring SAML For Lighthouse

Lachlan Archibald
  • Updated
Follow

SAML is the framework used to integrate applications with identity providers (IdP) for single sign-on (SSO). This is mostly (if not completely) reflected when a user logs in and authenticates with their IdP or is already logged in (if they have already authenticated with their identity provider prior to accessing Lighthouse).

Lighthouse supports the independent, concurrent use of both SAML and AAA authentication. SAML authentication is independent of, and does not interact with, other authentication methods.

Note: For release 21.Q4 SAML is only supported for authentication to the lighthouse Web GUI.

When SAML is configured and enabled, users can authenticate to the Lighthouse Web GUI either through SAML or another configured authentication mechanism such as Local or AAA. Users can SSH only via the other configured authentication mechanism (Local or AAA) if Remote Authentication is configured.

The default authentication is Local, with Lighthouse using locally defined users and groups. If AAA (TACACS, RADIUS or LDAP) Remote Authentication is configured, this will be used for Web GUI and SSH login authentication to Lighthouse (except for root which is always locally authenticated). Users are authenticated against AAA server(s) with group membership returned to Lighthouse, which is used to determine user roles and permissions. AAA Remote Authentication can support 2FA/MFA, depending on the AAA server capabilities.

Lighthouse supports SAML integration with the following identity providers:

  • OKTA
  • Azure Active Directory (Azure AD)
  • One Login

Before you begin

Note: The following variables are used in the SAML configuration instructions below. Please replace them with the correct values for your environment.

  • {main lighthouse address} - The address most users will use to connect to your primary Lighthouse web interface. e.g. lighthouse.example.com or 192.168.1.10
  • {provider} - Each IdP implements the specification slightly differently. Lighthouse needs to know which style to expect to handle these differences. If your IdP is not one of our official supported IdPs, try configuring Lighthouse using the generic provider option as the most widely applicable. You could also try using our other explicit IdP options, but these often expect provider-specific intricacies.

Please also review the limitations of the Lighthouse SAML SSO feature.

Generic IdP setup

Note: You must have your user groups setup in lighthouse prior creating & assigning them via the IdP. See the example in step 6 of the Okta configuration later in this topic.

Note: The {provider} in the steps must exactly match one of our provider strings e.g. generic, okta, azure_ad, onelogin.

  1. Create an application integration for “Lighthouse” in your IdP

  2. Set ACS or consumer URL as https://{main lighthouse address}/api/v3.7/sessions/saml/sso/{provider}

  3. Set the Allowed SSO URLs or Allowed redirect URLs or ACS URL Validator to include or match the /saml/sso/ URL for each address of each of your lighthouses that you want users to be able to login from.

    Example:

     https://{main lighthouse address}/api/v3.7/sessions/saml/sso/{provider}
 https://{main lighthouse IP address}/api/v3.7/sessions/saml/sso/{provider}
 https://{secondary lighthouse address}/api/v3.7/sessions/saml/sso/{provider}

    Depending on your IdP you may need to include the /saml/sp_init/ URLs.

     https://{main lighthouse address}/api/v3.7/sessions/saml/sso/{provider}
 https://{main lighthouse address}/api/v3.7/sessions/saml/sp_init/{provider}
 https://{main lighthouse IP address}/api/v3.7/sessions/saml/sso/{provider}
 https://{main lighthouse IP address}/api/v3.7/sessions/saml/sp_init/{provider}
 https://{secondary lighthouse address}/api/v3.7/sessions/saml/sso/{provider}
 https://{secondary lighthouse address}/api/v3.7/sessions/saml/sp_init/{provider}

  4. Set the Service Provider EntityID or Audience as lighthouse-{provider}

  5. If your service provider requires you to configure the Recipient

    • And only allows a single value
    • And you run multiple lighthouses or access lighthouse via multiple addresses
    • Then either:
      • Set the recipient as lighthouse-{provider} and use the onelogin option as your provider configuration.
      • Or if you only access each via a single address you could create a separate application integration per lighthouse.

  6. If your IdP has the option then set the initiator to the Service Provider

  7. Set your IdP to sign the Assertion for SAML.

Generic IdP SAML Attribute

You will also need to configure your IdP to send an additional attribute LH_Groups as part of the SAML response.

In most IdPs this is done by adding an Attribute Statement or Parameter configuration in your application integration. This parameter should be set as a multi-value parameter i.e. multiple values should be provided by multiple duplicative either Attribute Value tags or Attribute tags in the SAML assertion.

We recommend setting the value of this attribute to be populated with the names of the user’s Roles (or Groups) in your IdP. This method allows you to create roles in your IdP with the same names as the user groups on your lighthouse that can be assigned in your IdP to grant users that level of access to Lighthouse.

Alternatively, you can populate the LH_Groups attribute with the names of the Lighthouse user groups the user should be granted by any other mechanism that your IdP provides. e.g. custom user properties

Note: Your IdP can populate the LH_Groups attribute to place users in any Lighthouse user group except Lighthouse’s default admin group. You can allow users to login with admin privileges by simply creating another user group in Lighthouse with the admin role and assigning the matching role/group in your IdP to the user. i.e. populate LH_Groups to include its value.

Lighthouse Setup

You will need to export an IdP metadata XML file for your Lighthouse application integration from your IdP. If your IdP requires that requests be signed by the Service Provider then you will also need to provide an x509 certificate & private key in .pem format (either exported from your IdP or created locally then configured in your IdP).

  1. Upload your IdP metadata XML (and if required certificate & private key) to your primary Lighthouse e.g. via SCP
  2. Use the saml-idp-metadata command to configure each Lighthouse individually. Each Lighthouse is configured individually with the same or a different metadata XML (and certificate + key).

Note: The commands to configure each Lighthouse individually, all must be run from your primary Lighthouse instance.

# Example: Configuring a Multi-Instance Lighthouse for Okta IdP
# List initial lighthouse configurations (i.e. none)
saml-idp-metadata list
# Configure Primary lighthouse
saml-idp-metadata create \
--metadata metadata.xml \
--provider okta \
--lh-id 1
#Configure Secondary lighthouse
saml-idp-metadata create \
--metadata metadata.xml \
--provider okta \
--lh-id 2
# List lighthouse configurations (i.e. both lighthouses configured)
saml-idp-metadata list

Example 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 the addresses of your Lighthouse isntances 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: e.g. Lighthouse

    1. Click Next

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

    1. Tick both:
      1. Use this for Recipient URL and Destination URL
      2. Allow this app to request other SSO URLs
    2. Fill out the 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 Lighthouse instances.

    Example:

    https://{main lighthouse address}/api/v3.7/sessions/saml/sso/okta
https://{main lighthouse IP address}/api/v3.7/sessions/saml/sso/okta
https://{secondary lighthouse address}/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 Application username 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

In the Sign On tab for your Okta application, find the line:

Identity Provider metadata is available if this application supports dynamic configuration.

Open the link and save the page as an XML file (Recommended name: okta_metadata.xml). 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 Lighthouse instances to use your IdP e.g. 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

  1. 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) e.g. root Note: After this initial setup, you will be able to login as a SAML user.
    2. Create the User groups with the Roles and permission that you desire. See “10.1 Creating new users and groups templates” in the Lighthouse User manual.
  2. In Okta go to Directory > Groups
https://{main lighthouse address}/api/v3.7/sessions/saml/sso/okta
https://{main lighthouse IP address}/api/v3.7/sessions/saml/sso/okta
https://{secondary lighthouse address}/api/v3.7/sessions/saml/sso/okta
  1. Click Add Group
  2. Enter the Group name that matches a Group name on Lighthouse
  3. Open your new group
  4. Go to Manage Apps
  5. Search for your Lighthouse app and click Assign
  6. Click Done
  7. Go to Manage People
  8. 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

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

  2. Name your connector e.g. 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 regular expression that matches only all your Lighthouses’ SSO addresses (IP & DNS for primary & secondary Lighthouse instances).
      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$ For example, to allow Onelogin login for Lighthouse addresses 192.168.1.10 and lighthouse.example.com, use the following: ^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. Enable Include in SAML assertion
    4. Enable 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_.*`
    1. 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 Lighthouse instances to use your IdP. e.g. 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

If you do not already have your own user groups set up in lighthouse:

  1. Login to Lighthouse as a local user (or any non-SAML user) i.e. root Note: After this initial setup, you will be able to login as a SAML user.
  2. Create the user groups with the roles and permissions that you desire. See “8.2 Creating new groups and roles” in the Lighthouse User Manual.
  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. Save.
  5. Open your 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. Save.
  9. If you used a mapping then go to Users > Mappings and run Reapply All Mappings.

The assigned users are now able to login to lighthouse with the permission levels which that 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.

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 e.g. Lighthouse, then click Create
  7. Go to 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 instance that you want to be able to sign in on. i.e. IP addresses and DNS address for both your primary and secondary Lighthouse instances.
      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
      1. Set Sign on URL to https://{main lighthouse address}/api/v3.7/sessions/saml/sp_init/azure_ad
      2. Click Save
  1. Edit Attributes & Claims
    1. Remove the default claims from Additional claims.
    2. Click Add new claim and Enter:
      1. Name: LH_Groups
      2. Source Attributes: user.assignedroles

IdP Metadata

  1. Go to Azure Active Directory
  2. Go to Enterprise applications and open your application
  3. Go to Single sign-on
  4. In 3. SAML Signing Certificate 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 Lighthouse instances to use your IdP e.g. 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

Note: If you do not already have your own user groups set up in Lighthouse: 1. Login to Lighthouse as a local user (or any non-SAML user) e.g. root Note: After this initial setup, you will be able to login as a SAML user. 2. Create the user groups with the roles and permission that you desire. See “8.2 Creating new groups and roles” in the Lighthouse User Manual.

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 user group on Lighthouse.
    2. Set Allowed member types to Both (Users/Groups + Applications).
    3. Set the other fields as you desire.
  6. Go to Azure Active Directory
  7. Go to Enterprise applications
  8. Open your App
  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.

Limitations

IdP metadata certificate expiry

The IdP metadata XML file that you export to configure Lighthouse contains a certificate that is used to authenticate that SAML response came from your IdP. Different IdPs have different expiry periods for these certificates, consult your IdP’s documentation to find their expiry period. When your IdP’s certificate expires you will need to regenerate it then re-export your IdP metadata and update your lighthouse configurations. If your IdP supports sending expiry notifications to your admin, we recommend you enable these notifications.

User Permissions Changes

When you change the permissions assigned to a lighthouse user in your IdP (via LH_Groups SAML attribute), the changes will not take effect until the user logs out and back into lighthouse.

If you need to quickly restrict a user’s access, consider altering the permissions of or deleting that user’s user groups on Lighthouse. See Lighthouse user manual “8.3 Modifying existing groups”. You can also set a low Web Session Timeout. See Lighthouse user manual “5.9 Examine or modify Lighthouse Session Settings”.

SAML SSO Usergroups

The LH_Groups attribute can be used to place SSO users in any Lighthouse user group except Lighthouse’s default admin group. You can allow users to login with admin privileges by simply creating another user group in Lighthouse with the admin role and assigning the matching role/group in your IdP to the user. i.e. populate LH_Groups to include its value

SAML SSO Users

SAML Users can only be managed in your IdP and will not appear under Lighthouse User Management.

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk