ChannelEngine: SSO authorization
About this article
This article describes how to configure single sign-on (SSO) authorization for your ChannelEngine environment.
Table of contents
Single sign-on (SSO) is an authentication process that grants access to applications using one central login ID (i.e.: user credentials). This process is controlled by a company or entity's identity provider.
An identity provider is a system that manages digital identities and provides authentication services to applications, websites, and other services. Examples of identity providers include Google Workspace, OneLogin, Azure Active Directory (AD), Okta, Auth0, etc.
The benefit of using SSO is that a user only has to remember the credentials for their company. It puts control over user management in the hands of the company or entity, and it is a more secure method of authentication than traditional login credentials.
Configure SSO on ChannelEngine
As a ChannelEngine user, you can configure SSO if you use an identity provider with support for Open ID Connect (OIDC).
During this pilot phase of the implementation at ChannelEngine, you can configure SSO for your environment by following the steps below:
- Add ChannelEngine as an OIDC custom application using the interface of your identity provider. The way to add applications varies depending on your client. E.g.:
- Once ChannelEngine is added as an OIDC application, the identity provider provides a URL, Client ID, and Client secret.
Contact ChannelEngine and provide the following information:
SSO configuration request form
Field Example Explanation Name TestCorp Inc. SSO The name is displayed to the user when choosing a login method. Authority URL https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0/ The authority URL handles the login request. Client ID 00000000-0000-0000-0000-000000000000 The client ID for the OIDC client application. Client secret AAaaa~BBBBBBBBBBBBBBbbbbbbbbbbbbbb~CC000 The client secret for the OIDC client application. Make sure to send this to ChannelEngine using a secure channel, such as Bitwarden Send. Custom scopes profile, email Any additional scopes ChannelEngine needs to receive basic user information. Email claim name The claim contains the user’s email address. Role claim name roles The claim contains the ChannelEngine role that should be assigned to the user (see Role mapping).
- During the current pilot stage, a member of ChannelEngine's Support team adds these credentials to your account. If this is your first time logging in, they ensure your user account is provisioned with the correct access.
- When ChannelEngine creates the provider, it grants you a unique
configuration GUID. This can be used for whitelisting URL redirects.
- The next time you and other users in your company log in to ChannelEngine, you are redirected to your identity provider – where you can input the same user credentials used to access your company's applications.
Your users must be assigned to a role or user group in your identity provider that fully matches the user's role on ChannelEngine before they are able to access your environment. When the user logs in, the identity provider passes the value (i.e.: role) in the token to ChannelEngine – and ChannelEngine matches it to the role in our database, thus providing the correct level of access.
In the future, user roles that you assign or remove from your identity provider are automatically mapped to ChannelEngine. This allows you to add, remove, and manage users independently of ChannelEngine, forming part of your company's onboarding and offboarding processes.
Troubleshoot error 'You do not have access to this tenant'
Some identity providers are not fully able to match ChannelEngine's roles. When the token is passed to ChannelEngine, the user role is left empty in the token. This results in the user receiving an error message when trying to access the ChannelEngine tenant. In this case, user roles have to be set manually on ChannelEngine.
The steps to allow access to your users are as follows:
- The new user tries to log in to ChannelEngine for the first time, and receives an error message stating that they do not have access to the tenant.
- The user with the administrator role for the ChannelEngine account must log in to ChannelEngine and assign a role to the new user manually. To do so, go to Settings, Users, select a role from the dropdown menu under the User roles field, and click Save.
- The next time the user tries to log in to the ChannelEngine tenant, they are redirected to the correct landing page.
During the pilot phase, SSO only allows you to map your users to the built-in roles listed below. If you do not provide a role claim when you send the SSO configuration form, the role assigned to the user's email address in the ChannelEngine application itself is used.
The following roles are currently supported:
|Order manager without customer view||Order.manager.without.customer.view|
|Administrator without customer view||Administrator.without.customer.view|
Redirect URL allowlisting
Some identity providers require you to allowlist redirect URLs. You can determine the correct URL to allowlist based on a combination of your unique ChannelEngine domain name
<your domain>.channelengine.net plus the
configuration GUID provided to you after you have sent the SSO configuration request to ChannelEngine.
Can I configure SSO by myself?
No, this is not possible during the pilot phase. ChannelEngine needs to configure the identity provider for you, but a self-service user interface is planned for a future release.
Can I manage access independently for different ChannelEngine environments?
Yes, this is possible. You can either configure a single OpenID Connect app for multiple environments or create one for each environment to manage access and role assignments in more detail.
Can I connect multiple identity providers with a single ChannelEngine environment?
Yes, this is possible. One ChannelEngine environment can have multiple identity providers connected with it. The user is prompted via a window to choose the environment they want to access. The most recent choice is remembered automatically.
Can I manually enable or disable password logins when using SSO?
No, this is not possible during the pilot phase. Once SSO is enabled, password logins are going to be automatically disabled for all non-administrator users.