ChannelEngine: SSO authorization

About this article

This article describes how to configure single sign-on (SSO) authorization for your ChannelEngine environment. 

Table of contents

Introduction

Configure SSO on ChannelEngine

• SSO configuration request form
• Role management
• Role mapping

Redirect URL allowlisting

FAQs

Introduction

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:

1. 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.:
   • OneLogin - OIDC Custom Connector
   • Google Workspace  - Signing in users with OIDC
   • Auth0 - Connect to OpenID Connect identity provider
   • Okta - How do I add OIDC to my app?
   • Azure AD - Add OIDC application
2. Once ChannelEngine is added as an OIDC application, the identity provider provides a URL, Client ID, and Client secret. 
3. 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	email	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).

4. 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.
5. When ChannelEngine creates the provider, it grants you a unique configuration GUID. This can be used for whitelisting URL redirects. 
6. 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. 

Role management

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: 

1. 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. 
2. 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. 
3. The next time the user tries to log in to the ChannelEngine tenant, they are redirected to the correct landing page. 

Role mapping

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:

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. 

E.g.: https://testcorp-inc.channelengine.net/callbacks/oidc/00000000-0000-0000-0000-000000000000/signin 

FAQs

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.