SAML

The SAML Connector provides a way for Maverics to interact with any SAML provider. The Connector automatically fetches the information from samlMetadataURL and uses the provided API endpoints to authenticate users and perform session validation.

By default, the SAML connector uses the HTTP-POST binding for sending SAML login requests and receiving their responses.

Configuration options

The following values must be provided to the SAML Connector via the Maverics configuration file.

Entity ID

samlEntityID is the unique application entity ID assigned to the application.

Metadata URL

samlMetadataURL is the metadata URL from the application configured in the SAML provider. The samlMetadataURL setting will accept a file:/// URI if the metadata file is saved on a filesystem accessible to the Orchestrator user.

Consumer Service URL

samlConsumerServiceURL is the URL that the SAML provider will use to POST the SAML response back to. The Maverics SAML ACS handler will be served on this URL, as such it should not conflict with the path of any application resources. The samlConsumerServiceURL path can be arbitrary (e.g. /maverics-saml or /saml-handler), but must match the provider’s configuration for the specified samlEntityID.

Logout Callback URL

samlLogoutCallbackURL is an optional field used to define the URL to which the SAML provider will call back once logout is successful. This will initialize an endpoint on Maverics to listen for the callback. The URL’s domain must match the domain Maverics is on. The samlLogoutCallbackURL path can be arbitrary (e.g. /logout-maverics-saml or /logout-saml-handler), but must match the provider’s configuration for the specified samlEntityID.

SP Cert Path

samlSPCertPath is an optional configuration to the path to the certificate that will be used to sign SAML authentication requests. Must be used with samlSPKeyPath.

SP Key path

samlSPKeyPath is an optional configuration to the path to the private key that will be used to sign SAML authentication requests. Must be used with samlSPCertPath.

Name ID Format

samlNameIdFormat is an optional field used to define the SAML Subject NameID format specified for the app in your SAML provider: urn:oasis:names:tc:SAML:2.0:nameid-format:entity. If left unspecified no NameID format will be sent.

IDP-Initiated Login

samlIDPInitiatedLogin is an optional field used to define the IDP-initiated login settings.

Enabled

enabled defines whether the connector will accept unsolicited SAML responses from the configured IDP. IDP-initiated login is disabled by default as it is inherently less secure than the alternative SP-initiated flow.

Allowed Redirect URLs

allowedRedirectURLs are the set of URLs that the connector can redirect to after processing an IDP-initiated SAML response. The IDP must pass one of the listed URLs via the relay state when it initiates a login. For more info on why a set of URLs are required, please see the OWASP guide on IdP Initiated SSO and the importance of mitigating the Open Redirect attack.

Cache

cache is an optional field that defines the cache settings for the connector. If left undefined, the connector will use the default in-memory cache.

Examples

Basic Configuration

connectors:
  - name: samlClient
    type: saml
    samlEntityID: MavericsOrchestrator
    samlMetadataURL: https://saml-idp.com/FederationMetadata/2007-06/FederationMetadata.xml
    samlConsumerServiceURL: https://orchestrator.example.com/acs
    samlLogoutCallbackURL: https://orchestrator.example.com/logout
    samlNameIdFormat: urn:oasis:names:tc:SAML:2.0:nameid-format:entity
    samlIDPInitiatedLogin:
      enabled: true
      allowedRedirectURLs:
        - https://alpha-app.example.com/dashboard
        - https://beta-app.example.com/index.html  
    cache: redis

Local SAML metadata file

This sample assumes the SAML metadata was downloaded and saved in /etc/maverics/samlmetadata.xml.

connectors:
  - name: samlClient
    type: saml
    samlEntityID: MavericsOrchestrator
    samlMetadataURL: file:///etc/maverics/samlmetadata.xml
    samlConsumerServiceURL: https://orchestrator.example.com/acs
    samlLogoutCallbackURL: https://orchestrator.example.com/logout
    samlNameIDFormat: 'urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified'
    samlSPCertPath: /etc/maverics/certs/example-sp.crt
    samlSPKeyPath: /etc/maverics/certs/example-sp.key