IQ Server Authentication and Authorization

IQ Server | Reading time: 10 minutes

There are several options for authorization and authentication in IQ Server, and many Administrators have a hard time navigating their best options. This article helps you determine which options work best for your organization.

Video

In addition to this written guide, we’ve made a video that goes over the highlights of IQ Server authentication and authorization. Check it out here:

 

Learning Objectives

At the end of this article, you’ll be able to:

  • Understand the difference between authentication and authorization.
  • Explain the authentication methods available with IQ Server.
  • Explain the authorization methods available with IQ Server.
  • Determine which authentication and authorization method works best with your organization.

Audience

IQ (Lifecycle, Auditor, Firewall) Administrators.

What’s the Difference Between Authentication and Authorization?

Before you can start figuring out the best setup for your organization, it’s important to understand the difference between authentication and authorization.

In simple terms, authentication determines who you are and authorization determines what you can access.

In more detail:

  • Authentication determines who a user is, often called the subject in authentication systems. There are lots of options for determining the subject, like user ID and password, fingerprints, facial recognition, and so on.
  • Authorization determines what a user can do within the application. Most of the time this is represented by roles or permissions associated with the authenticated user.

When discussing authentication and authorization, it’s also important to note the concept of realms. Realms are a type of database that store usernames and passwords used to identify and validate users of web applications — in this case, IQ Server. Realms also list roles associated with each validated user. In both the IQ Server realm and LDAP realm, access to IQ Server resources is granted to all users that have a particular role, and each user can have any number of roles associated with their username.

Now that you know the difference between authentication and authorization, and a little bit about realms, let’s go over the different options available for your IQ Server setup.

Local Users

While we recommend using a security protocol for managing users and permissions, the IQ Server realm is also available for those wanting a lighter setup. Using a local setup (IQ Server realm), user accounts (including usernames and passwords) are created and managed on the IQ Server itself.

A local setup can be used for both authorization and authentication. This is the simplest option when you have a limited number of users and you’re using our local database. However, this is not an enterprise setup, and should really only be used in an evaluation setting.

Local User Example

Scenario: You are setting up IQ Server as a proof-of-concept and you want to use a local user setup to test out authentication and authorization.

To add local users, you need to login to IQ Server and use the System Preferences menu to create new users.

You then need to assign users to access roles in the context of organizations and applications. You can assign a user to either a system-wide administrator role or an organizational role at the level of root organization, organization, or application. Which role and level you choose for a user determines what permissions that user receives.

You can also assign roles to individual users or groups of users. IQ Server has a built-in group called Authenticated Users that contains any authenticated user.

For information on adding users, see Creating a User in our IQ Server Help documentation.

For information on assigning access roles, see Role Management in our IQ Server Help documentation.

LDAP

The most common, and preferred, method of authentication and authorization is using your company’s existing Lightweight Directory Access Protocol (LDAP) server. If you have LDAP, you’ve already mapped the users and groups, and it is much easier to use that existing information with IQ Server.

In addition to handling authentication via LDAP, the IQ Server can be configured to map roles to LDAP user groups. If a user is a member of an LDAP group associated with an IQ role, the IQ Server grants that user the matching role permissions. In addition to this highly configurable user and group mapping capability, the IQ Server can augment LDAP group membership with specific user-role mapping.

The IQ Server also supports multiple LDAP servers and user/group mappings. Connection details to the LDAP server, user/group mappings, and specific account logins can also be tested directly from the user interface.

All these features allow you to adapt to any specific LDAP usage scenario and take advantage of the central authentication set up across your organization.

LDAP Example

Scenario: Your organization has LDAP with no constraints, and you want to use that for IQ Server authentication and authorization.

Here’s how that scenario might play out:

  1. Users request access to an IQ Server application through their web browser.

  2. IQ Server makes a request to your organization’s configured LDAP server.

  3. The LDAP server verifies the user’s identity (authentication).

  4. After authenticating the user, IQ Server then uses the account’s LDAP group attributes in combination with role mappings defined in the IQ Server to determine which features the user is authorized to access.

  5. Users are signed-in with the correct permissions.

Getting Started with LDAP

LDAP configuration can be done in the IQ Server UI. To get started with LDAP, do the following:

  1. Enable the LDAP authentication realm.

  2. Create the LDAP server configuration with connections and user/group mapping details.

  3. Assign LDAP roles to IQ Server roles according to organization and application access configuration.

  4. Create external role mappings to adapt LDAP roles to IQ Server specific usage.

  5. Rearrange your LDAP query as needed to get the best performance:

    • A general best practice is to have the group info readily available because LDAP group is automatically mapped to a role.
    • Keep in mind the benefits of multiple LDAP servers. For instance, if you can’t create a query to get the groups — make multiple LDAP connections with an efficient query for each group.

For more information on specific steps, see LDAP Integration in the IQ Server Help docs.

Reverse Proxy

A reverse proxy is a kind of server that sits between a user’s browser and the IQ Server. The reverse proxy can add additional information to a request on behalf of the client. You need a reverse proxy server to use SSO, SAML, or OAUTH with IQ Server.

Using a reverse proxy with IQ Server lets you do the following:

  • Enable single sign on (SSO) with IQ Server by using a reverse proxy to connect to whatever SSO solution you are employing.
  • Implement external ways of authenticating and authorizing like SAML and OAuth.
  • Provide a single point of authentication for all HTTP requests.

