ArchDocs
Start free

Single sign-on

Single sign-on lets colleagues sign in with their company accounts. Set up and test the connection before making SSO mandatory.

Configuring SSO requires Enterprise and sso:manage.

The settings page also needs billing:read to check the plan and roles:read to list default roles.

Open the organization name in the sidebar, then select Organization Settings > Single sign-on.

Verify your company domain

  1. In Verified domains, enter your company domain and select Add domain.
  2. At your DNS provider, publish the exact TXT name and TXT value shown for that domain. Use the copy icons to avoid changing the challenge.
  3. After DNS propagation, select Verify. If the check fails, read the error beside the record, correct the DNS entry and try again.

An unverified domain doesn't route people to SSO. Verifying a domain alone doesn't enable the connection.

Connect SAML

  1. Set Protocol to SAML 2.0.
  2. On Metadata URL, enter your identity provider's HTTPS URL in Identity provider metadata URL and select Import metadata. You can instead use Manual to enter Sign-on URL, Identity provider issuer and Signing certificates.
  3. Under Provisioning defaults, choose a Default role for new members, then select Save SAML connection.
  4. Copy ACS URL and Entity ID from Service provider details into your identity provider's application. If your identity provider accepts service provider metadata, give it the Metadata URL from Service provider details. This is the ArchDocs URL, not the one you entered in step 2.
  5. Configure the identity provider to send the person's email address. Set Email attribute or Name attribute if you need to map different attributes, then save the connection again.

SAML assertions must be signed. Identity provider signs the whole response controls an additional signature check; turning it off doesn't allow unsigned assertions.

For certificate rotation, import metadata again with the complete certificate set. If you replace certificates manually, paste the complete replacement set into Signing certificates. Leaving that field empty keeps the stored certificates.

Connect OIDC

  1. Create an OIDC web application at your identity provider. Set its redirect URI to your ArchDocs API address with the path /auth/sso/oidc/callback.
  2. Set Protocol to OpenID Connect in ArchDocs.
  3. Enter Issuer URL, Client ID and Client secret. Use the issuer URL itself, rather than the discovery document URL.
  4. Set Scopes. The initial value is openid profile email; ArchDocs always includes openid in sign-in requests.
  5. Choose a Default role under Provisioning defaults. Set Email attribute or Name attribute if the provider uses different claim names.
  6. Select Save OIDC connection.

On later edits, leave Client secret blank to keep the stored secret.

Enable sign-in and provision members

Turn on SSO sign-in under Enable single sign-on, then complete an SSO sign-in with a company account. Password and Google sign-in remain available until you require SSO.

On first SSO sign-in, ArchDocs links an existing account with the same email address or creates an account. Later sign-ins use the linked account. ArchDocs adds a person who isn't yet a member with the Default role, or Viewer if none is set. This requires free member capacity and an email domain verified for this organization.

This is just-in-time provisioning at sign-in. Changing the default doesn't change existing members' roles.

Require SSO and keep recovery access

  1. Under Break-glass password access, enable Password access for an administrator who has org:manage. This bypass access lets them sign in with a password while SSO is required. Keep that account's password and recovery email usable.
  2. Confirm that an SSO sign-in succeeded within the last 24 hours and that the connection is enabled.
  3. Under Require single sign-on, turn on Mandatory for verified domains.

Members on verified domains must then use SSO instead of password or Google sign-in, unless they have bypass access. If no administrator has bypass access when you require SSO, ArchDocs grants it to the Owner automatically. While SSO is required, you can't remove bypass access from the last administrator with org:manage who has it; give another administrator bypass access first. Password reset remains available, but it doesn't bypass the SSO requirement.

After a downgrade below Enterprise, enabled SSO connections still work for sign-in, the settings become read-only, and SSO is no longer mandatory.