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
underAdmin Settings > SSO Settings
to generate SP Metadata file as shown below.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) |
Yes |
| |
ssoId | Yes |
|
authzRole | Yes |
|
accountName | Yes |
|
orgScope | Yes
No |
|
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 theSign 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 onUpload
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 theAccount 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 (underAdmin 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 |
|
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 |
|
ERR_INVALID_LAST_NAME |
|
ERR_INVALID_EMAIL |
|
ERR_INVALID_MOBILE_NUMBER |
|
ERR_INVALID_ACCOUNT_NAME |
|
ERR_INVALID_SSO_ID |
|
ERR_INVALID_ROLE |
|
ERR_INVALID_ORG_SCOPE | This error occurs only for MSP users in the following cases:
|