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.
Health Check
healthCheck
defines an optional health check for the connector. This option is
required when using the connector in an IDP-continuity scenario. For more info on how
to define the health check, please see the docs.
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