Configuring OneLogin SSO

From Stellar Cyber v5.4.0, do not use the default Stellar Cyber integration application in OneLogin. Instead follow the steps below to create a new application.

If you already use OneLogin to manage access to other products in your organization, you can also configure it as the Identity Provider (IdP) for users accessing the Stellar Cyber Platform. Integrating Stellar Cyber with OneLogin lets you extend centralized user access control to Stellar Cyber through Single-Sign On (SSO) and SAML (Security Assertion Markup Language).

For information about authentication and authorization through SSO, see Integrating with an IdP.

Adding Stellar Cyber as a New Application in OneLogin

The setup of OneLogin to act as the IdP for Stellar Cyber users involves the addition of Stellar Cyber user accounts, creation of a Stellar Cyber application, and then the assignment of the application to the users.

Add Stellar Cyber User Accounts to OneLogin

You can import a set of users in bulk in a CSV file or add them individually. The following instructions are for adding an individual user whom you want to OneLogin to authenticate when the user attempts to log in to Stellar Cyber.

Log in to the OneLogin UI as a OneLogin administrator.
Select Administration | Users | Users | New User.

The New User configuration page appears.
Enter values for the First name, Last name, and Email, and then Save User.
When using a OneLogin SSO for both user authentication and authorization, select More Actions | Change Password, enter a default password, select Force user to update, and then Update.

When users first log in with the default password, they will be prompted to change it.
Select Save User to save the user configuration.
Repeat to add additional users.

Create a New Stellar Cyber Application in OneLogin

To add Stellar Cyber as a new application in OneLogin:

Select Administration | Applications | Applications | Add App.

The Find Applications page appears.
Search for SAML Test Connector (IdP) and choose it in the applications list.

The SAML Test Connector (IdP) application appears.
Change the name of the application (for example, “Stellar Cyber SSO”), optionally set rectangular and square icons and add a description, and then Save the application to create a new one.

Artwork for Stellar Cyber logos is available for download in the media kit.

After you Save the application with a new name, more options appear in the left menu.
Select Configuration and enter the following SAML (Security Assertion Markup Language) settings:

Audience: Also referred to as EntityID, this identifies the SP (Service Provider) for which SAML assertions are intended. For SSO (Single Sign-On) authentication of Stellar Cyber users, enter the IP address or FQDN of the Stellar Cyber Platform where users log in. It must be preceded by https://

For example, if the Stellar Cyber UI login is at 10.1.1.20, enter https://10.1.1.20

Recipient: This specifies the endpoint URL that processes SAML assertions. Enter the same Stellar Cyber IP address or FQDN as you did for Audience.

For example, enter https://10.1.1.20

ACS (Consumer) URL Validator: Also referred to as ACS URL Pattern, this validates the ACS (Assertion Consumer Service) URL to which OneLogin sends SAML responses and requires a regular expression pattern, using a backslash to escape the dots. The Stellar Cyber URL varies depending on whether it's for global SSO on the Stellar Cyber Platform or if it's for tenant SSO.

Global SSO example: https://10\.1\.1\.20/saml/login/callback

Tenant SSO example: https://10\.1\.1\.20/saml/login/callback/cust_id/<tenant-id>

ACS (Consumer) URL: This defines the SP endpoint (Stellar Cyber) that receives and processes SAML assertions.

Examples

Global SSO example: https://10\.1\.1\.20/saml/login/callback

Tenant SSO example: https://10\.1\.1\.20/saml/login/callback/cust_id/59125044
Save the configuration.
Select Parameters, leave the default setting Configured by admin selected, and select the Add ( + ) icon.
In the New Field dialog box that appears, enter the following attributes and then Save the configuration:

Field name: stellar_scope

Include in SAML assertion: (select)
After you save the configuration and the dialog box changes from “New Field” to “Edit Field stellar_scope”, leave the Value at its default setting of - No default - , and Save again.
Repeat the previous three steps to define the scope, role, and privilege for three other Stellar Cyber user types:

stellar_privilege

stellar_tenant

stellar_tenant_group

The first two attributes (stellar_cyber and stellar_privilege) are required for all users. The last two (stellar_tenant and stellar_tenant_group) are only required for users in a multi-tenant deployment.
Save the parameters.
Select SSO, leave the other settings as they are, set SAML Signature Algorithm as SHA-256, and then Save the SSO settings.
Copy details to use in the Stellar Cyber SSO (SAML) configuration later.

If you configure Stellar Cyber to use the OneLogin metadata URL, copy the Issuer URL.

When manually configuring Stellar Cyber to work with OneLogin, you will need the SAML 2.0 Endpoint (URL) displayed here and the X.509 certificate that you can see by selecting View Details for X.509 Certificate. Copy and paste them in a text editor now or return here to copy and paste them into the Stellar Cyber SSO (SAML) manual configuration later.

Assign the Application to the User

Assign the Stellar Cyber application to a user and set the user’s scope, role, and privileges.

Select Administration | Users | Users and then select one of the user accounts you previously added.
In the settings for this user, select Applications.
On the Applications tab, select the Add ( + ) icon.

The Assign new login to <username> dialog box appears.
Choose the Stellar Cyber application you just created—for example, Stellar Cyber SSO—and then select Continue.
Select Allow the user to sign in, enter values for the attributes you previously defined—for example, stellar_privilege = super_admin and stellar_scope = root—and then Save your changes.

By default, a root admin has access to “All Tenants”. You don’t need to set “All Tenants” as a value in the stellar_tenant field. For a partner, enter a tenant group, which provides access to all tenants in the group. For a user, specify a single tenant.

