Skip to main content

SSO (Single sign-on) Configuration Guide for IT Admins

Setting up Single-Sign-on (SSO) to manage access to Orchestrator via your preferred IdP

Team Celona avatar
Written by Team Celona
Updated over 4 months ago

SSO provides a seamless login experience to the Orchestrator for users whose identity is managed by an external authentication source. This is based on the SAML 2.0 Authentication and Authorization framework - an XML-based open standard for exchanging authentication and authorization data between an application service provider and an identity management system used by an enterprise.

Orchestrator currently supports “Service Provider (SP)” initiated SSO. “Service Provider” is the provider of a business function or service (in this case, the Celona Orchestrator). The Orchestrator requests and obtains an identity assertion from the customer’s Identity Provider (IDP). Based on this assertion, the Orchestrator allows users to access the service.

The current implementation requires the customer’s Admin to configure an Orchestrator Launch URL in the IDP Portal (or an embedded link in the Intranet page) from which users can launch into the Orchestrator UI.

In addition to Service Provider (SP) and Identity Provider (IDP), the key elements of SSO are the following:

  • SAML Request: The authentication request that is generated when a user tries to access Orchestrator

  • SAML Assertion: The authentication and authorization information issued by the customer’s IDP (like Okta, etc.) to allow access to the service offered by the service (Orchestrator)

  • Metadata: Data in the XML format that is exchanged between the trusted partners (IDP and Orchestrator) for establishing interoperability and integrity. Customers could, if needed, check the integrity of the request through signature verification using the public cert of Orchestrator shared in metadata. However, it’s optional.

  • SAML Attributes: The attributes associated with the user (Email, Account Name, Role, etc.) associated with the specific customer account

    • The SAML attributes must be configured on the IDP according to specifications associated with a user account in Orchestrator

    • These attributes are included in the SAML assertion when Orchestrator sends a SAML request to the IDP

This feature lets a customer admin configure the Orchestrator's launch URL for all your organization's users. This can be done via the IDP Portal (or an embedded link on the Intranet page).
​

Configuration in Celona Orchestrator (CSO)

Step 1: Set CSO as a Service Provider (SP)

  1. Login: Use SuperAdmin, GlobalAdmin, or Admin credentials to access CSO.

  2. Navigate: Go to Customer Admin Settings > SSO Settings Menu.
    ​

  3. Enable Service Provider:

    • Click on the Service Provider radio button.

    • If no metadata exists, you will see the option to ENABLE SERVICE PROVIDER.

    • Click to generate the SP Metadata.

    • Download the generated XML metadata file for reference.
      ​

Step 2: SSO Configuration on the IDP portal

Please note that Celona SSO can be integrated with any IDPs that follow the SAML 2.0 protocol.

For more information on the steps to configure Okta and Azure IDP portal, refer to SSO Configuration on Okta and SSO Configuration on Azure.

SAML Attributes Guide (common for any IDP)

  • The following attributes must be sent in the assertion statement -

Attribute Name

Mandatory

Value Description and Restrictions

firstName

Yes

alphanumeric, hyphen, apostrophe, underscore, space, and dot with a max limit of 32

lastName

Yes

alphanumeric, hyphen, apostrophe, underscore, space, and dot with a max limit of 32

mobile

No

E.164 format (example: +11234567890)
plus sign followed by a maximum of 15 digits; the first digit should not be 0

email

Yes

  • Must be a corporate email, personal email domains are not allowed

  • The login to the Orchestrator is either through SSO or direct credentials, but not both. If you need both, please use different email ids for different logins

  • If only one corporate email address must be used, choose only one avenue as the primary login. If SSO is chosen as the primary login, ensure that there is no existing non-SSO user account on the Orchestrator that has an email matching that of SSO

ssoId

Yes

  • Unique identifier of a user profile on IDP

  • The ssoId has the letter ‘I’ as an Identifier and not the lower-case letter ‘L’

authzRole

