Skip to main content

Single sign-on

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.

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, like e-mail, and first and last names. These claims can have different names for different providers, so we need to figure out what they are called.

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:

PropertyDescription
NameName for your new application, e.g. my-new-openid-app-registration.
Supported account typesSet to Accounts in this organizational directory only to only allow logins with Microsoft accounts that are registered in your organization.
Redirect URLYour 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:

URLDescription
https://develop--eva-pos-app.netlify.app/loginTo allow SSO in the generic develop POS web-build. (Only used for testing)
https://eva-pos-app.netlify.app/loginTo allow SSO in the generic POS web-build. (Only used for testing)
https://develop--eva-companion-generic.netlify.app/loginTo allow SSO in the generic develop companion web-build. (Only used for testing)
https://eva-companion-generic.netlify.app/loginTo allow SSO in the generic companion web-build. (Only used for testing)
https://[YourAdmin1.0URL]/login/openid-callbackTo allow SSO in your EVA Admin 1.0.

Under Mobile and desktop applications, configure the following URLs:

URLDescription
io.newblack.eva.app://loginTo allow SSO in the Companion App for pre-0.96.0 builds.
io.newblack.eva.app://open-id/loginTo allow SSO in the Companion App for release 0.96.0 and up.
io.newblack.eva.pos.app://loginTo allow SSO in the POS.

Under Single page applications, configure the following URLs:

URLDescription
https://[YourAdminSuiteURL]/loginTo allow SSO for the main login in Admin Suite
https://[YourAdminSuiteURL]/crm/loginTo allow SSO for the People module in Admin Suite
https://[YourAdminSuiteURL]/financial/loginTo allow SSO for the Finance module in Admin Suite
https://[YourAdminSuiteURL]/orders/loginTo allow SSO for the Orders module in Admin Suite
https://[YourAdminSuiteURL]/organizations/loginTo allow SSO for the Organizations module in Admin Suite
https://[YourAdminSuiteURL]/pim/loginTo allow SSO for the Products module in Admin Suite
https://[YourAdminSuiteURL]/promotions/loginTo allow SSO for the Promotions module in Admin Suite
https://[YourAdminSuiteURL]/settings/loginTo allow SSO for the Settings module in Admin Suite
https://[YourAdminSuiteURL]/stock-management/loginTo allow SSO for the Stock module in Admin Suite
https://[YourAdminSuiteURL]/tasks/loginTo allow SSO for the Tasks module 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:

ClaimDescription
emailUser's e-mail address
given_nameUser's first name
family_nameUser's last name

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
}
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
}

Additional management services​

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.