For information about user scope and privilege, see Integrating with an IdP.
Save User.

Configure Authentication in Stellar Cyber

With all your details collected, you are now ready to configure SSO Authentication in Stellar Cyber. The steps below are generally applicable for use for global configuration or per-tenant configuration.

Prepare for Users

For Authentication Only SSO: First, manually add all users on the Stellar Cyber Platform. After this manual entry, users can log in with SSO. Use the list of User Principal Names that you saved.
For Authentication & Authorization SSO: Configure all users through the IdP.

You enable SSO for all users except the root admin user. The root admin user must always use local authentication (https://your.stellar.cyber.address/login).
For Local access (bypass) when SSO is enabled: If Stellar Cyber loses connectivity with your IdP, users configured for SSO cannot log in. As a preventive bypass method, manually create a new user in the Stellar Cyber Platform with root scope and with a valid email address that has "+admin" appended to a valid user name, as follows: <user>+admin@yourorganization.com (joe+admin@yourorganization.com). The user you create must be able to receive a password reset email at <user>@yourorganization.com. This email alias is what Stellar Cyber uses to permit the bypass of an SSO for a local login. After you create this separate user account, the user can log in two ways:
- An SSO user with <user>@yourorganization.com
  
  or
- A local user at https://your.stellar.cyber.address/login using <user>+admin@yourorganization.com
If SSO is configured, it's recommended to keep an active administrative account in the Stellar Cyber user management.

Set up SSO

Log in to Stellar Cyber and select System | Settings.
In the Authentication Settings section, select SSO (SAML) as the Authentication Method.

Select Metadata URL or Manual Config:

If you select Metadata URL:

Issuer URL: Enter the Stellar Cyber URL.

Metadata URL: Paste the URL you copied from the IdP. The URL must begin with either https:// or http://. Different vendors use different names for the Metadata URL:

Identity Provider	Term for Metadata URL
Active Directory Federation Services	Federation Metadata URL
Microsoft Entra ID	App Federation Metadata URL
Okta	Metadata URL
OneLogin	Issuer URL
Rippling	Metadata URL

If you select Manual Config:

Issuer URL: Enter the Stellar Cyber URL.

Entry Point: Paste the entry point URL you copied from the IdP.

You must include http:// or https:// before the URLs. Different vendors use different names:

Identity Provider	Term for Entry Point URL
Active Directory Federation Services	SAML Endpoint
Microsoft Entra ID	Login URL or SAML-P Sign-on Endpoint
Okta	Sign on URL
OneLogin	SAML 2.0 Endpoint (HTTP)
Rippling	SAML 2.0 Endpoint (HTTP)

IDP Certificate: Upload the certificate file you downloaded from the IdP.

Select Allow Clock Skew to allow for system time differences between Stellar Cyber and your IdP. Authentication messages have an expiration. If the system times on Stellar Cyber and your IdP are not synchronized, the messages might expire before they even get to Stellar Cyber. The result is that users cannot log in, because they cannot authenticate.
Choose your IdP setting: Authentication Only or Authentication and Authorization. Note the following:
- A Global selection of Authentication and Authorization applies to all users (root, partner, and tenant), so the option to change authentication method for a specific tenant is not applicable when the Global method is set to Authentication and Authorization. You cannot log in to Tenant SSO when Global SSO is set to Authentication and Authorization. If you want to use SSO but also allow local users and tenant override, you must set the Global authentication method either to Local or to use the IdP with Authentication Only.
- Although you can customize SSO configuration on a per-tenant basis, the Authorization capability is only supported at the global level. Overrides you make at the tenant level are for Authentication only, so the toggle for Authentication and Authorization is not offered in the tenant editor.
- The root tenant must be configured to use either Default (same method as the Global authentication), or Local. It is not supported for configuration with an independent SSO.
- The authentication method for partners is the same as that for root users. Any authentication overrides for tenant-level users in a tenant group have no effect on the authentication method for the partners who manage the group.
- Choose Authentication Only for Stellar Cyber to authenticate users from your IdP, but manage scope and privilege locally. If you choose this, you must create the user in Stellar Cyber before adding them to your IdP.
- Choose Authentication and Authorization for Stellar Cyber to authenticate users from your IdP, along with their scope and level of privilege. You must configure authorization on your IdP before enabling this, otherwise users cannot log in. If you choose this, you do not need to create the user in Stellar Cyber. Stellar Cyber creates the user and assigns scope and privilege based on the information passed from the IdP.
  
  When Global Settings is configured for Authentication & Authorization, the option to Create new users manually is hidden because new users must come from the IdP source.
Choose a Two-Factor Authentication option that matches your IdP configuration:
- Off: If you choose this option, Stellar Cyber user accounts are not offered a 2FA option.
- Mandatory: If you choose this option, all users for every tenant are required to use 2FA when logging in to Stellar Cyber.
- Optional: If you choose this option:
  - The 2FA option can be customized for individual tenants under System | Tenants.
  - Individual users can choose to enable 2FA under their User Profile in the Stellar Cyber UI.
  - You can enforce 2FA for specific users under System | Users when adding or editing a user
  - The overall Global Settings for 2FA affect authentication for partners and tenant users. For example, if 2FA is Mandatory, all users must use 2FA.
  - Enabling 2FA here is independent of what you have configured on your SSO service. Enabling it here causes a separate 2FA prompt to be displayed upon logging in to Stellar Cyber.
  - The 2FA page from Stellar Cyber refers to use of Google Authenticator, but other authenticator applications also work.
Review your settings and then Submit them.