Methods

You can use any of the methods below to authenticate users, but you can only have one method selected at a time. The server will not start if you have enabled more than one. Example configuration for each is given in the default security.yml file. Select a specific method by adding or uncommenting the related properties in the configuration.

Panopticon uses Spring Security for authentication. Properties below that start with spring. all have their default names and can be looked up in the Spring documentation. Properties that start with authentication. are Panopticon-specific.

Some properties below have sensitive information such as passwords. If you do not want to store them in clear text in security.yml you can move them to Secret.properties.

Username and Password

This is the default method and will be used if you have no other method-related properties in security.yml. In this mode, the server expects a list of users and their groups in the <appdata>/users.xml file. The server creates a template for this file when it starts if it’s not there already.

NOTE:

The default users.xml has example users, but they are all commented out. This means that out of the box, the server will use username and password, but has no known users, so you can’t really log in until you provide more configuration (i.e., there will be a single viewer user named user with a one-time random password).
Use this mode for testing and very simple setups only.

LDAP

To use the Lightweight Directory Access Protocol (LDAP) as authentication method, first configure the connection to your LDAP server and a user that has permissions to search users and groups. For example:

spring.ldap:
urls: 'ldap://ldap-host-name:389/'
username: 'cn=admin,dc=company,dc=org'
password: 'admin123'
base: 'dc=company,dc=org'

The spring.ldap.base property is optional and can be used to define a root which the rest of the configuration is relative to.

Next, define where to find the users. Panopticon uses bind authentication against LDAP, so it will try to log in to the LDAP server with the credentials entered by the user. In the example below, {0} is a placeholder where the entered username will be substituted.

authentication.ldap:
user-search.base: ou=sales
user-search.filter: (objectClass=user)
user-dn-patterns: uid={0},ou=users

NOTE: user-search is optional but useful if you have a complicated user structure. You can list multiple user-dn-patterns if you separate them with semicolon.

Finally, tell Panopticon how to find each user’s group memberships. Here, {0} is a placeholder where the user’s full DN will be substituted.

authentication.ldap:
group-search.base: ou=groups
group-search.filter: (member={0})
group-role-attribute: cn

Active Directory

To use Active Directory (AD) as an authentication method, you need to first configure the AD server. Then provide the following:

authentication.active-directory:
urls: ldap://host-name:389/
domain: company.com

Field

Description

urls

This field is mandatory and can take multiple URLs, if necessary, but they must be separated.

The port can be 389 or 3268. With the latter, Panopticon does a global search in AD which is useful if there are multi/subdomain set up. However, the Panopticon server cannot extract groups from it because memberOf properties would be missing.

domain

This field is optional. If it is not defined, you can provide the login name as someone@somecompany.com. Otherwise, simply log on as someone assuming the domain is set to somecompany.com.

OAuth 2.0

A typical OAuth configuration looks like this:

spring.security.oauth2.client:
registration:
our-okta-app:
client-id: 0odfhiuhvb5d7
client-secret: r7rFsdgkjsdgpUXB
scope: openid, profile, groups
provider:
our-okta-app:
issuer-uri: https://dev-8052349.okta.com

our-okta-app is a name that you choose yourself for the registration. Tthis is because Spring Security normally supports multiple registrations. It can be anything, but it needs to be the same in both locations, and it affects the redirect URI.

From the OAuth server, you need three things: the ID and secret for the client that you have registered there for Panopticon, and the URI to the server itself. The scope should be enough to retrieve the user’s username and user groups, and the application should be configured to return the groups in a claim.

On the OAuth server side, you need to register a Panopticon endpoint as a valid sign-on redirect URI (or similar). This endpoint is /login/oauth2/code/<reg-name>, where <reg-name> is what you chose for the registration in security.yml. For example, https://company.org/analytics/login/oauth2/code/our-okta-app, assuming you expose Panopticon at https://company.org/analytics.

Panopticon gets the username from the preferred_username claim, and the user groups from the groups claim by default. If you want to use other claims, this can be configured via:

authentication.oauth2.username-claim (default preferred_username)
authentication.oauth2.groups-claim (default groups)

The configuration above only works if the OAuth server exposes the default metadata endpoint (i.e., /.well-known/openid-configuration or /.well-known/oauth-authorization-server). If it does, Spring Security can get most of the necessary configuration from there. If not, you need to manually provide this configuration. The list of available properties can be found here and other resources on the web:

https://docs.spring.io/spring-security/reference/6.1/servlet/oauth2/login/core.html#oauth2login-boot-property-mappings

SAML 2.0

A typical SAML configuration looks like:

spring.security:
saml2.relyingparty.registration:
our-okta-app:
assertingparty:
metadata-uri: https://login.company.org/sso/saml/metadata

our-okta-app is a name that you choose yourself for the registration. This is because Spring Security normally supports multiple registrations.

On the SAML server side, you need to register a Panopticon endpoint as the single sign-on URL (or similar). This endpoint is /login/saml2/sso/<reg-name>, where <reg-name> is what you chose for the registration in security.yml. For example, https://company.org/analytics/login/saml2/sso/our-okta-app, assuming you expose Panopticon at https://company.org/analytics.

Panopticon uses the NameID element in the SAML response as the user’s username and gets the user groups from the groups attribute. If you want to use an attribute as username, or a different attribute for the groups, this can be configured via:

authentication.saml2.username-attribute (Default not set, use NameID)
authentication.saml2.groups-attribute (Default groups)

You get the metadata-uri from the SAML server. Spring Security will fetch the rest of the required configuration from there. If this doesn’t exist, or is not publicly exposed, you need to manually provide the rest of the configuration. The list of available properties can be found here and other resources on the web:

NOTE: When Panopticon initiates a SAML login, it stores verification information in the user’s HTTP session. To find and validate this after the login, it is critical that the browser passes the session cookie back. By default, SAML finishes with a cross-site POST which the browser considers insecure and therefore omits the cookie. To make an exception for the session cookie, add this to security.yml:

server.servlet.session:
cookie.same-site: None
cookie.secure: true

This sets SameSite=None on the cookie, instructing the browser to include it in the cross-site POST. Cookies can only have this attribute if they also have Secure set. This means that you must use HTTPS with these settings.

If the SAML server requires that you sign the SAML requests, you need to provide a credentials pair: a private key and the corresponding public certificate. The certificate used to validate the signatures on SAML responses is automatically downloaded with the metadata.

spring.security.saml2.relyingparty.registration:
our-okta-app:
assertingparty:
metadata-uri: https://login.company.org/sso/saml/metadata
signing.credentials:
- private-key-location: file:/creds/key.pem
certificate-location: file:/creds/cert.pem

Intellectual Property Rights Notice | Technical Support