SAML SSO
Learn how to authenticate into Tracecat with SAML SSO.
Supported Identity Providers
Configuration
In your .env file, make sure you have the following values set.
Instructions
Tracecat requires BOTH assertions and responses to be signed.
If you are using a self-signed certificate for your metadata URL,
you’ll need to add the CA certificates .pem file as a base64-encoded string via the SAML_CA_CERTS environment variable.
Okta
Create an SAML app
Go to Applications and select Add Application. Select SAML 2.0 and click on Create.
Configure SAML settings
- Set the Single sign-on URL, Recipient URL, and Destination URL to
https://<your-tracecat-instance>/auth/saml/acs. - Set the Audience Restriction to
https://<your-tracecat-instance>.
Configure attribute statements
Map email to user.email
Configure SAML settings in environment variables
Set the following environment variables in your .env file:
SAML_IDP_METADATA_URL: Okta metadata URL
Restart Tracecat instance
Restart Tracecat to apply the changes.
Test SSO configuration
Navigate to your Tracecat instance and click on the Login button. You should be redirected to Okta for authentication.
Microsoft Entra ID
Microsoft Entra ID only signs SAML assetions by default. You’ll need to explicitly enable the Sign SAML response and assertion option.
Create an SAML app
Go to Enterprise applications and select the New application button. Find and select the Microsoft Entra SAML toolkit app.
Configure SAML settings
- Set the Reply URL and Sign on URL to
https://<your-tracecat-instance>/auth/saml/acs. - Set Identifier to
https://<your-tracecat-instance>/api. - Set Relay State to
https://<your-tracecat-instance>. - Make sure that Sign SAML response and assertion is enabled.
Configure attribute and claims
Map email to user.mail
Authentik
Create a provider
Go to Providers and select the Create button. Choose SAML Provider and select the Next button.
Configure the provider
- Enter a name and choose an authorization flow
- Set the ACS URL to
https://<your-tracecat-instance>/auth/saml/acs. - Set the Audience to
https://<your-tracecat-instance>/api.
Configure assertion signing
- Expand the Advanced protocol settings section.
- Select a Signing Certificate and ensure Sign assertions is enabled.
Configure property mapping
- Select authentik default SAML Mapping: Name in Selected User Property Mappings.
- Click the < button to deselect it.
- Select the Finish button.
Create an Application
Go to Applications and select the Create button. Fill in the details as desired.
Find metadata URL
- Select the provider you created previously.
- Select the Metadata tab.
- Select the Copy download URL button.
Configure SAML settings in environment variables
Set the following environment variables in your .env file:
SAML_IDP_METADATA_URL: Metadata download URL
Restart Tracecat instance
Restart Tracecat to apply the changes.
Test SSO configuration
Navigate to your Tracecat instance and click on the Login button. You should be redirected to Authentik for authentication.
Environment variables
If you know what you’re doing, you can configure the SAML configuration via environment variables in the Tracecat api service:
Protocol Configuration
SAML_ALLOW_UNSOLICITED: Whether to allow unsolicited SAML responses (default:true)SAML_ACCEPTED_TIME_DIFF: Time difference in seconds for SAML authentication (default:3)SAML_AUTHN_REQUESTS_SIGNED: Whether to require signed SAML authentication requests (default:false)SAML_SIGNED_ASSERTIONS: Whether to require signed SAML assertions (default:true)SAML_SIGNED_RESPONSES: Whether to require signed SAML responses (default:true)
SSL Transport Configuration
SAML_VERIFY_SSL_ENTITY: Whether to verify SSL certificates for general SAML entity operations (default:true)SAML_VERIFY_SSL_METADATA: Whether to verify SSL certificates when fetching metadata (default:true)SAML_CA_CERTS: Base64 encoded CA certificates for SSL/TLS transport layer validation
SAML Protocol Configuration
SAML_METADATA_CERT: Base64 encoded certificate for SAML metadata document signature verification