SAML and SCIM

Two features link TechWatchAlert to your company directory:

• SAML 2.0: your colleagues sign in with their company account, as with OIDC SSO, but over the SAML protocol (ADFS, Okta, Entra ID, Google Workspace…);
• SCIM 2.0: the directory itself creates, updates and deactivates the organization’s accounts, and puts everyone in the right groups.

Both are included in the Enterprise plan (or as a quoted add-on). On another plan, the SAML 2.0 choice on the Authentication (SSO) page and the Provisioning (SCIM) page carry the plan lock; the API also rejects the request and says why.

• Who: the organization’s Admins and Owner.
• Where: Organization settings › Security › Authentication (SSO) and Security › Provisioning (SCIM).
• Prerequisite: at least one verified email domain (step 1 of the SSO page). An address outside the verified domains is always rejected, at sign-in and at provisioning: an organization’s directory only has authority over its own domains.

SAML 2.0 sign-in

How it works

1. On the sign-in page, the person enters their address. If the domain belongs to an organization whose SAML SSO is active, the Sign in with your organization’s SSO button appears (alone, if the organization enforces SSO).
2. TechWatchAlert sends a signed authentication request to your identity provider, which authenticates the person (password, MFA, passwordless: the provider decides).
3. The provider returns a signed assertion. TechWatchAlert checks it, then opens the session.

What TechWatchAlert checks on every response:

• the assertion is signed with the registered provider certificate (a signed response alone is not enough); SHA-1 signatures are rejected;
• it is meant for you: audience = the TechWatchAlert identifier, destination and recipient = your organization’s exact reply URL;
• it answers the request sent from this browser (a response meant for another browser, or for a request already handled, is rejected);
• it is within its validity period, with a 3-minute clock tolerance;
• it has never been presented before: each assertion works only once;
• the address belongs to a verified domain of the organization.

Sign-out is local: it ends the TechWatchAlert session, not your identity provider session.

Details to give your provider

Choose SAML 2.0 under Protocol. The Details for your identity provider section shows:

Value	Where to paste it
Identifier (Entity ID)	“Identifier”, “Audience URI”, “Entity ID”
Reply URL (ACS)	“Reply URL”, “Single sign-on URL”, “ACS URL”
Metadata URL	to import into a provider that reads metadata (ADFS…)
Signing certificate	if your provider checks the request signature

Download metadata gives the same content as an XML file. The identifier and reply URL are specific to your organization.

Microsoft Entra ID

1. In the Entra admin center: Enterprise applications › New application › Create your own application, “Integrate any other application you don’t find in the gallery”.
2. Single sign-on › SAML. In Basic SAML Configuration, paste the TechWatchAlert Identifier (Entity ID) and Reply URL (ACS).
3. Attributes & Claims: the unique user identifier (NameID) is user.userprincipalname by default. If the UPN is not the email address, choose user.mail. To synchronize groups, Add a group claim › “Groups assigned to the application”.
4. SAML Certificates: copy the App Federation Metadata Url.
5. In TechWatchAlert, Metadata › By URL, paste this URL, then Import.
6. Users and groups (in Entra): assign the application to the relevant people or groups.

Entra sends groups as their object ID (a GUID), in the http://schemas.microsoft.com/ws/2008/06/identity/claims/groups claim: enter this name in Groups attribute, and map the object IDs in the group mappings (see below). Beyond 150 groups, Entra no longer sends the list: stick to the groups assigned to the application.

Okta

1. Applications › Create App Integration › SAML 2.0.
2. Single sign-on URL: the Reply URL (ACS); Audience URI (SP Entity ID): the Identifier (Entity ID). Name ID format: EmailAddress; Application username: Email.
3. Attribute Statements (optional): firstName = user.firstName, lastName = user.lastName. Group Attribute Statements: name groups, filter as needed.
4. On the Sign On tab, copy the Metadata URL.
5. In TechWatchAlert, Metadata › By URL, paste it, then Import. Enter groups in Groups attribute if you configured it.
6. Assignments: assign the application.

Google Workspace

1. Google Admin console: Apps › Web and mobile apps › Add app › Add custom SAML app.
2. On the Google Identity Provider details step, click Download metadata.
3. In TechWatchAlert, Metadata › By XML file, choose this file, then Import.
4. Service provider details: ACS URL = the reply URL, Entity ID = the identifier; Name ID format: EMAIL, Name ID: Basic Information > Primary email.
5. Attribute mapping (optional): First name → firstName, Last name → lastName; Group membership → groups if you want to synchronize groups.
6. Turn the app on for the relevant organizational units (User access › ON).

Manual entry and certificate rollover

Without a metadata file, Enter manually asks for the provider Entity ID, its Sign-in URL (SSO) (HTTP-Redirect binding) and its signing certificate (PEM). During a certificate rollover, paste the old and the new one separated by a blank line: both are accepted until you remove the old one. An active connection must always keep a complete provider.

Assertion attributes

• NameID: Email address (the NameID is the address) or Persistent identifier (a stable identifier; the address then comes from the email attribute, and an address renamed in the directory finds the same account).
• Email, first name, last name, groups attributes: left empty, the usual names are recognized (email, mail, firstName, givenName, lastName, surname and the Entra ID claims). Without a Groups attribute, groups are not synchronized at sign-in.
• Allow sign-in from the provider’s portal (off by default): accepts unsolicited responses started from the Okta portal or My Apps. Such a response cannot be bound to the browser presenting it: only turn it on if your users need it.

Test, then enable

Test with my account runs a real SAML sign-in without enabling SSO: you go through your provider, then come back to the page, which shows the result — the address read, the name, the groups received, the organization groups that would apply, whether the domain is verified, and every attribute received. No account is created, no session is opened. On failure, the reason is shown (see the table below).

