Configure SAML SSO

What you will build

By the end of this tutorial, members of your workspace will be able to sign in using your organisation's Identity Provider (IdP), without a separate HowlOps password.

Time: approximately 15 minutes
Plan required: any paid plan
Prerequisites: Owner or Admin role in HowlOps; Admin access to your IdP

---

Concepts

The platform acts as a SAML 2.0 Service Provider (SP). Your IdP authenticates users and sends a signed SAML assertion back to the platform. You need to exchange two pieces of information between the SP (HowlOps) and the IdP:

• SP Metadata: tells the IdP how to address and sign responses for HowlOps
• IdP Metadata: tells HowlOps where to redirect users and how to verify assertion signatures

---

Step 1: Retrieve your SP Metadata

1. In HowlOps, go to Settings → Security → Single Sign-On.
2. Note down (or copy) the following values:

Value	Where it goes
SP Metadata URL	Enter into your IdP to auto-configure
SP Entity ID	Enter manually into IdP if auto-config is unavailable
ACS URL	Enter manually into IdP if auto-config is unavailable

---

Step 2: Configure your Identity Provider

Select your IdP:

Okta

1. In Okta Admin Console: Applications → Applications → Create App Integration → SAML 2.0 → Next.
2. App name: HowlOps (or any label). Click Next.
3. In the SAML Settings section:
   • Single sign-on URL (ACS URL): paste the ACS URL from HowlOps.
   • Audience URI (SP Entity ID): paste the SP Entity ID from HowlOps.
   • Name ID format: EmailAddress
   • Application username: Email
4. Click Next → Finish.
5. In the Sign On tab, click View SAML setup instructions and copy the IdP Metadata URL.

Microsoft Entra ID (Azure AD)

1. Azure Portal → Microsoft Entra ID → Enterprise Applications → New application → Create your own application.
2. Name: HowlOps, select Integrate any other application…, click Create.
3. Go to Single sign-on → SAML.
4. In Basic SAML Configuration:
   • Identifier (Entity ID): SP Entity ID from HowlOps
   • Reply URL (ACS URL): ACS URL from HowlOps
5. Save. Under SAML Signing Certificate, copy the App Federation Metadata URL.

Google Workspace

1. Google Admin Console → Apps → Web and mobile apps → Add app → Add custom SAML app.
2. Name: HowlOps. Click Continue.
3. Download the IdP metadata XML or copy the SSO URL, Entity ID, and Certificate.
4. In the Service provider details step:
   • ACS URL: paste ACS URL from HowlOps
   • Entity ID: paste SP Entity ID from HowlOps
   • Name ID format: EMAIL
   • Name ID: Basic Information > Primary email
5. Click Finish.

---

Step 3: Complete SSO setup in HowlOps

1. Go to Settings → Security → Single Sign-On.
2. Paste your IdP Metadata URL into the field (or upload the XML file).
3. Enter your SSO domain, the email domain your users sign in with (e.g. yourcompany.com).
4. Click Save configuration.

---

Step 4: Verify your domain

To prevent another organisation from claiming your email domain, HowlOps requires you to prove DNS control of it before SSO login is allowed.

1. In Settings → Security → SSO, after entering your domain, copy the DNS TXT record that HowlOps displays:

   Field	Value
   Type	TXT
   Host / name	_howlops-sso-verify.yourcompany.com
   Value	howlops-domain-verification=<token>

2. Add this TXT record to your domain's DNS zone (in your domain registrar or DNS provider).

3. Once DNS has propagated (usually a few minutes), return to HowlOps and click Verify.

---

Step 5: Test the connection

1. Click Test SSO connection in HowlOps.
2. A new browser tab opens, redirecting you to your IdP login.
3. Log in with your IdP credentials.
4. If successful, you are redirected back with a green confirmation banner.

---

Step 6: (Optional) Enforce SSO

Enforce mode blocks password-based login for all workspace members: everyone must authenticate through the IdP.

1. In Settings → Security → SSO, toggle Enforce SSO.
2. Click Save.

---

Troubleshooting

Problem	Likely cause	Fix
SAML response signature invalid	IdP certificate expired or metadata stale	Re-fetch metadata from IdP and re-save
Redirect loop on login	ACS URL or Entity ID mismatch	Check for trailing slash differences
User not found after SSO	Email in assertion does not match HowlOps account	Ensure IdP sends email as NameID
IdP metadata could not be fetched	Metadata URL unreachable	Upload XML directly
Members locked out after enforce	Members not in IdP	Disable enforce, provision users, re-enable
SSO login rejected / "email domain not authorized"	Domain not DNS-verified, or user's email domain differs from the verified SSO domain	Complete Step 4 (verify the domain); ensure users sign in with an email on the verified domain

---

What's next

• Concepts: Plans & capabilities: capabilities and the SSO security baseline
• How-to: Rotate API tokens: manage API access