SSO

Our OpenID integration allows you to set up one of your OpenID-enabled authorization providers for authentication purposes in EVA. In short, your users will be able to log on to EVA using their Microsoft, Google or any other OpenID-enabled credentials.

Configure in Admin Suite or via API

SSO can also be configured in our Single sign-on chapter in Admin Suite.

This page goes into detail on how to do so via API, but has the same explanations on settings and limitation - whatever your choice, both will lead to the same results.

Necessary information

The way this integration works is that EVA will contact your configured provider and request authentication. The user then logs onto the provider (Google for example). The provider then sends information back to EVA which can be used to log in.

To set up a provider, we first need to collect some information from our provider. We are going to need:

• a BaseURL
• a ClientID
• the appropriate claims

BaseURL

The BaseURL is your providers URL to which we will be making the OpenID request.

ClientID

The ClientID is configured on your provider's side of things and will serve as the identifier for the client that is making the request.

Claims

Claims are bits of information that your provider returns in response to a successful OpenID request. This includes properties like e-mail or first and last names. Since every provider has his own naming for specific fields, you'll you have to ensure these claims (read: fields) as used by the provider match the corresponding fields in EVA - if you want to use the provider's information.

Example configuration

To give you a feel for configuring an OpenID provider, we will show you how to set this up using Azure AD as your provider.

Application registration

According to the Azure AD OpenID documentation, we first need to 'register an application'. This is Azure's definition of setting up the ClientID we mentioned before.

In Azure's setup, we encounter the following configuration:

Property	Description
Name	Name for your new application, e.g. my-new-openid-app-registration.
Supported account types	Set to Accounts in this organizational directory only to only allow logins with Microsoft accounts that are registered in your organization.
Redirect URL	Your callback URL (discussed later)

Configuring callback URLs

Now, in your newly registered application, head over to Authentication. Here, we need to add two Platforms; one for 'Web' and one for 'Mobile and desktop applications'.

Under Web, configure the following URLs:

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)

Under Mobile and desktop applications, configure the following URLs:

The following URLs are for the "old" 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 Sales App.
global.newblack.eva.beyond.public.sales://openID	To allow SSO in the Beyond version of Sales App.
global.newblack.eva.main.public.customers://openID	To allow SSO in the Main version of Customers App.
global.newblack.eva.beyond.public.customers://openID	To allow SSO in the Beyond version of Customers 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.

Under Single page applications, configure the following URLs:

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

Now, in the same overview, tick the box labeled ID Tokens under the Implicit grants and hybrid flows section.

Fetch your necessary data

After having registered your application, head over to your newly created application's overview, and find your Application (client) ID and Directory (tenant) ID. Copy these values.

Now, at the top of your overview, click Endpoints and find the endpoint for OpenID Connect metadata document. This URL is the BaseURL we discussed before, with /.well-known/openid-configuration suffixed. Remove the latter part and you have your BaseURL.

danger

Do not confuse BaseURL with CallbackURL, they are very different.

Claims

Claims are bits of information that the OpenID provider will include in their response to EVA. This information can be sent in a JWT token. The properties contained in this token correspond with fields in EVA but they may have a different name, which requires you to connect them by mapping. In the Azure AD claims documentation we can check what claims we need to watch and what they are called:

Claim (naming at OpenID provider)	Field in EVA
email	User's e-mail address
given_name	User's first name
family_name	User's last name

Claims and scripting

We can expand the JWT token with scripting. By inserting a custom script you can 1) add additional information to the token (e.g. a role set and/or OU), and 2) perform mapping of the values. For scripting examples, see Scripting extension points.

Set up your OpenID provider

Now that we have all information we need, we can start to set up our OpenID provider. To do so, we use CreateOpenIDProvider with all information we have gathered before:

{
  "Name": "Azure",
  "Enabled": true,
  "BaseUrl": "https://login.microsoftonline.com/yourTenantID/v2.0",
  "ClientID": "yourClientID",
  "FirstNameClaim": "given_name",
  "LastNameClaim": "family_name",
  "EmailAddressClaim": "email",
  "UserType": 2, //desired UserType of the users that are created from OpenID
  "CreateUsers": true //whether or not to create users in EVA from the SSO auth
}

{
  "ID": 1
}

note

Users that are created as a result from an OpenID login will not be created with any roles attached. These have to be manually added.

Set as primary provider

To set your newly configured OpenID provider as the primary OpenID provider, use SetPrimaryOpenIDProvider:

{
  "ID": 1
}

{}

Update OpenID provider

To update your OpenID provider, use

{
  "ID": 1,
  "Name": "Log in using your Microsoft account",
  "Enabled": true,
  "BaseUrl": "https://login.microsoftonline.com/yourTenantID/v2.0",
  "ClientID": "yourClientID",
  "FirstNameClaim": "given_name",
  "LastNameClaim": "family_name",
  "EmailAddressClaim": "email",
  "UserType": 2,
  "CreateUsers": true
}

{
  "ID": 1
}

Additional management services

• UpdateOpenIDProvider
• GetOpenIDProviderByID
• ListOpenIDProviders
• DeleteOpenIDProvider

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.

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;

1. Use SSO to create a user and then have another user log in and assign correct roles. Now the original user can log in.
2. Make sure there is a known record of your user - with the appropriate roles - before using SSO so you can log in right away.