Yes

  • User role on IDP

  • IDP will automatically send the value of the user’s role based on the group the user is assigned to

  • To avoid errors when adding role mapping on the Orchestrator UI, enter the group name exactly as it appears (case-sensitive) in the IDP Role field in Step 4

accountName

Yes

  • Set this attribute value exactly as “Account Name” on the Orchestrator -> Account Info

  • During “Just-in-Time” provisioning, the user will be created in this Account Name on the Orchestrator

orgScope

Yes
​(for SSO configuration at MSP)

No
​(for Independent Enterprises)

  • User's access to enterprises (tenants) under MSP

  • If a user has access to all enterprises under an MSP, i.e., a user is mapped to both groups, “ALL” and individual enterprises, when Orchestrator receives this attribute value containing both Celona_ALL and Celona_AcctNames(1,2,3), the precedence is given to Celona_ALL.

  • The attribute should follow the format 'prefix_accountName,' where the accountName is the name of the account managed by MSP.

Step 3: Download the IDP metadata and upload it to the Orchestrator

To integrate the customer's Identity Provider (IDP) with Celona Orchestrator, follow the steps below.

Prerequisites:

  1. Customer’s IP Metadata File: Obtain the metadata file from the customer's IDP.

Downloading metadata from Okta

Download the Okta metadata by clicking on View SAML setup instructions under the Sign On tab as shown below:

Downloading metadata from Azure

Navigate to the Single Sign-on page, scroll down to the 'SAML Certificates' card and download the Federation Metadata XML file.

2. Logout URL: Get the URL where SSO users should be redirected after logging out of the CSO portal.

Configuration Steps:

  1. Access SSO Settings:

    • Navigate to Admin Settings > SSO Settings in the Celona Orchestrator.

    • Select the Identity Provider tab.

  2. Upload IDP Metadata:

    • Upload the IDP metadata file received from the customer.
      ​

    • Enter the logout URL provided by the customer.

  3. Default Role Configuration (Optional):

    • If no role mappings are configured between the IDP and CSO, select a default role to assign to users.

      • If configured: Users without specific role mappings can still log in with the designated default role.

      • If not configured: Users without role mappings will encounter an error page with an error code in the URL.

Important Notes

  1. Accessibility:

    • Customer Admins can also configure the Identity Provider in CSO.

  2. Default Role Behavior:

    • Existing customers with pre-configured IP setups: The Default Role will not be assigned automatically, preserving current behavior.

    • For existing setups, the configuration will work as-is unless explicitly updated.

  3. Default User:

    • When a customer account is created on Orchestrator, a default user is also created, and it is tagged as ‘Default User’.

    • Orchestrator will not allow ‘Default User’ to be signed in via SSO as it mandates at least one user without SSO to be able to login to Orchestrator in case the IDP encounters outages - so the customer has at least one user to access Orchestrator.

Ensure role mapping is appropriately configured to streamline user access management (refer to Step 4: Role Mapping for details).

Step 4: Add the Role Mapping on Orchestrator

  • Navigate to Admin Settings -> SSO Settings and click on '+' icon in the Role Mapping Section as shown below:

  • Enter the IDP Role (this should match the role-based group name condition set on the IDP portal - Okta or Azure)

  • Select the Orchestrator Role from the dropdown menu and click Add. Once the details are saved, they will be displayed on the page as shown below -

  • Admins can edit or delete user roles via the Orchestrator using the edit / delete icons shown above.

Note: If an IDP role is not mapped to an Orchestrator role, it's assigned a default role. This default role can be configured on the Orchestrator under the Identity Provider section.

Completing these steps will fully integrate the customer’s IDP with the CSO for Single Sign-On.


​

