SAML 2.0 authentication#

Starburst Enterprise platform (SEP) supports configuring SAML 2.0 authentication to implement single sign-on (SSO) for SEP clusters. When you configure SAML 2.0 with SEP, SEP acts as a SAML service provider and receives authenticated user data from an identity provider (IdP) using HTTPS as follows:

  1. The SEP coordinator identifies the need for authentication and redirects your browser to the SAML IdP’s SSO service.

  2. User provides credentials on the IdP login page for authentication.

  3. The IdP redirects the user’s browser to SEP’s SAML Assertion Consumer Service.

  4. SEP validates the SAML assertion and creates a JSON web token (JWT) for the session.

To enable SAML 2.0 authentication for SEP, configure your coordinator as described in this document. You do not need to make changes to your worker configuration; only the coordinator authenticates communication from clients.

Configuration#

To enable SAML 2.0 authentication for SEP, complete the following steps:

  1. Configure the SAML authenticator in SEP to act as a service provider.

  2. Configure your supported IdP for SAML 2.0 authentication.

SEP coordinator configuration#

To implement SAML 2.0 authentication, you must secure the SEP coordinator with TLS.

The following example provides the minimum required configuration:

http-server.authentication.type=saml

http-server.https.port=8443
http-server.https.enabled=true

http-server.authentication.saml.sp.keystore.path=SAML_CERTIFICATE
http-server.authentication.saml.idp.metadata-file=https://identity-provider.com/saml/metadata
SAML 2.0 authentication configuration properties#

Property

Description

http-server.authentication.saml.sp.entity-id

(Optional) The value for the entityId attribute of the SAML service provider. Defaults to the domain of the requester HTTP address.

http-server.authentication.saml.sp.keystore.path

The path for a PEM file that either contains the certificate and private key to use for the SAML service provider, or specifies a JKS keystore that loads the certificate and private key.

http-server.authentication.saml.sp.keystore.password

(Optional) If using a JKS keystore, the password to the keystore.

http-server.authentication.saml.sp.keystore.key-alias

(Optional) If using a JKS keystore, the alias of the key to use as the SAML service provider certificate.

http-server.authentication.saml.idp.metadata-file

The URI or path to the identity provider’s metadata file.

http-server.authentication.saml.token-signing-key

(Optional) The key for signing the JWT tokens that are generated for SAML-authenticated sessions. Defaults to a random value.

http-server.authentication.saml.token-expiration

(Optional) The duration in hours of SAML-authenticated sessions. Defaults to 12.

http-server.authentication.saml.user-mapping.pattern

(Optional) The regex pattern used to match the subject name from the SAML assertion. Uses the first match group as the username.

http-server.authentication.saml.user-mapping.file

(Optional) The file containing the rules for mapping the subject name from the SAML assertion to the username.

http-server.authentication.saml.challenge-timeout

(Optional) Maximum duration of a SAML authorization challenge. Defaults to 15.

Identity provider configuration#

The following identity providers support SAML 2.0 authentication with SEP:

Azure Active Directory#

Use the following steps to configure Microsoft Azure Active Directory as a SAML 2.0 identity provider for SEP:

  1. In the Azure portal, use the search bar to navigate to the Enterprise applications page.

  2. From the top menu, select + New application.

  3. Select + Create your own application.

  4. In the Create your own application pane, enter a name for the app. Select the Integrate any other application option. Click Create.

  5. Navigate to Manage > Single sign-on. Select the SAML option as your single sign-on method.

  6. Download the XML file from your coordinator URL at https://<host>:<port>/saml/metadata.

  7. Click Upload metadata file. Select the XML file, and click Add.

  8. Ensure that the Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL) fields populate. Click Save.

  9. In the SAML certificates section, copy the content of the App Federation Metadata Url field to your clipboard.

Okta#

Use the following steps to configure Okta as a SAML 2.0 identity provider for SEP:

  1. In the Okta Admin Console, click the menu and select Applications > Applications.

  2. In the Applications pane, click Create App Integration.

  3. In the next pane, select SAML 2.0 and click Next.

  4. This opens the Create SAML Integration pane. In the General Settings tab, enter a name for the app in the App name field. Click Next.

  5. Download the XML file from your coordinator URL at https://<host>:<port>/saml/metadata.

  6. In the XML file, find the md:AssertionConsumerService element with attribute Binding equal to urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST. Copy the Location attribute to your clipboard.

  7. In the Configure SAML tab in Okta, paste the attribute into the Single sign on URL field. Select the Use this for Recipient URL and Destination URL checkbox.

  8. In the XML file, find the md:EntityDescriptor element. Copy the entityID attribute.

  9. In the Configure SAML tab in Okta, paste the attribute into the Audience URI (SP Entity ID) field.

  10. For all other fields, select the appropriate options or leave them in their default settings. Click Next.

  11. Complete the Feedback tab, and click Finish

  12. In Metadata details, copy the content of the Metadata URL field to your clipboard.

