Your organization can sign on with a single click (and avoid security headaches) thanks to available Single Sign-On for all SAML 2.0 standard IdPs.
Single Sign-On lets users access Arcules using your organization's user database or Identity Provider rather than Arcules managing separate passwords for the users.
Please note, this enables SSO as an additional Identity Provider, it does not remove standard email/password authentication.
Below is a list of tested identity providers but other identity providers supporting SAML 2.0 should also apply:
Google
Okta
Auth0
Two-Factor Authentication (2FA) can be supported if enabled via the identity providers.
SSO controls how users sign in — it does not create user accounts.
Enabling SSO does not automatically provision users in Arcules. Every person who will sign in with SSO must still be added on the People page and given a role, exactly as they would be without SSO. SSO changes what happens when they sign in; it does not change whether an account exists for them.
Set up and enable SSO before you add and invite your users.
Recommended order of setup
Complete these in order:
Add and validate your domain (Step 1 below)
Configure and enable SSO (Step 2 below)
Add your users on the People page and assign their roles
Prerequisites
Access to your domain's DNS Management Tool.
IT Manager level access to your organization's Arcules account.
All users who will sign in with SSO must have email addresses at the exact domain you verify. Subdomain addresses are not supported — see Step 1.
Use the following values for relevant SAML 2.0 settings to setup in the Identity Provider (IdP) of choice:
Single Sign On URL: (same for Recipient/Destination URL)
EU
JP/APAC
https://manage.jp.arcules.com/federation/login/saml/assert
Audience Restriction:Americas
arcules.com
EU
eu.arcules.com
JP/APAC
jp.arcules.com
Note: This field may have a different name depending on the IDP. In Azure AD for example, it is calledIdentifier (Entity ID).
Name ID Format: EmailAddress
Available Attribute Mapping:
- firstName
- lastName
- image (url to the image file)
Ensure your organization SAML 2.0 IdP is setup with a valid IdP Metadata XML. You can use either a URL to the IdP Metadata XML that you host or upload the Metadata File. Your IdP metadata XML contains your identity provider’s signing certificate, which has an expiration date. When that certificate is renewed or rotated, you will need to update it by replacing the metadata — see Renewing or Replacing an Expiring IdP Certificate below.
Note: If you are using a manually edited metadata xml file for SSO configuration, the <ds:X509Certificate> field needs to be all one line with no white space.
Example:
<ds:X509Certificate>MIIEHDCCA...CxQp8m</ds:X509Certificate>
Step 1: Add and validate a domain
In order to prove that you are the owner/administrator of a domain, Arcules will have to validate the domain. To do so, you need to add a unique key provided by Arcules to your DNS configuration. This domain must match the domain used for the email addresses used for SSO.
Go to Settings > Identity & Access Management.
At the top you will see the Verify Domain section
Click + New Domain and enter the domain email address ( myemail@mycompany.com)
Click ADD
Click VERIFY, then copy the TXT key
Open your DNS Management Tool (e.g. Google Domains, GoDaddy, ...)
Paste the key into the TXT field
Wait until your DNS configuration changes (Note: this could take up to 72 hours)
To view detailed instructions on how to verify a domain with a TXT record, see the following examples by Google Domains here, or GoDaddy here.
Step 2: Configure & enable SSO
Now that you have verified a domain, you can enable the SSO feature.
Go to Settings > Identity & Access Management.
Search for the section entitled SAML Single Sign-On.
Locate the domain address you want to enable SSO for and toggle it on.
Select your Setting Method. You can upload your IdP metadata XML file or add the URL to the file that you host publicly.
Click SAVE
To disable SSO, simply toggle off SSO per domain.
Repeat steps 1 and 2 if you want to enable SSO for additional domains within your organization.
Step 3: Add and Invite Your Users
With SSO enabled, add each person who needs access:
Go to the People page.
Add the user using the email address at your verified SSO domain. The email address must match the NameID your identity provider sends, exactly.
Send the invite. Clicking Send Invite activates the user’s account. Because SSO is enabled for their domain, the emailed link takes them to the Arcules login page, where they enter their email address and are redirected to your identity provider.
Users who are not added here cannot sign in, even if they authenticate successfully with your identity provider.
Renewing or Replacing an Expiring IdP Certificate
Your identity provider’s SAML signing certificate expires periodically, depending on your provider’s policy. What you need to do depends on which Setting Method your domain uses, shown on the domain card under Settings > Identity & Access Management.
If you use a metadata URL — no action needed
A renewed certificate published at that URL is picked up automatically. You do not need to re-enter the URL.
If you use a metadata file — upload the renewed metadata
An uploaded file is a snapshot. It does not update when your identity provider renews its certificate, so you must replace it before the old certificate stops being used, or SSO logins will fail.
Arcules accepts the certificate only inside a complete IdP metadata XML file. Standalone .cer, .crt, .pem, or .pfx files cannot be uploaded.
Before you start
Export the updated metadata XML from your identity provider after the new certificate has been issued and assigned to the Arcules application.
Replacing the metadata interrupts SSO for that domain from the moment you remove the existing entry until you save the new one. Do this during a maintenance window, and make sure at least one IT Manager can sign in with their Arcules email and password.
Steps
Go to Settings > Identity & Access Management.
Search for the section entitled SAML Single Sign-On and expand the domain whose certificate you are renewing.
Click the trash icon next to the current metadata file to remove it.
Select Use Metadata file as your Setting Method, then click CHOOSE FILE and select your updated metadata XML.
Click SAVE.
Verify immediately: sign in from a private or incognito window with a user account on that domain. You should be redirected to your identity provider and returned to Arcules successfully.
Leave the domain toggled on throughout — turning SSO off is not required and will change how users on that domain are prompted to sign in.
Staying ahead of expiry
Check your signing certificate’s expiration date in your identity provider — most display it in the SAML or SSO settings for your Arcules application, alongside the option to renew it. If tracking renewals manually is a burden, consider switching this domain to a metadata URL instead.
User Login page
To login with SSO, enter the email address associated with the SAML account and click on Next.
Notes on Setting up in ADFS
Please note we highly recommend using Azure AD to work with SAML 2.0 integration, and we do not actively support implementing SAML 2.0 directly via ADFS.
However, below information might help in getting set up inside ADFS:
SAML Endpoint - https://manage.arcules.com/federation/login/saml/assert
Relying Party Identifier - arcules.com
For everything else, please use default values.
For claim issuance policy, you might need two rules:
Rule 1 – from Active Directory, pass Email-addresses as Name ID
Rule 2 - a custom rule with this info:
c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"]
=> issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer =c.Issuer, OriginalIssuer =c.OriginalIssuer, Value = c.Value,ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress");
Note for Microsoft Azure/Authenticator when using Mobile
If you are using Microsoft Azure/Authenticator as your SSO provider, you need to have the Microsoft Authenticator app installed on your iOS or Android device, if you want to access Arcules via mobile.
Troubleshooting
Problem: User signs in with the identity provider successfully but cannot access Arcules.
The user authenticated, but no Arcules account exists for that email address. Enabling SSO does not create accounts. Go to the People page and add the user, assign their roles, then send an invite to activate the account. Confirm the email address on the People page matches the NameID from your identity provider exactly.
Problem: A user is asked for an Arcules password instead of being sent to our identity provider.
Check the domain of that user’s email address against the domains you’ve verified under Settings → Identity & Access Management.
If the address is at a subdomain of a verified domain (user@eu.company.com vs. verified company.com), SSO does not apply to it and the user falls back to standard Arcules sign-in. Verify the subdomain as its own domain to enable SSO for those users.
Problem: A user is returned to the login page.
Same cause: the email address returned by your identity provider is at a domain that isn’t verified and SSO-enabled in Arcules. Confirm the address your identity provider sends in the NameID matches a verified domain exactly.
Problem: My domain has been stuck as unverified / “pending” and never completes.
Almost always, the TXT record exists but was created under the wrong name. Arcules looks for the record at the exact domain you entered — if you added xyz.com, the record’s name must be xyz.com itself, not a subdomain of it such as arcules.xyz.com.
To see what your DNS is actually publishing, run this from a terminal, replacing xyz.com with your domain:
dig +short TXT xyz.com
If your arcules-domain-verification=... key appears in the output, DNS is correct and verification will complete shortly. If the output is empty or doesn’t contain the key, the record isn’t where Arcules is looking. In your DNS tool, check the name your record was actually saved under — the two most common outcomes are arcules.xyz.com (from entering arcules in the Host or Name field) and xyz.com.xyz.com (from entering the full domain in a field that already appends it).
To fix it, edit the record so it applies to the domain itself rather than to a name beneath it. How you express that depends on your DNS provider — most use @ for this, some require the field to be left empty, and your provider’s own documentation for “root domain” or “apex” TXT records will say which. Re-run the command above to confirm the key is now returned for xyz.com.
Adding this record won’t interfere with any existing TXT records on your domain, such as SPF.
You do not need to remove and re-add the domain, and you do not need a new key. Arcules re-checks pending domains automatically every few minutes, so verification completes on its own once the corrected record has propagated. Deleting and re-adding the domain issues a new key and means redoing the DNS record.
Problem: All users on a domain suddenly cannot sign in with SSO, or the identity provider reports a signature validation error.
If your domain uses an uploaded metadata file, your IdP’s signing certificate has most likely been renewed or rotated while Arcules still holds the old one — replace the metadata (see Renewing or Replacing an Expiring IdP Certificate). If your domain uses a metadata URL, check that the URL is publicly reachable and returns valid metadata.