Step 5: Configure the SSO Launch URL in eitherthe customer portal or IDP dashboard

  • The SSO Launch URL should follow the pattern below:

    • https://<CSO-fqdn>/v1/api/ssogw/saml/login/alias/<customer_alias_value>

  • The <customer_alias_value> will be:

    • <companyName>_self_serve where <companyName> is Account Name without whitespace as displayed on the Account Info page.

    • Use Case-1: If the SSO launch point is from the IDP Dashboard, then a separate icon bookmarked to the above URL can be added (Okta has Bookmark App to hyperlink for an Icon. Ex: Celona)

    • Use Case-2: If the SSO launch point is from the Customer Portal, the above URL needs to be embedded as a hyperlink inside the portal.

  • Once the above configuration is complete, users can launch the Orchestrator by clicking on the Launch URL from the SSO launch points.

  • As the Orchestrator receives an SSO authentication from the IDP, it will do JIT (Just-In-Time) provisioning to create a user profile on the Orchestrator and log the user directly into the Orchestrator dashboard.

Step 6: Viewing the SSO users on Orchestrator

  • SSO users, along with their roles, are tabulated in the Users section (under Admin Settings on the Orchestrator) as shown below:

Troubleshooting

Users will be redirected to an error page with an error code in the URL if an error occurs. A sample page is shown below:

Please note the following -

Before Release 2406:
If a user encounters trouble logging in via SSO, ensure they do not have an existing Orchestrator account set up with an email and password. If they do, please delete that account from the Orchestrator to allow the SSO login process to proceed.

From Release 2406 Onward:

If an existing Orchestrator user with an email and password setup attempts to log in via SSO, their account will automatically be converted to an SSO user. After this conversion, they will no longer be able to log in using their previous email and password credentials.

Please also note that default users are an exception to the above and will not be automatically converted to SSO users.

The table below shows all the possible error codes in the URL and their corresponding reasons. Administrators can reach out to the Celona support team for further troubleshooting if required.

Error Code

Possible Reasons

ERR_SSO_NOT_CONFIGURED

  • Service Provider metadata is not configured in the Orchestrator

  • The customer’s IDP metadata is not configured in the Orchestrator

ERR_INVALID_URL

The SSO Launch URL is incorrectly configured on the customer’s portal

ERR_INVALID_RELAY_STATE

SSO is not initiated directly from the SSO Launch URL but from the identity provider.

ERR_INVALID_FIRST_NAME

  • The first name is not configured with respect to case sensitivity

  • The first name is left empty

  • The first name is longer than 32 characters

  • The first name contains special characters other than hyphen, apostrophe, space, dot, or underscore.

ERR_INVALID_LAST_NAME

  • The last name is not configured with respect to case sensitivity

  • The last name is left empty

  • The last name is longer than 32 characters

  • The last name contains special characters other than hyphen, apostrophe, space, dot, or underscore.

ERR_INVALID_EMAIL

  • The email address is not configured with respect to case sensitivity

  • The email address is left empty

  • The email address is of a personal domain rather than a corporate domain

  • The email address of an existing user has changed.

ERR_INVALID_MOBILE_NUMBER

  • The mobile number provided does not follow the format of E164 (+ sign followed by 15 digits where the first digit is not zero)

ERR_INVALID_ACCOUNT_NAME

  • The account name is not configured with respect to case sensitivity

  • The account name does not match with the Account Name displayed on the Account Info page on the Orchestrator

  • The account name has changed for the given SSO user (please note that once a user profile is created under one account, it cannot be moved to a different one)

ERR_INVALID_SSO_ID

  • The SSO ID is not configured with respect to case sensitivity

  • attribute name in idp configuration is ssold

ERR_INVALID_ROLE

  • The user role is not configured with respect to case sensitivity

  • The user role on the IDP is not mapped to an Orchestrator role or a default role

ERR_INVALID_ORG_SCOPE

This error occurs only for MSP users in the following cases:

  • The org scope is not configured with respect to case sensitivity

  • The org scope attribute is left empty

  • The org scope does not contain an underscore which is a delimitator to split the prefix and the name of the organization

  • The organization name is missing from the attribute

  • The organization does not exist on the Orchestrator

  • The organization does not have an associated MSP (Managed Service Provider) on the Orchestrator

Related Articles
[US-CBRS] Configuring your own Spectrum Access System (SAS)
Access Point Configurations
Security FAQ
SSO Configuration on Azure
SSO Configuration on Okta
Did this answer your question?