PingFederate#

Use the following steps to configure PingFederate as a SAML 2.0 identity provider for SEP. For more information, refer to the PingIdentity documentation.

  1. In PingFederate, navigate to Applications > Integrations > SP Connections.

  2. Click Create Connection.

  3. In the Connection Template tab, select Do not use a template for this connection. Click Next.

  4. In the Connection Type tab, select Browser SSO profiles. For protocol, select SAML 2.0. Click Next.

  5. Download the XML file from your coordinator URL at https://<host>:<port>/saml/metadata.

  6. In the Import Metadata tab, upload the XML file.

  7. In the General Info tab, ensure that the Entity ID, Connection Name, and Base URL fields populate. Click Next.

  8. In the Browser SSO tab, click Configure Browser SSO.

  9. In the SAML Profiles tab, select either the SP-initiated SSO or IDP-Initiated SSO option. Click Next.

  10. In the Assertion Lifetime tab, enter your desired assertion validity time.

  11. In the Assertion Creation tab, click Configure Assertion Creation.

  12. In the Identity Mapping tab, select Standard. Click Next.

  13. In the Attribute Contract tab, select Subject Name Format for SAML_SUBJECT. Click Next.

  14. In the Authentication Source Mapping tab, click Map New Adapter Instance.

  15. In the Adapter Instance tab, select an adapter instance. Click Next.

  16. In the Mapping Method tab, select the Use only the adapter contract values in the SAML assertion option. Click Next.

  17. In the Attribute Contract Fulfillment tab, select Adapter as the Source. For Value, select the attribute you want to use as the username. Click Next.

  18. (Optional) In the Issuance Criteria tab, select any desired authorization conditions. Click Next.

  19. In the Summary tab, click Done.

  20. In the Authentication Source Mapping tab, click Next.

  21. In the Summary tab, click Done.

  22. In the Assertion Creation tab, click Next.

  23. In the Protocol Settings tab, click Configure Protocol Settings.

  24. Ensure that a POST binding, with /saml as the Endpoint URL, is added to the list. Click Next.

  25. In the Allowable SAML Bindings tab, select POST. Click Next.

  26. In the Signature Policy tab, select any desired signature policies. Click Next.

  27. In the Encryption Policy tab, select your desired encryption policy. Click Next.

  28. In the Protocol Settings Summary tab, click Done.

  29. In the Protocol Settings tab, click Next.

  30. In the Summary tab, click Done.

  31. In the Browser SSO tab, click Next.

  32. In the Credentials tab, click Configure Credentials.

  33. In the Digital Signature Settings tab, select the desired Signing Certificate to use with the SSO service.

  34. If you previously enabled signature verification for assertions, navigate to the Signature Verification Settings tab. Click Manage Signature Verification Settings to configure your signature verification.

  35. If you previously enabled encryption for assertions, navigate to the Select XML Encryption Certificate tab. Select the certificate you want to use for encrypting SAML assertions.

  36. In the Summary tab, click Done.

  37. In the Credentials tab, click Next.

  38. In the Activation & Summary tab, review your entries for the SEP SAML SP connection. Ensure the connection is active. Click Save.

  39. In the SP Connections list, find your SEP SAML SP connection and click Select Action > Export Metadata.

  40. Specify the path or URI to the exported metadata file with the http-server.authentication.saml.idp.metadata-file property in your SEP coordinator configuration.

KeyCloak#

Use the following steps to configure KeyCloak as a SAML 2.0 identity provider for SEP:

  1. In KeyCloak, select the realm you want to use for SEP.

  2. Download the XML file from your coordinator URL at https://<host>:<port>/saml/metadata.

  3. On the Clients page, click Import Clients.

  4. Click Browse. Select the XML file.

  5. Ensure that the Client ID field populates.

  6. Enter a Name and Description for your SEP client.

  7. If you want to encrypt SAML assertions, select On for Encrypt Assertions. Click Save.

  8. In SAML capabilities > Name ID format, select a name ID format.

  9. Make all other desired configuration changes. Click Save.

  10. On the Realm Settings page, click SAML 2.0 Identity Provider Metadata next to Endpoints.