SAML-Based Login Settings
  • 08 Jan 2023
  • 7 Minutes to read
  • Dark
    Light
  • PDF

SAML-Based Login Settings

  • Dark
    Light
  • PDF

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 Allow SAML-Based Logins to the on position.
  • 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.

Configuring a SAML Provider

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 the identity provider that cannot be changed after it is saved. The IDP name cannot contain spaces, hyphens or a long word. It will appear in the list of available identity providers for the user.

  • Automatically redirect all logins to the identity provider - Select whether to automatically redirect all users to the configured SAML identify provider.

    • When this is enabled, any user who tries to log in to Axonius will be automatically redirected to the configured SAML identify 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 identify 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.

  • Single sign-on service URL (optional) - A URL that is needed for the SAML Authentication.

  • Entity ID (optional) - The ID of the Axonius entity in the identity provider.

  • Signing certificate (Base64 encoded) (optional) - A base64-encoded signing certificate that is needed for the SAML protocol.

  • Do not send AuthnContextClassRef - The SAML AuthNRequest will not include the AuthnContextClassRef SAML attribute:
    <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport<</saml:AuthnContextClassRef>>

  1. 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:
Name Value Comment
Signing certificate (Base64 encoded) https://<axonius_hostname>/api/login/saml/metadata/ A one-shot URL for identity providers that support metadata URL parsing
Entity ID / Audience URI https://<axonius_hostname>/api/login/saml/metadata/
Reply URL / Single Sign on URL https://<axonius_hostname>/api/login/saml/?acs Assertion Consumer Service URL
Sign on URL / Default Relay State https://<axonius_hostname>/api/login/saml Optional. This is useful only if you want to allow identity-provider initiated authentication

Mapping SAML User Parameters

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.

SAMLUSERBAsedPAramets.png

  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 identify 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. Additional configuration is needed in Okta in order to pass user role assignments.

Custom Group Attributes need to be set in Okta. 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 - Role Assignment Settings

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

image.png

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. 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 re-evaluated and will remains 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.
  3. Role Assignment Rules (users will be assigned to the first matching role) (optional, default: empty) - 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.

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.

SAMLAdvancedSettings.png

To enable Dynamic Data Scope mapping

  1. In System Settings, on the Identity Providers Settings tab, scroll down to SAML Advanced Settings.
  2. Toggle Set Dynamic Data Scope on.
  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:

    SAML-JSON-mapping-blur.png

    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. The first SAML configuration cannot be deleted.

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.