Security#

Starburst Gateway includes security features for its user interface and APIs. The Gateway passes all requests to backend clusters without performing additional security checks.

TLS configuration#

TLS is required for all authentication mechanisms.

Load balancer setup#

If your environment already has a load balancer or proxy server with a valid TLS certificate, work with your network administrators to deploy Starburst Gateway behind the load balancer.

End-to-end TLS#

To configure an end-to-end TLS connection TLS directly with Starburst Gateway, obtain a TLS certificate and configure the following settings:

serverConfig:
    http-server.http.enabled: false
    http-server.https.enabled: true
    http-server.https.port: 8443
    http-server.https.keystore.path: certificate.pem
    http-server.https.keystore.key: changeme

For advanced TLS configurations, see the TLS documentation.

Authentication#

Authentication only works over HTTPS.

To configure authentication, add an authentication section to your configuration file with the desired authentication type

OAuth/OpenID Connect#

See the following example OAuth configuration:

authentication:
  defaultType: "oauth"
  oauth:
    issuer: https://your-oauth-provider.com
    clientId: your-client-id
    clientSecret: your-client-secret
    tokenEndpoint: https://your-oauth-provider.com/token
    authorizationEndpoint: https://your-oauth-provider.com/auth
    jwkEndpoint: https://your-oauth-provider.com/.well-known/jwks.json
    redirectUrl: https://your-gateway.com/oidc/callback
    redirectWebUrl: https://your-gateway.com/
    userIdField: email
    scopes:
      - openid
      - profile
      - email

Set the privilegesField to retrieve user privileges from an OAuth claim.

OAuth routing considerations#

OAuth requires additional routing configuration:

  • Starburst Gateway uses /oidc/callback while clusters use /oauth2.

  • Starburst Gateway needs its own OAuth client ID, while backend clusters must share a single client ID.

  • OAuth requests must route to a single backend cluster.

The following example creates a routing rule that sends OAuth requests to a group called oauth2-handler:

  ---
  name: "OAuth requests"
  description: "Oauth requests need to go to a single backed"
  condition: "request.getRequestURI.startsWith(\"/oauth2\")"
  actions:
    - "result.put(\"routingGroup\", \"oauth2-handler\")"

Form authentication with preset users#

Configure form authentication with preset users in your YAML file:

presetUsers:
  user1:
    password: <password>
    privileges: ADMIN_USER
  user2:
    password: <password>
    privileges: API

privileges must be a combination of ADMIN, USER, and API. Use _ for separation.

Provide RSA key pair files for signing authentication tokens:

authentication:
  defaultType: "form"
  form:
    selfSignKeyPair:
      privateKeyRsa: /path/to/private-key.pem
      publicKeyRsa: /path/to/public-key.pem

Form authentication with LDAP#

Configure form authentication with LDAP in your YAML file:

authentication:
  defaultType: "form"
  form:
    ldapConfigPath: <ldap_config_path>
    selfSignKeyPair:
      privateKeyRsa: <private_key_path>
      publicKeyRsa: <public_key_path>

LDAP configuration file#

Create a separate LDAP configuration file:

ldapHost: 'ldap.example.com'
ldapPort: 389
useTls: true
useSsl: false
ldapAdminBindDn: 'cn=admin,dc=example,dc=com'
ldapUserBaseDn: 'ou=users,dc=example,dc=com'
ldapUserSearch: '(&(objectClass=person)(uid={user}))'
ldapGroupMemberAttribute: 'member'
ldapAdminPassword: 'admin-password'
ldapTrustStorePath: '/path/to/truststore.jks'
ldapTrustStorePassword: 'truststore-password'
poolMaxIdle: 8
poolMaxTotal: 8
poolMinIdle: 0
poolTestOnBorrow: true

Authorization#

Starburst Gateway supports three roles to control access to control access to different features

  • ADMIN: Allows access to the Editor tab for configuring backends

  • USER: Allows access to the main user interface

  • API: Allows access to REST APIs for backend configuration

Role configuration#

Define roles using regex format:

authorization:
  admin: (.*)ADMIN(.*)
  user: (.*)USER(.*)
  api: (.*)API(.*)

LDAP authorization#

For LDAP-based authorization, add the LDAP configuration path:

authorization:
  admin: (.*)ADMIN(.*)
  user: (.*)USER(.*)
  api: (.*)API(.*)
  ldapConfigPath: '/path/to/ldap-config.yml'

See the LDAP test configuration file for detailed examples.

OAuth authorization#

For OAuth-based configuration, set the privilegesField in your configuration to specify a OAuth claim.

Page permissions#

By default, all authenticated users can access all pages. Restrict page access by configuring page permissions.

Available pages#

The following pages are available:

  • dashboard

  • cluster

  • resource-group

  • selector

  • history

Permission configuration#

Configure page permissions using role names and page names separated by underscores:

pagePermissions:
  admin:  # Empty = access to all pages
  user: dashboard_history  # Access only to dashboard and history pages
  api:  # Empty = access to all pages

Self-signed certificates#

If backend clusters use self-signed certificates, configure Starburst Gateway to trust them.

JVM trust store#

Add JVM parameters for the trust store:

-Djavax.net.ssl.trustStore=<truststore file>
-Djavax.net.ssl.trustStorePassword=<truststore password>

Disable hostname verification#

To skip hostname validation for self-certificates, include the following in the serverConfig configuration:

serverConfig:
  proxy.http-client.https.hostname-verification: false
  monitor.http-client.https.hostname-verification: false