SSO provides a seamless login experience to 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 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 Orchestrator). Orchestrator requests and obtains an identity assertion from the customer’s Identity Provider (IDP). Based on this assertion, Orchestrator allows a user to access the service.

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

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

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

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

The SP-initiated workflow is depicted below:

SSO Configuration on Orchestrator

Step 1: Customer Admins need to reach out to Celona representative or Celona support to request Orchestrator metadata (for the specific customer account) to be used for further IDP configuration

Celona support will create Orchestrator metadata file (based on Account Name), upload to Orchestrator, save the profile, and forward the metadata file to the designated IT contact (who will be responsible for configuring the customer IDP and user roles). 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):

Fig. Sample SP (Orchestrator) metadata file

SSO Configuration on IDP (Okta)

Step 2: Customer IT Admin to configure IDP based on Orchestrator metadata shared by Celona Support

IDP Configuration: Celona’s SP initiated SSO has been tested with various IDPs including Okta.

The following steps shows the required IDP configuration on Okta (as an example): Step 2.a: Create an application on Okta

Step 2.b: General Settings & SAML Settings


Configure SAML: The Single Sign On URL below should be mapped to AssertionConsumerService from Orchestrator metadata:

Step 2.c: Custom Attributes

The following attributes must be sent in the assertion statement:

Attribute Name

Mandatory (Yes/No)

Description

Value Restrictions

firstName

Yes

First name of User

Alpha Numeric with max 32 characters

lastName

Yes

Last name of User

Alpha Numeric with max 32 characters

mobile

No

Mobile number of User

E.164 Format (plus sign followed by maximum 15 digits). First digit should not be 0.

Example:

+0011234567890 → Invalid

1234567890 → Invalid

11234567890 → Invalid

+11234567890 → Valid


email

Yes

Email of User

Must be corporate email. Personal email domains (yahoo, gmail, msn, hotmail, live, aol) are not allowed.

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

If only one corporate email Id must be used, choose only one avenue as primary login. If SSO is chosen as primary login, ensure that there is no existing non-SSO user account on CSO that has email matching to that of SSO.

ssoId

Yes

Unique identifier of User profile on identity provider

Note: The ssoId has letter ‘I’ as Identifier

and not lower-case letter ‘L’

authzRole

Yes

User Role on Identity Provider.

Note: IDP will automatically send the value of user’s role based upon the group that user is assigned to.

To avoid any errors, when adding role mapping on CSO UI, exactly enter the group name (case-sensitive) in IDP Role in Step 4.

Ex: If user belongs to roleGroup_Admin as in pic below, then authzRole value will be roleGroup_Admin.


accountName

Yes

Set this attribute value exactly as “Account Name” on CSO -> Account Info.

Ex: indOrg1 in pic above is the Account Name set as named on CSO.

Note: During “Just-in-Time” provisioning, user will be created in this Account Name on CSO.


orgScope

Yes (Mandatory attribute for SSO configuration at MSP)

No (This attribute is not needed for Independent Enterprises)

A User’s access to enterprises

(“tenants”) under MSP

This value is automatically sent by IDP (Okta) in the below format based upon the association of users to the Authorization Groups, either role based or scope based. In other words, based upon the business use- case, a user should be housed appropriately in the groups.

Format for Group name creation:

<prefix><underscore><accountName> where prefix can be anything without underscore & accountName should be of the enterprises managed by MSP.

If the User needs an access to all the enterprises under MSP, value can directly be <prefix><underscore>ALL

Valid Examples:

