# SAML Configuration

> Discusses the Security Assertion Markup Language (SAML) standard and its application in facilitating single sign-on (SSO) and other security assertions within ReversingLabs solutions.

**Note: This guide applies to Spectra Analyze and Spectra Detect Manager.**


## Identity Provider setup

With your Identity Provider (IdP), create and configure the Spectra application. In this setup, the Spectra appliance is a Service Provider (SP). Depending on the IdP, different values are required to set up an SP. In addition, the SAML response issued by the IdP when logging in to an SP may have different default values.

Information required by the IdP usually involves the following:

- Entity ID
  - This is the unique identifier of the SP, and is usually based on a URL.
  - For Spectra appliances, **Entity ID** is configurable (see below).
- ACS
  - This is the *Assertion Consumer Service*, or the address where the Identity Provider sends a SAML response.
  - In some providers, this is also called a *Reply URL* or *Single sign-on URL*.
  - For Spectra appliances, this is: `<Appliance URL>/saml2/acs/`
- Login URL
  - This is not a required field in some Identity Providers.
  - For Spectra appliances, this is: `<Appliance URL>/accounts/login/`
- Attribute Statements
  - These are the claims to be sent back to the Service Provider (SP)
  - Required attributes: `email` and `userName` (which can also be an email).
  - Optional attributes
- Group Attribute Statements
  - Some IdPs have a separate setting for groups.
  - It is common to send all groups using a regex like `.*`. The Service Provider (SP) will then match the relevant groups.

Assign the users who need access to the appliance to one group, and also assign admin users (or Superusers) to an additional group. Then, assign both groups to the Spectra application.

Note: You can create a third group specifically for users you want to explicitly deny access.unts/login/`

After configuring the application in the IdP, export an **XML metadata file**.

## Service Provider setup

> In Spectra Analyze: *Administration > Configuration > Authentication > User Directory: SAML*
>
> In Spectra Detect: *Administration > Spectra Detect Manager > Authentication > User Directory: SAML*

Within the Spectra appliance, configure the following fields.

**Entity ID**

Unique identifier for the SP. An example setup would be to use the appliance address + a suffix, such as `/sp`. For example, `https://example.reversinglabs.com/sp`.

**Federation metadata file**

This is the XML file exported from the Identity Provider.

**Claim mapping**

The values provided here are the attributes (fields) in the Identity Provider’s SAML response that are to be used in the Spectra appliance. These can have different values, depending on how you configure them on the IdP. `Username` and `E-mail` are required fields.

For example, if you have the following attributes in your IdP:

- `userName`
- `email`
- `groups`

...add them in this section. You can also use a single attribute to populate several fields in the Spectra appliance. For example, if you have an `email` attribute in your IdP, you can list `email` twice here: once for the username, and once for the email. The remainder of the fields can be left blank. 

Multiple users can share the same email attribute. If that is the case, `email` can't be used for a username because a username must be unique. Usernames are also case-insensitive: for example, if a user "john" exists, another user "John" can't be added.

**User access**

In this section, set one or more group IDs which correspond to specific actions or permissions you wish to enforce. For example, if you set up a *Superuser flag group* called `manager-admin` and add certain users to that group within your Identity Provider, then only those users will have superuser (admin) privileges on the appliance.

Certain Identity Providers don’t expose the names of groups, and instead use an ID like this one: `bcbd79b7-784f-43f2-af70-4dd67cbbc463`. In these cases, use that instead of the group name.

The *Active flag group* field accepts the name of the group containing active users. If a user is not in this group, they will be marked as inactive and denied access. If using multiple groups, a user must be present in at least one group to be granted access.

The *Superuser flag group* field accepts the name of the group containing superusers (administrators). Users will be marked as superusers only if they are in this group.

The *Require group* field accepts the name of the group containing users who have access to the appliance. Authentication will fail for every user that is not in this group. If using multiple groups, a user must be present in all groups configured to be granted access.

The *Deny group* field accepts the name of the group containing users who are not allowed to access the appliance. Authentication will fail for every user that is in this group.

**Note: The `Active` and `Require` groups function similarly, but only one should be used at a time. Superusers must belong to both the `Superuser` flag group and either the `Active` _or_ `Require` group (whichever group is chosen is also used to determine the full list of users.)**


**Allow unsolicited responses from IdP**

There are two ways of logging in using SAML:

1. Going to the appliance login page and clicking *Login Using SSO*.
2. Opening the Identity Provider’s dashboard and logging in to the appliance from there.

If you wish to enable logging in from a dashboard, mark this checkbox.
