This guide walks through configuring Enterprise SSO between Okta and the Cloudmersive Management Portal from start to finish. It covers both sides: the Cloudmersive portal and the Okta Admin Console. Follow the steps in order. The whole process takes about fifteen minutes.

Note: SAML SSO must be enabled on your Cloudmersive account before you begin. Work with your Cloudmersive representative to enable the feature.

Before you start

You will need:

• A Cloudmersive account that is the Master Administrator of your organization. Only the Master Administrator can configure SAML SSO.
• A verified email address on that account, on your organization's own email domain. For example, if your users sign in as name@contoso.com, your account's email must end in @contoso.com and must be verified. Public email domains such as gmail.com cannot be used.
• Okta administrator access to create an application integration and assign users to it.
• Two browser tabs: one signed in to https://portal.cloudmersive.com and one signed in to your Okta Admin Console.

How it fits together: Okta is the identity provider. Cloudmersive is the service provider. You will copy two values from Cloudmersive into Okta, then copy three values from Okta into Cloudmersive. When a user signs in with Enterprise SSO, Cloudmersive sends them to Okta to authenticate and Okta sends a signed response back.

Part 1: Get the Cloudmersive service provider values

1. Sign in to https://portal.cloudmersive.com as the Master Administrator.
2. Open Security Center from the home page and click Manage Authentication. You can also reach Manage Authentication from Settings.
3. Under SAML Single Sign-On, click Manage SAML SSO.
4. If the page asks you to verify your email address, click Verify Email Address, complete the verification, and return to this page.
5. If the page shows Contact Sales, the feature is not yet enabled on your account. Contact your Cloudmersive representative and return once it is enabled.
6. Confirm the Organization and Domain shown at the top of the page. The domain is taken from your own email address and cannot be typed in. If you administer more than one organization, choose the correct one from the dropdown.
7. Under Step 1, note the two values you will enter into Okta. Keep this tab open.
   • Service Provider Entity ID / Audience URI
   • Assertion Consumer Service (ACS) URL

Part 2: Create the SAML application in Okta

1. In the Okta Admin Console, go to Applications, then Applications.
2. Click Create App Integration.
3. Select SAML 2.0 and click Next.
4. On the General Settings page, enter an App name such as Cloudmersive. A logo is optional. Click Next.
5. On the Configure SAML page, fill in the General section:
   • Single sign-on URL: paste the Assertion Consumer Service (ACS) URL from Cloudmersive.
   • Leave "Use this for Recipient URL and Destination URL" checked.
   • Audience URI (SP Entity ID): paste the Service Provider Entity ID from Cloudmersive.
   • Default RelayState: leave blank.
   • Name ID format: choose Persistent.
   • Application username: choose Okta username.
   • Update application username on: leave as Create and update.
6. Still on the Configure SAML page, add the attribute statements in the Attribute Statements section. Okta offers two ways to define them and either produces the same result for Cloudmersive.
   • Expression-based (the Add expression button). Each row has a Name and an Expression. Expression-based statements reference the user profile with the user.profile prefix. Add:
     • Name: email. Expression: user.profile.email. This one is required.
     • Name: firstName. Expression: user.profile.firstName. Optional.
     • Name: lastName. Expression: user.profile.lastName. Optional.
   • Legacy (click Show legacy configuration if it is collapsed). Each row has a Name, a Name format and a Value. Add the same three rows with Name format set to Unspecified and the Value set to user.email, user.firstName and user.lastName. Note that the legacy fields use user.email without the profile segment; using user.email in an expression-based row gives the error "Invalid property email in expression".
     The attribute names email, firstName and lastName must be typed exactly as shown, in that capitalization.
7. Leave the Group Attribute Statements section empty. Click Next.
8. On the Feedback page, choose "I'm an Okta customer adding an internal app" and click Finish.

Why Persistent for the Name ID: the Name ID is the permanent identifier Cloudmersive uses to recognize a user. Persistent means Okta generates a stable, opaque value that never changes and is never reused, so a departed employee's identity cannot be inherited by a new hire who is later given the same email address. The user's email address is sent separately in the email attribute. Do not choose EmailAddress as the Name ID format.

Part 3: Collect the Okta values

1. Open the application you just created and go to the Sign On tab.
2. In the SAML Signing Certificates section, find the active certificate and open its Actions menu.
3. Click View IdP metadata. A new tab opens with the metadata XML. Select all of the text and copy it. This is the fastest way to configure Cloudmersive, because the metadata contains all three values Cloudmersive needs.
4. If you prefer to enter the values by hand, click View SAML setup instructions instead and note:
   • Identity Provider Single Sign-On URL
   • Identity Provider Issuer
   • X.509 Certificate

