Single sign-on
EVA allows using single sign-on (SSO) from providers adhering to the OpenID format. SSO configurations can be set up in the Single sign-on chapter.
From the overview, clicking any of the existing SSO providers will give you the option to set it as the primary option. Simply click the Set as primary button to do so.
Configuration
In order to create an SSO configuration, you first need some information from your provider;
- Your SSO provider's BaseURL
- You ClientID with your SSO provider
- Appropriate Claims
Then, create a new SSO provider in the Admin Suite chapter. SSO configurations can be tailored to your specific needs.
User Type
Select which user type your SSO configuration applies to.
Expand to see possible user types
The use of each user type:
- Employee - Someone with permissions in EVA, either as a store staff member accessing our Apps or a head office admin using Admin Suite
- Customer - A consumer account which can be used as part of a checkout process
- Anonymous - Only used on API calls when there is no Auth Token given. Not all APIs are available to be called annonymously
- Business - Can be ignored
- System - EVA system processes e.g. Data exporter or Data Lake
- Debtor - Used to instruct relevent payment methods
- Limited Trust - Can be ignored
- Tester - Can be ignored
- Removed by Request - GDPR accounts which were requested for annonymisation
- API - An external system API call identified by its header
Checkboxes
- Enabled: This one should be pretty straight-forward.
- Create users: Leave this unchecked if logging in using SSO shouldn't create a user record in EVA.
- Disallow other methods: Checking this box disables any other login methods for users that were created using this SSO method.
Claims
Claims are bits of information that your provider returns in response to a successful OpenID request. This includes properties like email or first and last name. Since every provider has its own naming conventions for specific fields, you'll need to match those names used by the provider (read: fields) with the corresponding fields in EVA to properly use the provider's information.
For example, the First name field in EVA may be called given_name by an OpenID provider - which is what you'll have to enter in the First name claim field, and so forth for the other claim fields (as applicable).
Configuring your provider
Now that we've configured SSO from the 'EVA-side', there are some things to consider when doing configurations from the SSO 'Provider-side'.
Callback URLs
We have to configure callback URLs for all our frontends in order for SSO to function properly:
Web applications:
| URL | Description |
|---|---|
| https://develop--eva-pos-app.netlify.app/login | To allow SSO in the generic develop**POS** web-build. (Only used for testing) |
| https://eva-pos-app.netlify.app/login | To allow SSO in the generic POS web-build. (Only used for testing) |
Mobile and desktop applications:
The following URLs are for the Apps
| URL | Description |
|---|---|
| io.newblack.eva.app://login | To allow SSO in the Companion App for pre-0.96.0 builds. |
| io.newblack.eva.app://open-id/login | To allow SSO in the Companion App for release 0.96.0 and up. |
| io.newblack.eva.pos.app://login | To allow SSO in the POS. |
| io.newblack.eva.beyond.tasks://openid | To allow SSO in App Suite |
| io.newblack.eva.beyond.customers://openid | To allow SSO in App Suite |
| io.newblack.eva.beyond.sales://openid | To allow SSO in App Suite |
| io.newblack.eva.dev.tasks://openid | To allow SSO in App Suite |
| io.newblack.eva.dev.customers://openid | To allow SSO in App Suite |
| io.newblack.eva.dev.sales://openid | To allow SSO in App Suite |
The following URLs are for the Unlisted Apps distributed after September 26, 2023
| URL | Description |
|---|---|
| global.newblack.eva.main.public.pos://openID | To allow SSO in the Main version of POS. |
| global.newblack.eva.beyond.public.pos://openID | To allow SSO in the Beyond version of POS. |
| global.newblack.eva.main.public.sales://openID | To allow SSO in Main version of Checkout App. |
| global.newblack.eva.beyond.public.sales://openID | To allow SSO in the Beyond version of Checkout App. |
| global.newblack.eva.main.public.customers://openID | To allow SSO in the Main version of Loyalty App. |
| global.newblack.eva.beyond.public.customers://openID | To allow SSO in the Beyond version of Loyalty App. |
| global.newblack.eva.main.public.tasks://openID | To allow SSO in the Main version of Tasks App. |
| global.newblack.eva.beyond.public.tasks://openID | To allow SSO in the Beyond version of Tasks App. |
| global.newblack.eva.main.public.cfd://openID | To allow SSO in the Main version of CFD. |
| global.newblack.eva.beyond.public.cfd://openID | To allow SSO in the Beyond version of CFD. |
Single page applications:
| URL | Description |
|---|---|
| https://[YourAdminSuiteURL]/login | To allow SSO for the main login in Admin Suite |
| https://main--[YourAdminSuiteURL]/login | To allow SSO for the main login in Admin Suite |
| https://beyond--[YourAdminSuiteURL]/login | To allow SSO for the main login in Admin Suite |
Implicit grant flow
In order for single page applications to access the token without an intermediate code exchange step (you need this, trust us), make sure to enable 'implicit grant flows' in your SSO provider.
Deleting Users
Users that are deleted in the OpenID provider's database will NOT be deleted in EVA. However, we can set up SSO users to exclusively be able to log in using SSO. This effectively means that as their record in the OpenID provider's database is erased, so is their means of logging in. The EVA employee user will still exist, but it won't be able to authenticate.
DisallowOtherMethods
To do so, simply add "DisallowOtherMethods": true to your CreateOpenIDProvider or UpdateOpenIDProvider request.
IsSingleSignOnly
Alternatively, you can also configure the PushUser and CreateEmployeeUser service with the IsSingleSignOnly property. When this property is set to true, the users will not be able to create a separate password in EVA anymore - meaning that once they don't have access to SSO, they won't have access to EVA.
If an account has the IsSingleSignOnly attribute, editing any user objects from the profile page is not possible, as it is not applicable.
Converting existing users to SSO only
To update existing users to be limited to the SSO flow only, you can use the service SetUserToSingleSignOnOnly.
This service requires the functionality ChangeUserLoginType and accepts an ID (UserID).
Authentication versus authorization
Even though SSO 'can' be used to create users. They won't yet have any roles, not even the Login role. Unless you will use SSO on your webshop for customers, you will have to assign roles manually. There are two flows here essentially;
- Use SSO to create a user and then have another user log in and assign correct roles. Now the original user can log in.
- Make sure there is a known record of your user - with the appropriate roles - before using SSO so you can log in right away.