Integrations
SAML single sign-on
Connect your organization’s identity provider to the Bastion tenant workspace using SAML 2.0.
On this page
What SSO signs users into
Enterprise SAML signs your team into its Bastion workspace. It does not authenticate your application’s customers and does not replace site-secret SDK authentication. Configure it as the workspace owner. SSO configuration and sign-in are disabled in the public demo.
Connect your identity provider
- Open Workspace → SSO. Obtain the service-provider metadata URL, issuer/entity ID, and callback/ACS URL shown for this site.
- Create a SAML 2.0 application in your identity provider. Set audience/entity ID to the reported issuer and ACS/reply URL to the reported callback URL.
- Configure HTTP-POST responses, signed assertions, and an email NameID or email attribute. Assign the application to your existing Bastion team members.
- Copy the IdP SSO entry point, IdP entity ID/issuer, and unexpired PEM X.509 signing certificate into Bastion.
- Enable the configuration and test the reported workspace login URL in a browser. Keep an owner password session available while testing.
| Bastion value | Identity provider field |
|---|---|
| issuer | Service provider entity ID / audience. |
| callbackUrl | Assertion Consumer Service / reply URL. |
| metadataUrl | Importable service provider metadata. |
| loginUrl | Browser entry point for SP-initiated sign-in. |
| entryPoint | IdP Single Sign-On HTTPS URL, supplied to Bastion. |
| idpIssuer | IdP entity ID, supplied to Bastion. |
| certificate | IdP assertion-signing PEM X.509 certificate, supplied to Bastion. |
Configuration API
curl 'https://api.bastionsecurity.io/api/auth/sso/YOUR_SITE_ID/config' \
-H "Authorization: Bearer $BASTION_ACCESS_TOKEN"{
"entryPoint": "https://idp.example.com/saml/sso",
"idpIssuer": "https://idp.example.com/entity",
"certificate": "-----BEGIN CERTIFICATE-----\nYOUR_IDP_SIGNING_CERTIFICATE\n-----END CERTIFICATE-----",
"enabled": true
}GET and PUT configuration require the site owner’s Bearer access token and Enterprise access. The response provides the site-specific URLs; copy those values instead of guessing your deployment hostname. The certificate placeholder above must be replaced by a real, unexpired X.509 certificate.
Sign-in flow & endpoints
| Endpoint | Behavior |
|---|---|
| GET /api/auth/sso/{siteId}/metadata | Enabled Enterprise configuration → SAML XML metadata, not a JSON envelope. |
| GET /api/auth/sso/{siteId}/start | Browser redirect to IdP; establishes a five-minute HttpOnly state cookie. |
| POST /api/auth/sso/{siteId}/callback | IdP form POST with SAMLResponse and RelayState; validates signed assertion and state. |
| POST /api/auth/sso/exchange | {code} → user, accessToken, refreshToken, siteId in data. |
Bastion hosts the ACS callback. After validation, it redirects to /login/sso#code=… on the website. The website exchanges the one-use code automatically; it expires after 60 seconds. Open the login URL in the browser so state cookies and RelayState remain associated. You do not need to implement another SAML callback in your own application.
Assertion requirements & troubleshooting
- The assertion itself must be signed. A signed outer response alone is insufficient.
- Audience, destination, IdP issuer, InResponseTo, and RelayState must match the configuration and initiated sign-in.
- Assertions and requests use a five-minute validity window with 30 seconds of clock tolerance.
- Use email in NameID or a recognized email/mail attribute; match the existing user’s normalized email.
- The user needs an active owner, analyst, or viewer membership in this site.
- Use the correct public HTTPS callback URL and allow the Secure SameSite=None state cookie through the login flow.
The resulting session is workspace-scoped. It cannot access other tenants or account-wide settings. Access tokens expire after one hour; sign in again when expired. Update the IdP signing certificate in Bastion before certificate rotation or expiry.