Part 4: Enter the Okta values in Cloudmersive

1. Return to the Manage SAML SSO tab in the Cloudmersive portal.
2. Under Step 2, either:
   • Paste the metadata XML into the metadata box and click Import from metadata. The three fields below fill in automatically. Check that the Single Sign-On URL starts with https:// and points at your Okta domain.
   • Or fill in the fields directly:
     • Identity Provider Entity ID (Issuer): the Okta Identity Provider Issuer.
     • Identity Provider Single Sign-On URL: the Okta Identity Provider Single Sign-On URL.
     • Identity Provider Signing Certificate: the Okta X.509 Certificate. Paste the full certificate text. It is fine to include the BEGIN CERTIFICATE and END CERTIFICATE lines.
3. Leave Secondary Signing Certificate blank. It is only used when rotating certificates.
4. Make sure Enable SAML sign-in for this domain is checked.
5. Click Save SAML Configuration.
6. You are returned to Manage Authentication. The SAML Single Sign-On section now reads "Configured for your-domain (enabled)".

If the save is refused, the message on the page explains why. The most common causes are a Single Sign-On URL that does not start with https://, a certificate that was pasted incompletely, or a domain that is already configured by another Cloudmersive organization.

Part 5: Assign users in Okta

1. In the Okta Admin Console, open the Cloudmersive application and go to the Assignments tab.
2. Click Assign and choose Assign to People or Assign to Groups.
3. Select the users or groups who should be able to sign in to Cloudmersive and click Assign, then Done.

Only assigned users can complete an Enterprise SSO sign-in. Users who are not assigned see an error from Okta.

Part 6: Test the sign-in

Test with a user who does not yet have a Cloudmersive account. This is the cleanest test because it exercises the full first-time flow.

1. In a private browser window, go to https://portal.cloudmersive.com/login.
2. Click Sign in with Enterprise SSO.
3. Enter the test user's work email address, for example testuser@contoso.com, and click Continue.
4. You are redirected to Okta. Sign in as the test user, completing any MFA your Okta policies require.
5. You are returned to Cloudmersive. Because this address has no account yet, Cloudmersive sends a verification email to that address. Open the email and click the verification link in the same browser you started from. The link expires after ten minutes.
6. The account is created and you land on the portal home page, signed in.
7. Sign out, then repeat steps 1 through 4. This time there is no verification email. You go straight from Okta to the portal home page, signed in.

The verification email is only sent the first time a new address signs in. After that, sign-in is direct.

Part 7: Existing Cloudmersive accounts

Users who already have a Cloudmersive account are not switched to Enterprise SSO automatically. They continue to sign in with their existing method, such as a password or Sign in with Microsoft. If such a user tries Sign in with Enterprise SSO, the login page explains that an account already exists for that address.

To switch existing accounts to Enterprise SSO, open a support case with Cloudmersive and list the email addresses to switch. Cloudmersive Support verifies the request and completes the change. You can include your whole user list in one case.

New users at your domain need no action. Their accounts are created on their first Enterprise SSO sign-in after they click the verification link, as in Part 6.

Part 8: Organization membership

Enterprise SSO controls how a user signs in. It does not add anyone to your organization or grant any roles. Invite users to your organization from Access Management exactly as before. A user who receives an invitation can accept it after signing in with Enterprise SSO, and their account is created on the way if they did not have one.

Certificate rotation

Okta signing certificates expire. The Manage SAML SSO page shows the expiration date of the certificate currently in use. When Okta issues a new certificate:

1. In Okta, on the application's Sign On tab, generate the new certificate but do not activate it yet.
2. In Cloudmersive, open Manage SAML SSO, paste the new certificate into Secondary Signing Certificate, and click Save SAML Configuration. Both certificates are now accepted.
3. In Okta, activate the new certificate.
4. In Cloudmersive, paste the new certificate into Identity Provider Signing Certificate, leave Secondary Signing Certificate blank, and save. The old certificate is removed.

Disabling or removing Enterprise SSO

To pause Enterprise SSO without losing the configuration, open Manage SAML SSO, uncheck Enable SAML sign-in for this domain, and save. Users see a message that Enterprise SSO is not configured for their domain until you re-enable it.

To remove the configuration entirely, click Remove SAML Configuration and confirm. The page shows how many users are linked to this configuration and warns if any of them have no other sign-in method. Accounts are not deleted and other sign-in methods are unaffected. Accounts that were created through Enterprise SSO and have no other sign-in method will be unable to sign in until the configuration is restored and Cloudmersive Support re-enables them, so contact Cloudmersive Support before removing the configuration if you intend to keep those users.