SAML-Based Login Settings

Use SAML-based login to enable login using your existing enterprise identity provider, such as Okta or Microsoft Active Directory (AD).

Configuring General SAML-Based Login Parameters

These parameters apply to all SAML logins and only need to be entered once.

• Under the SAML-Based Login Settings section, toggle on Allow SAML-Based Logins.
• Restrict to SAML login only - To allow only SAML-based logins. Manual login is disabled.
• Logout from SAML provider on logout from Axonius - To log out from the SAML provider when the user logs out from Axoninus.
• Axonius external URL - This is optional. Used to access Axonius from an external URL. If the communication to Axonius is being proxied, then this should be the external domain, i.e., the proxy domain.
• Ignore user name case when logging in - When selected, the case of the user name will be ignored. This prevents a new Axonius account being created when a user connects with the same user name but is cased differently. For example: example@demo.com and eXamPle@Demo.com. In this case, a new account will not be created.

Configuring a SAML Identity Provider

To configure a SAML identity provider, use the configuration sections below. Not all configurations require all the sections to be configured.

Configuring a SAML Instance

Use the following steps to configure a SAML provider instance. This section is required for all SAML instances.

To configure a SAML instance:

1. Configure the following settings for each SAML provider. See Using Multiple SAML Providers.

• Name of the identity provider (required) - If your identity provider supports metadata URL parsing, you can use the link to automatically fill in some details. If it doesn't, fill them manually in the Name of the identity provider field. Note that the name of the identity provider can be any string you like; It is used only to identify the identity provider within Axonius.
• Unique name of IDP (required) - A unique name for the identity provider that cannot be changed after it is saved. This name must be added to the SSO provider when creating the connection. The IDP name:
  • Cannot contain spaces, hyphens, or a long word.
  • Must be 10 characters or fewer and may contain numbers.
    • Examples: AxSSO00001, AxLogin001, AxAzure001

• Automatically redirect all logins to the identity provider - Select whether to automatically redirect all users to the configured SAML identity provider.
  • When this is enabled, any user who tries to log in to Axonius will be automatically redirected to the configured SAML identity provider.
    • To access the Axonius login page without being redirected, use the following URL: https://[Axonius host name / IP address]/?redirect=false
  • When this is disabled, any user who tries to log in to Axonius will need to manually click the 'Login with SAML' option to login with the configured SAML identity provider.
• Metadata URL (optional) - A one-time URL that can be used in Axonius to fill in all the other details. If your identity provider supports this, then you can use this and skip putting all the other settings manually.

• Do not send AuthnContextClassRef - (Applies to: Microsoft Active Directory and Microsoft EntraID) The SAML AuthNRequest will not include the AuthnContextClassRef SAML attribute:
  <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport<</saml:AuthnContextClassRef>>

2. In the identity provider console, define the credentials and SAML settings. These settings provide the values listed below used to enable SAML authentication in Axonius:

When creating multiple SSO connections, you must append ?IDP=xxx to all URLs in the table below.

Service Provider Signing Configuration

Configuring service provider signing is optional. You need a private key file and a certificate file saved on your system before performing this configuration.

To configure service provider signing:

• Click Enable Service Provider signing and fill in the following details:
  • Enable AuthnRequestsSigned - When selected, the service provider will sign authentication requests that it sends to the IdP.
  • Enable WantAssertionsSigned - When selected, the IdP wants the authentication requests it receives from the service provider to be signed.
  • Signing Private Key (.key, required) - Click Upload File to upload the private key file.
  • Signing Certificate (.crt, required) - Click Upload File to upload the certificate file.

Configure SAML Session Reauthentication

Configuring reauthentication is optional. When configured, users will be required to reauthenticate according to the timeout.

To configure session reauthentication:

• Cick Enable SAML session reauthentication and enter the Reauthentication timeout claim key as it is configured in IdP on the identity provider side, such as Okta or Azure.
  When the timeout is reached, the Login box is displayed and the user must reauthenticate.

SAML User Parameters Mapping

When using SAML, Axonius uses your SAML parameters to identify users and assign roles to them.

Axonius requires the following attributes to be sent by the provider. You can map the terms your SAML uses to Axonius. If you do not map user parameters, Axonius will use the default parameters sent by your provider.

1. User name (optional, default: empty) - The ID of the user in that identity provider. For example, in Active Directory or Azure Active Directory, this is the user principal name. If you do not fill in a value, the system uses the default from the identity provider.
2. First name (optional, default: empty) - The given/first name of the user. If you do not fill in a value, the system uses the 'givenname' value.
3. Last name (optional, default: empty) - The surname of the user. If you do not fill in a value, the system uses the 'surname' value.
4. Email (optional, default: empty) - The email address of the user. If you do not fill in a value, the system uses the 'emailaddress' value.
5. Department (optional, default: empty) - The department of the user. If you do not fill in a value, the system uses the 'department' value.
6. Job Title (optional, default: empty) - The job title of the user. If you do not fill in a value, the system uses the 'title' value.

