SAML SSO Optional feature

In SAML SSO under organization settings, you register a SAML identity provider (IdP) so that people with an email address on a verified domain can sign in through it. Only an organization owner can make these changes.

TIP

This is an optional feature. Depending on your contract, it might not be available.

How SAML SSO works

You turn on SSO for each domain verified in Domains. After you turn it on, people who sign in with an email address on that domain see Sign in with SSO. They authenticate with your organization's IdP, such as Okta or Microsoft Entra ID, and are signed in to Codatum.

• SSO applies to every account with an email address on the domain, whether or not the account belongs to a workspace in your organization.
• Password and Google sign-in remain available after you turn on SSO.
• For the sign-in flow on the user side, see Signing in with SSO.

You set up SSO in the following order.

Adding an identity provider

The following prerequisites apply.

• Only an organization owner can make these changes.
• Verify the domain that will use SSO in Domains.
• You need to be able to create a SAML app in your IdP.
• The SAML SSO menu is shown when this feature is available.

1. Open the workspace icon at the top of the global nav > Organization settings > SAML SSO.
2. Select Add identity provider.
3. In Name, enter a name that identifies the IdP, then select Add.

The new IdP appears in the list as Not configured. Under Set these in your IdP, the SP entity ID and ACS URL to register in your IdP are shown.

Setting up your IdP

Create a SAML app in your IdP and register the Codatum values. Every IdP needs the following three settings.

Setting in your IdP	Value
SP entity ID (audience)	The SP entity ID shown in Codatum.
ACS URL (reply URL)	The ACS URL shown in Codatum.
NameID	The user's email address. The format is urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.

If the NameID isn't an email address, sign-in fails. You also need to assign users to the app in your IdP.

After you create the app, note the following three values from your IdP. You use them in Entering IdP settings.

• The IdP entity ID (issuer)
• The SSO URL
• The X.509 signing certificate (PEM format)

Screen names in your IdP might change. For details, see your IdP's documentation.

Okta

1. In the Okta admin console, open Applications > Applications > Create App Integration.
2. For Sign-in method, select SAML 2.0.
3. Enter any name in App name.
4. In Configure SAML, enter the following:
   • Single sign-on URL: the Codatum ACS URL
   • Use this for Recipient URL and Destination URL: on
   • Audience URI (SP Entity ID): the Codatum SP entity ID
   • Name ID format: EmailAddress
   • Application username: Email
5. Save the app, then in Assignments, assign the users or groups who will sign in.
6. On the Sign On tab, note the Sign on URL, the Issuer, and the signing certificate from the SAML details.

In Codatum, enter the Issuer in IdP entity ID and the Sign on URL in SSO URL.

Microsoft Entra ID

The labels below are the names shown when the Microsoft Entra admin center is displayed in English.

1. In the Microsoft Entra admin center, open Enterprise applications > New application > Create your own application.
2. Select Integrate any other application you don't find in the gallery (Non-gallery), then create the app.
3. In the app's Single sign-on, select SAML.
4. In Basic SAML Configuration, enter the following:
   • Identifier (Entity ID): the Codatum SP entity ID
   • Reply URL (Assertion Consumer Service URL): the Codatum ACS URL
5. In Attributes & Claims, set the format of Unique User Identifier (Name ID) to Email address, and choose a source attribute that holds the user's email address.
   • If the user principal name (user.userprincipalname) differs from the email address, choose user.mail.
6. In SAML Certificates, download Certificate (Base64).
7. In Set up (app name), note the Login URL and the Microsoft Entra Identifier.
8. In Users and groups, assign the users or groups who will sign in.

In Codatum, enter the Microsoft Entra Identifier in IdP entity ID and the Login URL in SSO URL. In X.509 certificates, paste the contents of the downloaded certificate.

Entering IdP settings

1. Open the workspace icon at the top of the global nav > Organization settings > SAML SSO.
2. For the IdP, select Enter IdP settings. For an IdP that already has settings, select Edit.
3. Enter IdP entity ID, SSO URL, and X.509 certificates, then select Save.

After you save, the IdP status becomes Draft, and Domains that use SSO appears.

Testing sign-in and enabling SSO

For each domain, you test sign-in first and then enable SSO. A test sign-in doesn't change how users sign in.

1. Open the workspace icon at the top of the global nav > Organization settings > SAML SSO.
2. In Domains that use SSO for the IdP, select Test sign-in.
3. In the window that opens, sign in to your IdP as a user with an email address on the domain where you want to enable SSO.
4. Confirm that a success message appears and that the domain status changes to Tested.
5. For that domain, select Enable SSO, then select Enable SSO in the confirmation dialog.

After you enable it, the domain status becomes SSO enabled and the IdP status becomes Active. To use SSO on more than one domain, test and enable each domain separately.

You can follow the same steps for a domain that already uses SSO with another IdP. After you switch, people on that domain sign in with the new IdP. To migrate to a new IdP, add and test the new IdP, switch the domain to it, then disable the old IdP.

Stopping SSO

1. Open the workspace icon at the top of the global nav > Organization settings > SAML SSO.
2. For the domain, select Stop SSO, then select Stop SSO in the confirmation dialog.

