SSO (SAML)

Single sign-on lets your team sign in to Asiri with the identity provider (IdP) you already operate — Okta, Azure AD, Google Workspace, or any other SAML 2.0-compliant provider. Provisioning, de-provisioning, and role changes flow from your IdP into Asiri, so off-boarding a user from your directory immediately revokes their Asiri access.

Configuration lives at Settings → SSO and requires the admin role on the workspace.

What you get

• One sign-in surface for every member of your workspace.
• Domain-locked sign-in: only users whose email matches an enforced domain can use SSO.
• Automatic user provisioning on first sign-in (combine with SCIM to provision ahead of first login).
• Role assignment via the defaultRole setting (see Role mapping).
• A full audit trail of every SSO sign-in, configuration change, and provisioning event — see Concepts → Audit log.

Flow model

Asiri v1 supports SP-initiated sign-in only: the user starts at app.asiri.ng, enters their email, and Asiri redirects them to your IdP. IdP-initiated sign-in (clicking the Asiri tile inside Okta or the Azure My Apps portal) is not supported yet — those clicks will fail. Use a bookmark to app.asiri.ng instead.

Setup overview

Configuring SSO is a five-step flow. Steps 1 and 2 happen in your IdP; steps 3-5 happen in the Asiri dashboard.

1. Register Asiri as a SAML application in your IdP.
2. Download your IdP’s SAML metadata XML.
3. Paste the metadata into Settings → SSO and pick the default role.
4. Add your enforced sign-in domain(s).
5. Verify domain ownership with a DNS TXT record.

Sign-in is blocked until step 5 completes — domain verification closes an impersonation vector and is non-negotiable.

SP metadata Asiri publishes

Your IdP needs three values from Asiri to register us as a service provider. Get them from Settings → SSO → Download SP metadata (or pull them programmatically via GET /v1/sso/sp-metadata):

Asiri requires assertions to be signed. Sign-in requests from Asiri to your IdP are not signed.

Provider setup

Okta

1. In the Okta admin console, go to Applications → Applications → Create App Integration.
2. Pick SAML 2.0 and click Next.
3. General Settings: App name Asiri, then Next.
4. SAML Settings:
   • Single sign-on URL: the ACS URL from your Asiri SP metadata.
   • Audience URI (SP Entity ID): the Entity ID from your Asiri SP metadata.
   • Name ID format: EmailAddress.
   • Application username: Email.
   • Response Signed: Yes. Assertion Signed: Yes.
   • Leave the attribute statements empty — Asiri reads identity from the NameID.
5. Click Next, then Finish.
6. On the new app’s Sign On tab, click View SAML setup instructions. Download the IDP metadata XML.
7. Assign the app to the users and groups who should have Asiri access.
8. Paste the metadata XML into Asiri at Settings → SSO → IdP metadata.

Azure AD (Microsoft Entra ID)

1. In the Entra admin centre, go to Enterprise applications → New application → Create your own application.
2. Name it Asiri, choose Integrate any other application you don’t find in the gallery (Non-gallery), and Create.
3. Open the new application, go to Single sign-on, and pick SAML.
4. Edit Basic SAML Configuration:
   • Identifier (Entity ID): the Entity ID from your Asiri SP metadata.
   • Reply URL (ACS URL): the ACS URL from your Asiri SP metadata.
   • Sign on URL: https://app.asiri.ng/sign-in.
5. Under Attributes & Claims, confirm the unique user identifier is user.mail (or user.userprincipalname if your tenant uses UPNs as the email).
6. Under SAML Certificates, download Federation Metadata XML.
7. Under Users and groups, assign the users who should have Asiri access.
8. Paste the metadata XML into Asiri at Settings → SSO → IdP metadata.

Google Workspace

1. In the Google Admin console, go to Apps → Web and mobile apps → Add app → Add custom SAML app.
2. Name it Asiri and click Continue.
3. Download the IdP metadata XML on the Google Identity Provider details screen and click Continue.
4. Service provider details:
   • ACS URL: the ACS URL from your Asiri SP metadata.
   • Entity ID: the Entity ID from your Asiri SP metadata.
   • Name ID format: EMAIL.
   • Name ID: Basic Information → Primary email.
5. Skip the attribute mapping screen — Asiri reads identity from the NameID.
6. Click Finish, then turn the service ON for the OUs that should have Asiri access.
7. Paste the metadata XML into Asiri at Settings → SSO → IdP metadata.

Domain verification

After you save your IdP metadata and at least one enforced domain, Asiri displays a DNS TXT record on the SSO settings page. You must publish this record on your domain before sign-in is permitted.

The record looks like this (replace {tenant-uuid} with your tenant id and {token} with the value Asiri generates):

For example, a tenant whose id is 7f3b2c1a-... verifying acme.com would publish:

_asiri-sso-tenant-7f3b2c1a-....acme.com.   IN   TXT   "_asiri-sso-tenant-7f3b2c1a-...=abc123..."

After the record propagates (typically under five minutes), click Verify domain in the Asiri dashboard. Once verified, sign-in is enabled. Changing the enforced domain later resets verification — you’ll need to repeat this step for the new domain.

Role mapping

Every user provisioned through SSO is assigned the workspace’s defaultRole. Set this at Settings → SSO → Default role. Allowed values:

The role is re-applied on every sign-in, so changing defaultRole propagates to all existing SSO users on their next sign-in. To assign different roles to different users, use SCIM provisioning — your IdP can map its own groups onto Asiri roles at user-create time.

The dpco_principal role is reserved for DPCO firms and cannot be set via the SSO default-role field.

Troubleshooting

”No SSO provider for this email”

The user’s email domain isn’t in enforced domains, or domain verification hasn’t completed. Confirm the DNS TXT record is published and that Settings → SSO shows Domain verified.

”Invalid SAML response” or “Signature validation failed”

Most often: assertions aren’t being signed. In Okta this is Assertion Signed: Yes; in Azure AD it’s on by default; in Google Workspace it’s automatic. Re-download the IdP metadata after re-saving the IdP-side config — the certificate may have rotated.

”AudienceRestriction failed” / “Recipient does not match ACS URL”

The Entity ID or ACS URL you entered in the IdP doesn’t match what Asiri publishes for your tenant. Re-copy the values from Settings → SSO → Download SP metadata. The ACS URL must end in tenant-{your-tenant-id} — a missing or wrong tenant id is the most common cause.

”Domain not verified”

Asiri returns this when an SSO sign-in succeeds at the IdP but the user’s email domain hasn’t been DNS-verified on this workspace. Re-check the TXT record using dig +short TXT _asiri-sso-tenant-{tenant-uuid}.{your-domain} and then click Verify domain in the dashboard.

IdP-initiated sign-in fails

This is expected. v1 is SP-initiated only — point users to app.asiri.ng to start sign-in. IdP tiles in Okta or the My Apps portal will not work.