Once the test succeeds, fill in the Mapping & access rules step (landing group, enforced SSO, automatic account creation), then click Enable SSO. These rules are the same as with OIDC.

Error messages

Message	Cause
The assertion signature is missing, invalid or uses a rejected algorithm (SHA-1)…	Unsigned assertion, certificate different from the imported one, or SHA-1 signature. Re-import the metadata after a certificate rollover.
The assertion audience is not the TechWatchAlert identifier (Entity ID).	The identifier entered at the provider does not match.
The assertion recipient is not the reply URL (ACS). / The response is addressed to another URL.	The reply URL entered at the provider does not match.
The response does not match the request sent.	Sign-in started in another tab or browser; start again from the sign-in page.
The provider’s clock is off by more than 3 minutes.	The provider server clock (ADFS…) needs resynchronizing.
This response had already been presented.	Back button or form sent twice: sign in again.
No email address in the assertion…	Non-email NameID without an email attribute: change the NameID format or the attribute.
The address received does not belong to a verified domain of the organization.	Verify the domain (step 1) or check the address sent by the provider.

Every SAML sign-in, every rejection and every settings change is written to the audit log.

SCIM 2.0 provisioning

What the directory does

• Create an account: only for an address in a verified domain. An account that already exists at this address is attached to the organization, without a duplicate. The person joins as a Member; their rights come from their groups.
• Update: first name, last name, display name, external ID. The account address itself does not change (it identifies the person in all their organizations); change it from the account if needed.
• Deactivate (active = false): access to the organization is cut at once (membership, groups, projects), without erasing anything: cases, comments and the log stay attributed. SSO sign-in does not restore access until the directory reactivates the person.
• Reactivate: the person gets back their membership and the groups the directory gives them.
• Delete: like deactivation; the person’s account remains (it may belong to other organizations).
• Groups: groups pushed by the directory grant the rights of the organization groups mapped to them.

The organization owner cannot be deactivated by the directory: the operation is rejected; transfer ownership first.

Create the token

1. Security › Provisioning (SCIM), Generate token.
2. Copy the token shown: it will never be shown again (TechWatchAlert only keeps a fingerprint of it).
3. Copy the SCIM base URL.

Renew token creates a new one and the old one stops working immediately; Revoke stops provisioning (accounts already created stay as they are). The page shows the date of the directory’s last call, the number of active accounts and groups, and the latest operations log, rejections included.

Microsoft Entra ID

1. In the enterprise application created for TechWatchAlert (or a new non-gallery application): Provisioning › Provisioning Mode: Automatic.
2. Tenant URL: the SCIM base URL followed by ?aadOptscim062020 (this parameter asks Entra for the standard-compliant behavior); Secret Token: the token. Test Connection.
3. Mappings: keep userPrincipalName (or mail) → userName, mail → emails[type eq "work"].value, givenName → name.givenName, surname → name.familyName, and the expression Switch([IsSoftDeleted], , "False", "True", "True", "False") → active. Extension attributes (department, employee number…) are accepted and ignored.
4. Scope: “Sync only assigned users and groups”; assign the users and groups.
5. Provisioning Status: On, then Save.

Entra first deactivates an account removed from the application (active = false), then deletes it after 30 days; its specifics (booleans sent as text, capitalized Replace operations, member removal through a list of values) are supported.

Okta

1. In the SAML application created for TechWatchAlert: General › App Settings › Provisioning: SCIM.
2. Provisioning › Integration: SCIM connector base URL = the SCIM base URL; Unique identifier field for users = userName; Supported provisioning actions: Import New Users and Profile Updates, Push New Users, Push Profile Updates, Push Groups; Authentication Mode = HTTP Header, Authorization = the token. Test Connector Configuration.
3. Provisioning › To App: enable Create Users, Update User Attributes, Deactivate Users.
4. Push Groups: push the groups that should grant rights.

Okta updates profiles by full replacement and deactivates with active = false: both are supported.

Google Workspace

Google Workspace only provisions apps from its catalog automatically. With Google, use the SAML sign-in above with automatic account creation (SSO access rules): an account is created at first sign-in, in the chosen landing group, and the groups sent in the assertion are applied at every sign-in.

Directory groups → organization groups

In TechWatchAlert, rights come from groups: a group grants an organization role and access to projects. Mappings link a directory group to an organization group; they serve both SAML (groups attribute) and SCIM (pushed groups).

• Directory group: its name (SOC Team), or its object ID in Entra ID. The comparison ignores case. With SCIM, the group’s name, external ID and SCIM ID are recognized.
• Organization group: any group except a partner’s. Mapping a directory group to the Administrators group makes its members administrators; the owner role is never granted or removed by the directory.
• An organization group mapped here is driven by the directory: its members are the ones the directory puts in it, and a manual addition is removed at the next synchronization. Unmapped groups are never touched.
• Changes apply at the person’s next SAML sign-in, or immediately for SCIM-provisioned accounts. A SCIM-provisioned account follows the SCIM groups, not the assertion’s groups attribute.

Caution

Map the Administrators group to a directory group whose members you strictly control: anyone the directory puts in it becomes an organization administrator.

Frequently asked questions

Can we keep OIDC and add SAML? An organization has one SSO connection, OIDC or SAML. Switching from one to the other is done under Protocol; if SSO is active, the other configuration must be complete.

What about passwords? If Enforce SSO is checked, addresses in the verified domains sign in only through the organization’s SSO, as with OIDC (see Account and sign-in).

The plan drops below Enterprise? SAML SSO no longer routes anyone (the button disappears, password sign-in resumes), and the directory gets an explicit rejection. Nothing is erased: everything resumes when you return to the plan.