After you stop it, people can't sign in with SSO using an email address on that domain. The test result is kept, so you can select Enable SSO again without testing again.

Disabling and deleting an identity provider

1. Open the workspace icon at the top of the global nav > Organization settings > SAML SSO.
2. For the IdP, select one of the following:
   • Disable: In the confirmation dialog, select Disable identity provider.
   • Delete: In the confirmation dialog, select Delete identity provider.

When you Disable an IdP, sign-in and test sign-in with it stop. SSO stops on every domain that used the IdP. The settings and test results are kept. Selecting Enable returns the IdP to Draft. To resume SSO, select Enable SSO again for each domain.

Delete can't be undone. You can't delete an Active IdP, so disable it first. To use a deleted IdP again, add it as a new IdP and register the new SP entity ID in your IdP.

Rotating certificates

When you renew the IdP's signing certificate, register the old and new certificates side by side so that sign-in keeps working during the switch.

1. For the IdP, select Edit, add the new certificate with Add certificate, then select Save.
2. In your IdP, switch the signing certificate to the new one.
3. Select Edit again, select Remove for the old certificate, then select Save.

Changing only the certificates doesn't clear test results.

Display and actions

Each IdP shows the following items.

Display / action	Description
Add identity provider	Adds an IdP with a name. The SP entity ID and ACS URL are issued after you add it.
Status	Not configured, Draft, Active, or Disabled (see Identity provider status).
SP entity ID	The SP entity ID to register in your IdP. It's unique to each IdP and can't be changed.
ACS URL	The reply URL to register in your IdP.
IdP entity ID	The entity ID (issuer) issued by your IdP.
SSO URL	The SSO URL of your IdP. Only https URLs are accepted.
Certificates	The number of registered X.509 certificates.
Test sign-in	Signs in to your IdP and checks whether this IdP can be used for the domain of that email address.
Domains that use SSO	The organization's verified domains and their status for this IdP (see Domain status).
Enable SSO	Makes this IdP the SSO destination for a Tested domain.
Stop SSO	Stops SSO for a domain that shows SSO enabled.
Edit	Changes the name and IdP settings.
Enable	Returns a Disabled IdP to Draft.
Disable	Stops sign-in with the IdP. The settings are kept.
Delete	Deletes the IdP. Not shown for an Active IdP.
Resync	Shown when saved settings haven't been applied. Selecting it applies them again.

Identity provider status

Status	Description
Not configured	Only the name is registered. You can't test sign-in or enable SSO.
Draft	IdP settings are entered, and SSO isn't enabled on any domain. You can test sign-in.
Active	SSO has been enabled on at least one domain. The IdP stays Active even if you later stop SSO on the domain.
Disabled	Sign-in and test sign-in aren't available. The settings are kept.

Domain status

Status	Description
Not tested	No test sign-in has been done with this IdP.
Tested	A test sign-in with this IdP succeeded. You can select Enable SSO.
SSO enabled	This IdP is the SSO destination for the domain.
TXT record not confirmed	The domain was tested, but SSO can't be enabled because the domain recheck couldn't confirm the TXT record.

A domain that uses SSO with another IdP shows SSO is enabled with "(IdP name)".

Constraints

• A domain can use only one IdP for SSO. One IdP can be used for multiple domains in the organization.
• An organization can register up to five IdPs. Deleted IdPs don't count.
• Name can be up to 100 characters.
• Each IdP can have one to three X.509 certificates. Enter one PEM-format certificate per field. Expired certificates can't be registered.
• Changing IdP entity ID or SSO URL clears the IdP's test results, and its domains return to Not tested. SSO doesn't stop on domains where it's already enabled.
• Revoking a domain clears SSO and test results for that domain.
• While a domain shows the TXT record not confirmed warning, people can't sign in with SSO using an email address on that domain, and you can't enable SSO for it.
• Sign-in starts from the Codatum sign-in page. Sign-in started from the IdP, such as from the IdP's dashboard, isn't supported.
• After the feature becomes unavailable under your contract, you can still open the list from the menu if IdPs already exist. You can disable and delete existing IdPs. You can't add IdPs or change their settings.

The limits are also listed in Limits.

When test sign-in doesn't succeed

The test sign-in result appears inside the IdP card. Check the following based on the message.

1. If sign-in with the IdP failed, confirm that the SP entity ID and ACS URL in your IdP match what Codatum shows.
2. Then confirm that IdP entity ID, SSO URL, and the certificate entered in Codatum match the values in your IdP.
3. If the message says the NameID isn't an email address, set the NameID to the email address in your IdP.
4. If the message says the domain isn't a verified domain, sign in again with an email address on one of your organization's verified domains.
5. If the message says the TXT record couldn't be confirmed, restore the TXT record and verify the domain again in Domains.

If the message says the sign-in window was blocked, allow pop-ups for Codatum in your browser, then select Test sign-in again.

When "The latest settings have not been applied" appears

This means saved settings couldn't be applied to the settings used for sign-in. The settings themselves are saved.

1. Select Resync.
2. If the message doesn't disappear, wait a while, then select Resync again.

If the message still doesn't disappear, contact Codatum support.