The IQ Server can be configured to accept a reverse proxy configuration in the config.yml file, allowing you to specify the exact header field to be used:

# Configures reverse proxy authentication for the web UI.
reverseProxyAuthentication:
   # Set to true to activate authentication
   enabled: true
   # Name of the HTTP request header field that carries the username
   usernameHeader: "REMOTE_USER"
   # Set to true for backward compatibility with old client plugins
   csrfProtectionDisabled: false
 # The service URL that will be redirected to when a user requests logout.
 logoutUrl: http://localhost/logout/index.html

If you’re not using LDAP, you can assign roles to individual users or groups of users in the IQ Server realm. IQ Server has a built-in group called Authenticated Users that contains any authenticated user. This is not an LDAP group, but rather an internal group that is built-in to IQ Server.

The Authenticated Users group is available for any type of authentication/authorization service (SAML, OAuth, etc), and provides a way to grant permissions to any authenticated user.

For information on the Authenticated Users group, see Role Management in our IQ Server Help documentation.

TIP: If you want more defined groups than “all authenticated users,” your best bet is to set up an LDAP server and connect it to IQ Server.

LDAP with SSO Example

Scenario: Your organization has an existing LDAP, but needs single sign on with IQ Server. You decide to setup a reverse proxy server to implement SSO.

Here’s how this scenario might play out:

  1. Users request access to an IQ Server application through their web browser.
  2. The web browser talks to the reverse proxy.
  3. The reverse proxy delegates to your SSO service for authentication.
  4. The SSO service says either “yes, good to go” or “nope, and here’s the error.”
  5. If yes, then the authentication request gets sent off to the IQ Server with the username header populated.
  6. For authorization, users are given permissions based on LDAP groups associated with roles in the IQ Server.

In the above example, the single sign on server is used for login/authentication, and then the association of your permissions is still done via LDAP groups.

SAML Example

Security Assertion Markup Language (SAML) lets users login to other applications using their credentials from another context. SAML works by sharing a user’s identity in one location (an identity provider) to another (a service provider).

To use SAML with IQ Server, you need to configure a reverse proxy server.

Scenario: You are deploying IQ Server via AWS, and you need to use a reverse proxy server to work with a SAML service for user authentication and authorization.

Here’s how this scenario might play out:

  1. Users request access to an IQ Server application through their web browser.
  2. The web browser talks to the reverse proxy.
  3. The reverse proxy delegates to your SAML service for authentication and authorization.
  4. The SAML service says either “yes, good to go” or “nope, and here’s the error.”
  5. If yes, then the authentication request gets sent off to the IQ Server with the username header populated.
  6. For authorization, because the user came from a SAML service, the IQ Server assumes that the user has access to whatever the All Authenticated Users group has access to.

With SAML, all authentication and authorization is done externally. The IQ Server does not have any integration with SAML to pull those permissions out. SAML only passes along the username header. There is no group header available. There is currently no group mapping between IQ Server group roles and SAML groups.

Remember that the Authenticated Users group in IQ Server is available for the SAML service, and provides a way to grant permissions to any authenticated user. Using this method is more of a blanket approach and does not let you differentiate between roles like owner and developer.

For example, let’s say all of your developers access IQ Server through SAML and you want to easily give them developer permissions. In this case, you would use the Authenticated Users group in the IQ Server realm to say that all authenticated users are developers. You may then grant owner access to specific individual users.

NOTE: If you want to use OAuth, it is basically the same as the SAML scenario and your reverse proxy server delegates out to your OAuth system to authenticate. Like SAML, IQ Server does not have native OAuth integration.

So…Which Method Should You Use?

Determining the authentication and authorization methods to implement depends on many factors, and is determined on a case-by-case basis. In the end, how you setup your IQ Server is up to your organization, but we can provide some assistance.

Answer the following questions to get started determining which setup may be right for you:

  1. How many users will you manage?

    • If you have a large enterprise, LDAP is your best option.
    • A local setup should only be used for proof-of-concept.
  2. Do you already have an LDAP server?

    • If so, then go ahead and use LDAP!
    • If not, would you like to implement one?
  3. Do you need SSO?

    • If yes, then you’ll need a Reverse Proxy server.
  4. Do you plan on deploying IQ Server into AWS

    • If yes, then you will need to use SAML with a Reverse Proxy.
  5. Do you need SAML?

    • If yes, then a Reverse Proxy is required.
  6. Do you need OAuth?

    • If yes, then a Reverse Proxy is required.

The following table can also help you easily see what’s required for each method:

Method Enterprise Y or N? Authentication Y or N? Authorization Y or N? Requires other Services? SSO Y or N?
Local Users No Yes Yes No No
LDAP Yes Yes Yes Yes - LDAP Server No
Reverse Proxy Yes Yes No Yes - Authorization Server Yes
SAML Yes Yes Yes Yes - Reverse Proxy Yes
OAuth Yes Yes Yes Yes - Reverse Proxy Yes

Tell Us What You Think

We’d love to hear what you think about this topic and the information covered in this guide. Please take a minute to give us your thoughts over in the Sonatype Community and/or drop an email to the Customer Education team.