Passing User Group Membership from Okta to Axonius with SAML

By default, group membership is not passed from Okta to an Axonius instance with SAML login. Custom Group Attributes need to be set in Okta. in order to pass user role assignments. They enable values such as group assignments, email addresses, and other values to be passed. See How to pass a user's group membership in a SAML Assertion from Okta for more about passing a user's group membership with SAML.

SAML - User Assignment Settings

User assignment settings are used to configure the access level assigned to each user when logging in with SAML.

The following settings are available:

1. Default role for new SAML user only (if no matching assignment rule found) (Required, default: No Access) - The default role that will be associated with new SAML users. For details on managing user roles in Axonius, see Manage Roles.
2. Default data scope for new SAML user only (if no matching assignment rule found) (optional, Default: Global (Unrestricted)) - Select the Data Scope to assign to new users. For details about Data Scopes, see Managing Data Scopes.
3. Evaluate role assignment on (required, default: New users only) - Select whether to evaluate role assignment for new users or for new and existing users.
   • If New users only is selected, role assignment will be evaluated only for new users. The role for existing Axonius users will not be reevaluated and will remain as is.
   • If New and existing users is selected, role assignment will be evaluated for new users and also for existing users on every login.
4. User Assignment Rules (users will be assigned to the first matching role) (optional) - Configure a ranked list of rules to determine the user's role.
   • Each role consists of key/value pairs (case sensitive exact match) and the role to be assigned.
   • To reorder the rules, hover over the rule to use the drag and drop functionality.
   • When a user logs in to Axonius with SAML, the user's assigned role is determined based on the Role Assignment Rules Logic.

SAML Advanced Settings

The following advanced settings are available:

Using ADFS Compatible URLs

• Create ADFS compatible URLs - When using ADFS SAML authentication, select Create ADFS compatible URLs to have Axonius create and use ADFS compatible URLs.

Using SAML Credentials to Create Dynamic Data Scopes

Use Dynamic Data Scopes to allow users to log in without manually creating a Data Scope for each situation. When using an identity provider, Data Scopes can be assigned to users dynamically when they log in by mapping a Data Scope to their SAML login profile. This is done with JSON code.

To enable Dynamic Data Scope mapping

1. In System Settings, on the LDAP & SAML page, scroll down to SAML Advanced Settings.
2. Toggle on Set Dynamic Data Scope.
3. In the Dynamic Data Scope mapping rule box, paste the JSON mapping rule code. See Creating the JSON Mapping Rule below on how to create the JSON code.
4. Click Save to save the changes.

Creating the JSON Mapping Rule

Use the following template to create the JSON mapping code:

{
"<role name>": {
  "<module name>": {
   "<axonius field>": "<SAML field>"
  }
 }
}

For example, use the following JSON to dynamically create Data Scopes based on the viewer role permissions. The Asset Scope query will compare the defined Axonius field value with the value of the defined SAML field.

{
"viewer": {
  "devices": {
   "adapters_data.active_directory_adapter.name": "test"
  }
 }
}

To create JSON mapping code

1. On the Queries page, select the Asset Scope Query that creates the Data Scope.

2. In the query drawer, click Run Query. The results are displayed on the asset page.

3. In the query bar, select and copy the Axonius field name, as shown here:

   

   NOTE

   Do not include the quotation marks in the selection.

4. In the JSON template, enter the following values:

   • For role name, enter the name of the role from which the auto-created roles will be copied. (Valid options are view or edit.)
   • For module name, enter the name of the Axonius module. (Valid options are devices or users.)
   • For axonius field, paste the name of the Axonius field copied above.
   • For SAML field, enter the name of the SAML field to map to the axonius field field.

5. Create the JSON code directly in the Dynamic Data Scope mapping rule text box or in any text editor and then paste it into the text box.

6. Click Save.

Using Multiple SAML Providers

Configure multiple SAML providers to allow users with different identity providers to easily log in to Axonius.

To configure multiple SAML providers

1. Enter the configuration details for the first SAML provider.
2. Click Add New SAML.
3. Fill in the configuration details for the provider according to the directions above. See Configuring a SAML Provider.
4. To delete a SAML configuration, click the trashcan icon next to the configuration you want to delete.

See Using Identity Providers for general information about using identity providers.
For information about LDAP-based login settings, see LDAP Login Settings.