1. {'CELONA_msp1_cust1’, ‘CELONA_msp1_cust2’ }

2. {'Celona_ALL'} Invalid Examples:

1. {'Customer1', ‘Customer2’, ‘Customer3’}

2. {'ALL'}

Example:

Use-case 1: If user would have to be an Admin on Orchestrator managing all enterprises under MSP, 2 groups would be created on Okta – roleGroup_Admin, and CELONA_ALL as shown below. Then, user is associated to both groups. Hence, the assertion from Okta would contain authzRole as roleGroup_Admin and orgScope as {‘CELONA_ALL’}

Use-case 2: If user would have to be an Admin on Orchestrator managing Customer1 and Customer2 only under MSP, 3 groups would be created on Okta – roleGroup_Admin, CELONA_msp1_cust1, CELONA_msp1_cust2 as shown below. Then, user is associated to 3 groups. Hence, the assertion from Okta would contain authzRole as roleGroup_Admin and orgScope as {'CELONA_msp1_cust1’,

‘CELONA_msp1_cust2’ }


Note: If a user has access to all enterprises under an MSP, in case 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.

example : orgScope{'Celona_AcctName1, ‘Celona_ALL’, ‘Celona_ AcctName3} → Celona_ALL’ is honoured.

Step 2.d: Add custom attributes on IDP (Okta)

Note: Pic below shows Group Attribute Statements with orgScope for MSP SSO configuration

only. Not applicable for Independent Enterprises.

Step 2.e: Grant access to users inside relevant Groups on an Application

Step 3: Once the IDP configuration (Step 2) is complete, download the IDP metadata and upload it on Orchestrator

Step 3.a: Download the Okta Metadata by clicking ‘View SAML setup Instructions’ n Sign On tab as shown below:

From Orchestrator, navigate to Admin Settings → SSO Settings → IDP Provider, select 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 example below:

Step 4: Add the Role Mapping on Orchestrator

Navigate to ‘SSO Settings’ (under Admin Settings) and click on '+' icon in Role Mapping Section as shown below:

Fig. Role Mapping of SSO Users

Enter IDP Role (should match the role-based group name condition set on Step 2.d for authzRole on Okta), select Orchestrator Role from Dropdown menu (Supported roles – Admin, Observer, Installer, Device Manager) and click on ‘Add’. Once details are saved, it will show on page (as shown below):

The user roles can be edited or deleted by the Admin via the UI (using the Edit / Delete icons shown above).

Step 5: Configure 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 ‘Account Info’ page.

Use-case1: If the SSO launch point is from 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-case2: If the SSO launch point is from Customer Portal, then the above URL needs to be embedded as a hyperlink inside the portal.

Fig. IDP Dashboard with Celona Orchestrator icon added (Sample-use-case-1)

Once all the above configuration is complete, the users can launch into Orchestrator by clicking on the Launch URL from the SSO launch points. Once Orchestrator receives SSO authentication from the IDP, it will do JIT (Just-In- Time) provisioning to create user on Orchestrator and login user directly to Orchestrator Dashboard.

Step 6: Viewing the Users on Orchestrator

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

Troubleshooting

Whenever an error occurs, users will be redirected to error page with Error Code as part of the URL. A sample error page is shown below:

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

Error Code

Possible Reasons

ERR_SSO_NOT_CONFIGURED

a) SP metadata is not configured in the Orchestrator

b) 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 with SSO Launch URL, but it is launched directly

from identity provider.

ERR_INVALID_FIRST_NAME

a) Attribute is not configured with attribute name = 'firstName' on IDP (example: Attribute name for first name of user is configured to be ‘FirstName’ or ‘firstname’ instead of

‘firstName’)

b) firstName value is empty

c) firstName value is more than 32 characters.

d) Value contains special characters other than space, dot or

hyphen.

ERR_INVALID_LAST_NAME

a) Attribute is not configured with attribute name = 'lastName' on IDP (example: Attribute name for last name of user is

configured to be ‘LastName’ or ‘lastname’ instead of ‘lastName’)

b) lastName value is empty

c) lastName value is more than 32 characters.

d) Value contains special characters other than space, dot or hyphen

ERR_INVALID_EMAIL

1. Attribute is not configured with attribute name = 'email' on identity provider configuration (example attribute name for email of user is configured to be ‘Email’ or ‘EMAIL’ instead of ‘email’)

2. email value is empty

3. email is of personal domain. e.g. yahoo, gmail, msn, hotmail, live, aol

4. email for existing user has changed

ERR_INVALID_MOBILE_NUMBER

Value of mobile does not follow E164 Format: + sign followed by 15 digits where first digit is not zero.

Note: Not receiving any value in mobile attribute is ok since it is optional for Orchestrator but if received, it must follow E164 format mentioned above.

ERR_INVALID_ACCOUNT_NAME

a) Attribute is not configured with attribute name = 'accountName' on IDP (example: attribute name for account name of user is configured to be ‘AccountName’ or ‘accountname’ instead of ‘accountName’)

b) Value is not matching ‘Account Name’ visible on account

info page on Orchestrator.

c) Value is changed for given SSO user. Basically, once user is created under one account, it cannot be moved to another

account.

ERR_INVALID_SSO_ID

Attribute is not configured with attribute name = 'ssoId' on identity provider configuration (example: attribute name for unique identifier

of user is configured to be ‘SsoId’ or ‘ssoid’ instead of ‘ssoId’)

ERR_INVALID_ROLE

a) Attribute is not configured with attribute name =

'authzRole' on IDP (example: attribute name for unique


identifier of user is configured to be ‘AuthzRole’ or ‘authzrole’ instead of ‘authzRole’)

b) Value is not configured to map to one of the Orchestrator

roles

ERR_INVALID_ORG_SCOPE

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

a) Attribute is not configured with attribute name = 'orgScope' on IDP (example: attribute name for org scope of user is configured to be ‘OrgScope’ or ‘orgscope’ instead of ‘orgScope’)

b) Value is empty

c) Value does not contain underscore which is delimitator to split prefix and organization name.

d) Missing org name in value. ex. ‘Celona_’ or ‘abc_’

e) Org value is invalid. Either org does not exists in Orchestrator or if it exists, it does not have MSP as parent organization

Note: Value should be ‘prefix_orgname’ where prefix can

be any word not containing underscore.

Did this answer your question?