Single sign-on

Overview

Single sign-on lets your people sign in to devguard through your identity provider (IdP) over SAML, and directory sync (SCIM) keeps the roster in step with your directory. Both are part of one add-on, which devguard staff switch on for your organization. While it is off, Settings → Single sign-on shows how to contact us, and Settings → Billing → Add-ons links to it.

• Sign-in: a person who signs in through the provider for the first time is created and added to the organization as an employee.
• Provisioning: a person pushed by the directory is created, or linked to their existing account by email, and added as an employee before they ever sign in.
• Roles: the directory does not assign roles. Change a role in People, as for any member.
• Name and email: the directory owns them for its people, so they cannot be edited in devguard. Directory-managed members carry a Directory badge in People.
• Leaving: when the directory disables or deletes a person, devguard deactivates the member. See Directory sync.
• Owners: the directory never deactivates an owner, and owners are exempt from Require single sign-on.

Only owners and admins see this page.

Identity provider

One SAML provider can be registered per organization. The page shows three values to copy into your IdP:

Register the provider with either the metadata XML your IdP publishes, or, for an IdP that has none, its entity ID, sign-in URL and signing certificate.

Two settings are fixed at registration: the attribute mapping (which assertion attributes carry email, name, first name and last name) and the Directory ID attribute (the attribute that matches a signed-in person to the person your directory pushed). To change either, remove the provider and register it again.

Editing a registered provider offers Replace metadata, which is what you need when your IdP rotates its signing certificate. A provider registered from a certificate offers Replace certificate instead, where you paste the new signing certificate and can change the sign-in URL.

Sign-in domains

List the email domains the provider serves, separated by commas. Each domain must be verified before it counts.

1. Add the domains to the provider.
2. At your DNS host, create a TXT record named _devguard-verification-<organization id> under each domain, with the token the page shows.
3. Select Verify on the page once the record is published.

Sign-in by domain works only after verification, so nobody can claim a domain they do not control and capture its sign-ins. The match is exact: a subdomain such as eu.example.com must be listed and verified on its own. An assertion for an address outside the verified domains is refused.

Once a domain is verified, the devguard sign-in page offers single sign-on to anyone who enters an address under it, before any code is emailed.

Directory sync

Directory sync uses SCIM to create, update and deactivate members from your directory.

• Base URL: https://<auth host>/api/auth/scim/v2. The page shows the exact URL.
• Token: generated when you connect, shown once. Store it in your IdP immediately; if you lose it, issue a new one.
• Issue a new token: adds another token while the old one keeps working, so you can switch your IdP without a gap.
• Revoke: ends one token at once. The connection stays active and members stay as they are, but your IdP stops syncing until it uses a token that still works. Select Issue a new token to replace it.
• Disconnect: removes the connection for good and cannot be undone. The members it managed become ordinary members and can be edited, deactivated and removed in devguard. If the page says the directory is still disconnecting, select Try again once the button is enabled.

Disconnecting the directory or deleting the organization signs the synced people out of every session.

What the directory changes

Directory-managed members cannot be deactivated, reactivated or removed in devguard; only their role can be changed.

Owners are never deactivated by the directory

If the directory disables or deletes an owner, the member stays active and the page warns you. Transfer ownership or change their role on the People page, and the member is deactivated.

Changes made by the sync appear in the audit log under the actor Directory sync.

Require single sign-on

Require single sign-on forces people to use the provider. It can be switched on only with a verified provider and the add-on.

• It binds every non-owner whose email is under a verified domain.
• Owners are exempt, so a broken IdP can never lock the organization out.
• On the sign-in page, an address under a verified domain goes straight to the provider. Entering it again in the same browser tab also offers the emailed code, which is how an owner gets in while the IdP is down.
• Addresses outside the verified domains, such as auditors and consultants, keep their own sign-in. The invite dialog says so.
• Switching it on does not end existing sessions; people are held at their next sign-in.
• A SAML sign-in counts as two-factor. After SAML, neither the organization's two-factor requirement nor a person's own authenticator app is asked again; the IdP is responsible for the second factor.
• A held person can still change their password and manage two-factor settings.

Microsoft Entra ID

Sign-in

1. In Entra ID, create an enterprise application (a non-gallery application) for devguard.
2. Open Single sign-on and choose SAML.
3. Set Identifier (Entity ID) to the Identifier (entity ID) shown in devguard and Reply URL to its Reply URL (assertion consumer service URL).
4. Leave Attributes & Claims at its defaults. Entra ID always sends objectidentifier, which devguard uses as the directory ID.
5. Download the Federation Metadata XML and paste its contents on the Metadata XML tab of the provider form in devguard.
6. Keep the Directory ID attribute at its default, http://schemas.microsoft.com/identity/claims/objectidentifier, so the person pushed by provisioning matches the person who signs in.
7. Assign the users or groups that should have access.

Provisioning

1. Open Provisioning and set the mode to Automatic.
2. Enter the base URL as the Tenant URL and the token as the Secret Token.
3. Select Test connection.
4. Check the attribute mappings for users (listed below).
5. Switch provisioning on.

The user attribute mappings are:

Unassigning a user, disabling the account or deleting it in Entra ID all end up as a deactivated member in devguard. Assigning the user again, or enabling the account, reactivates it.

OneLogin

Add a SAML application, set the audience to the Identifier (entity ID) and the recipient and ACS URL to the Reply URL, and copy the issuer URL and SAML 2.0 endpoint into the provider form. For provisioning, add the SCIM base URL and token on the application's Configuration tab and enable provisioning.

Okta

Create a SAML 2.0 application, use the Reply URL as the single sign-on URL and the Identifier (entity ID) as the audience URI, and copy the sign-on URL and metadata into the provider form. For provisioning, enable SCIM provisioning on the application, enter the base URL, choose bearer-token authentication with the token, and enable create, update and deactivate users.