From v12.01, Coins ERP+ uses Code Grant to authenticate and recover identity from Azure Active Directory. This topic explains how to set this up and configure the permissions required.
Note: You do not have to switch to the Code Grant method of authentication as soon as you upgrade to v12.01 – the OpenID Connect method will still work – but we recommend you switch to Code Grant as soon as possible.
Configuration
App registration
A COINS App needs to be registered in AAD before the permissions can be granted. See Configuring AAD.
If you already have a COINS App registered you could use that, but we suggest registering a new App.
Set SY/AAD_RESPONSE_TYPE to CODE.
SY/AAD_RESPONSE_TYPE
AAD Response Type
The authentication response type. To be able to use AAD permissions will require the CODE response type.
Blank (default) = Use the OpenID connect method for authentication (as has been the case for the past few releases).
This allows the application to be upgraded and the old OpenID connect authentication method to be used until such time as setup for the CODE grant option can be completed if required.
CODE = Use the new code grant protocol. The refresh tokens and Graph capability will only work if the CODE option is used.
Disable Coins ERP+ two-factor authentication: set the AUTH2IPS parameter to blank.
Set the following parameters as appropriate:
SY/AAD_AUTHORIZE
AAD Authorisation URL
The Azure authorisation endpoint. Expected value: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
If your AAD app is set as single tenant you will need to alter the tenant value from “common” to “organizations”.
SY/AAD_CLIENT_ID
AAD Application Client ID
The ID of the Azure registered Application to be used to perform the authentication.
SY/AAD_HOME_URI
AAD Home URI
The URI for the page to be redirected to after logging out of COINS but without logging out of AAD. It is expected to be some sort of landing page which allows the user to select applications to launch. For example: https://www.office.com
SY/AAD_KEYS
AAD Keys URL
The Azure public keys URL. Expected value: https://login.microsoftonline.com/common/discovery/v2.0/keys
SY/AAD_LOGOUT
AAD Logout URL
The Azure logout endpoint. Expected value: https://login.microsoftonline.com/common/oauth2/v2.0/logout
If your AAD app is set as single tenant you will need to alter the tenant value from “common” to “organizations”.
SY/AAD_REDIRECT_URI
AAD Redirect URI
The Coins ERP+ URL to be redirected to after AAD authentication. This URL must be registered in the Azure application. The value entered here will have the login program appended. Expected value: https:<Host>/env/<environment>
SY/AAD_SECRET
AAD Client Secret
If using AAD login, this is the client secret that was created in the Azure application.
SY/AAD_SSO
AAD Use SSO
Whether to use AAD single sign on login. A button will appear on the login page and SSO will be enabled.
SY/AAD_TENANT
AAD Tenant ID
AAD Tenant ID used in mobile authentication process.
Related Parameters
SY/AAD_MOBILE - Use AAD For Mobile Authorisation
SY/AAD_MOBILE_APP_ID - AAD Application Client ID for M1x
Permission configuration
Permissions required by Coins ERP+ are specified in a series of functions that have been added to the menu %WSYPERM.
These functions will be added to as further Graph services are required.
Since the permissions are functions these can be added to groups. When a user logs in, the permissions are requested from AAD.
Permission can be granted by a Coins ERP+ user who is also an AAD administrator, or can be requested by a Coins ERP+ user (for example, if the AAD administrator does not have access to Coins ERP+).
Whichever technique is used to grant admin consent, the permissions set up as required will be stored in SY/AAD_PERMISSIONS as a list of functions that have been selected.
SY/AAD_PERMISSIONS
AAD Permissions Required
A list of the AAD permission functions required by the system. The administrator will be required to consent to these permissions.
This parameter is updated when the permissions are selected on the AAD Admin Consent function. They can be edited directly if required.
To grant or request admin consent
Navigate to the AAD Permissions function (%WSYP000).
AAD Permissions
The functions that are accessible to you are presented. The options on this page are generated from the functions on the %WSYPERM menu. Any unlicensed functions are hidden. The Grant column shows what permissions you were granted when you logged in.
Hover over the title of the permissions to show a brief summary of the functionality that will unavailable if this permission is not granted.
AAD Permissions with Tooltip
If there are permissions you do not want to grant to any users, open the record, clear the Required box for those permissions, and save the record.
Click the Admin Consent button.
A link required to perform the admin consent is copied to the clipboard.
If you are not the AAD Admin user, create an email to the AAD Admin user and paste in the link for them to follow.
If you are the AAD Admin user, continue with the steps below.
If you have more than one AAD account, a selection screen is shown:
Microsoft Account Selection
Select the Admin account to log in.
A Permissions Requested screen is shown.
Microsoft Permissions Requested Screen
Click Accept to grant Admin consent for the permissions shown.
As a consequence of the Admin user granting consent, the App Registration will now show these permissions granted.
Azure API Permissions
The Enterprise Applications will also show the admin grant.
Azure Enterprise Applications
By doing this step the normal users will now not need to consent individually to the permissions.
Coins ERP+ Two-Stage Login
Coins ERP+ Login
The Coins ERP+ login has been converted to a two-stage process.
The first stage is to acquire the identity of the user and to use that to map to a Coins ERP+ user.
The second stage is to request an authorisation code for that user for the specific services/permissions that they require based on:
the permissions functions that they have access to on the Permissions menu (%WSYPERM), and
which permissions have been selected as required – SY/AAD_PERMISSIONS).
This allows group access to control which features the user will be using and the corresponding Graph permissions that they will need.
The code grant protocol is shown below.
If Admin consent has not been run then the user might see a consent form (and this would only work for non-admin permissions) otherwise they would log in to AAD and with two screen refreshes they would arrive in COINS as before.
Duplicate email address
Previously if a duplicate email address existed in Coins ERP+, an error would result on login since it was not possible to know which user was required.
With the new two stage approach to login it is now possible to allow a user to have more than one account with the same email address.
If two (or more) user accounts contain the same email address, a user selection page is shown between the two authentication requests, to prompt the user to select the user they wish to log in as.
Coins ERP+ Account Selection
If the user clicks on the account required, they will be taken into COINS as that user.
If you only have one AAD login then some of the AAD User Selection pages will not appear and the process will be even more seamless for a normal user.
User Workbench
There is new tab on the User Workbench for when the user has been linked to AAD (that is, on the first successful login).
User Workbench – AAD ID Tab
It shows the AAD Object (user) ID and the scope that was granted the last time the user logged in. The profile button will run a Graph profile for this user to allow an administrator to test that the scope and access tokens are correctly assigned.
A successful profile request will look something like this:
AAD tokens and scope will be revoked if the AAD_CLIENT_ID is changed.
The AAD Object ID will be cleared if the user’s email is changed.