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.
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:
- the appropriate claims
The BaseURL is your providers URL to which we will be making the OpenID request.
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 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.
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.
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:
|Name||Name for your new application, e.g. |
|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:
|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)|
|https://develop--eva-companion-generic.netlify.app/login||To allow SSO in the generic develop companion web-build. (Only used for testing)|
|https://eva-companion-generic.netlify.app/login||To allow SSO in the generic companion web-build. (Only used for testing)|
|https://[YourAdmin1.0URL]/login/openid-callback||To allow SSO in your EVA Admin 1.0.|
Under Mobile and desktop applications, configure the following URLs:
|io.newblack.eva.app://login||To allow SSO in the Companion App for pre-|
|io.newblack.eva.app://open-id/login||To allow SSO in the Companion App for release |
|io.newblack.eva.pos.app://login||To allow SSO in the POS.|
Under Single page applications, configure the following URLs:
|https://[YourAdminSuiteURL]/login||To allow SSO for the main login in Admin Suite|
|https://[YourAdminSuiteURL]/crm/login||To allow SSO for the People module in Admin Suite|
|https://[YourAdminSuiteURL]/financial/login||To allow SSO for the Finance module in Admin Suite|
|https://[YourAdminSuiteURL]/orders/login||To allow SSO for the Orders module in Admin Suite|
|https://[YourAdminSuiteURL]/organizations/login||To allow SSO for the Organizations module in Admin Suite|
|https://[YourAdminSuiteURL]/pim/login||To allow SSO for the Products module in Admin Suite|
|https://[YourAdminSuiteURL]/promotions/login||To allow SSO for the Promotions module in Admin Suite|
|https://[YourAdminSuiteURL]/settings/login||To allow SSO for the Settings module in Admin Suite|
|https://[YourAdminSuiteURL]/stock-management/login||To allow SSO for the Stock module in Admin Suite|
|https://[YourAdminSuiteURL]/tasks/login||To 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.
Do not confuse BaseURL with CallbackURL, they are very different.
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:
|User's e-mail address|
|given_name||User's first name|
|family_name||User'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:
"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
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
Update OpenID provider
To update your OpenID provider, use
"Name": "Log in using your Microsoft account",
Additional management services
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.
To do so, simply add
"DisallowOtherMethods": true to your
Alternatively, you can also configure the
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;
- 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.