All Collections
Getting Started with Celona 5G LAN
SSO (Single sign-on) Configuration Guide for IT Admins
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 a week 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 where the users can launch into 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 public cert of Orchestrator shared in metadata. However, it’s optional.

  • SAML attributes: The attributes associated with the user (username, customer ID, 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).

Step-1: SSO Configuration on Orchestrator

  • Customer admins should click on Enable Service Provider under Admin Settings > SSO Settings to generate SP Metadata file as shown below.

    Graphical user interface, text, application, chat or text message Description automatically generated
    Graphical user interface, text, application Description automatically generated

  • The metadata file will have the following customizable fields (along with a certificate generated for signing the SAML request):

    • EntityID

    • SingleLogoutService

    • AssertionConsumerService

  • A sample Orchestrator metadata file is shown below for reference (with the cert info taken out)

Please note that this article uses Okta as an example, but you should be able to configure single sign-on (SSO) via any similar identity provider (IDP).

Step-2: SSO Configuration on IDP (Okta)

  • Customer IT Admins must now configure their IDP based on the Orchestrator metadata shared by Celona Support

  • Create an application by navigating to Applications -> Create a new app integration -> SAML 2.0 -> Next

  • To create a SAML Integration, provide the following details -

    • General Settings

      • App name

      • App logo (optional)

      • App visibility

  • Configure SAML

    • Single sign-on URL: This URL should be mapped to AssertionConsumerService from Orchestrator metadata:

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

Attribute Name

Mandatory

Value Description and Restrictions

firstName

Yes

Alpha Numeric with max 32 characters

lastName

Yes

Alpha Numeric with max 32 characters

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 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_orgname', where the prefix can be any word not containing an underscore

  • Add custom attributes on IDP (Okta)

  • The picture below shows Group Attribute Statements with orgScope for MSP SSO configuration. (this does not apply to Independent Enterprises)

  • Grant access to users inside relevant Groups on an Application

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

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

  • From the Orchestrator, navigate to Admin Settings → SSO Settings → Identity Provider, upload the IDP metadata file, enter the Logout URL, and click on Upload as shown below:

  • The Upload action will parse the XML file and display the configuration parameters as shown in the example below:

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 Okta)

  • 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.

Step 5: Configure the SSO Launch URL in either Customer Portal/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 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:

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 space, dot, or hyphen.

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 space, dot, or hyphen.

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

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

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

Did this answer your question?