¶ General Setup
Setup => General
Enter the setup of the Authorization Box environment like Customer settings, Contracts, Database connections and Authorization Box users.
¶ Customer Settings
Use the ‘Edit’ button (left top corner) to change the Customer Settings.
.png)
Contact name : Name of the contact of the company.
Contact Email Address : Email Address of the contact of the company.
Contact Phone Number : Phone Number of the contact of the company.
Company required in Authorization Requests : With the option “Yes”, the system will check on Company in the Authorization Request.
Authentication Method : Choose which method has to be used ("Basic" [with a username and password specific for the Authorization Box] or “Microsoft” [with your Microsoft account])
Multi-Factor Authentication : Choose if this has to be enabled (using Mail code) or disabled. Usually this is not enabled when Authentication with Microsoft has been chosen.
¶ Fasttab Contracts
Shows the contract(s) with 2-Controlware. The number following “Contracts” shows the number of active contracts.
Application Name : The application a contract has been agreed upon.
Start date : The starting date of the application contract.
End date : The date the application contract will end.
Extension Date : The date the application contract will have to be extended.
Contract terminated : The date the application contract is (going to be) terminated.
Characteristic : Any additional information regarding the application contract.
.png)
¶ Fasttab Databases
Shows the number of database connections that are set up and (still) can be set up with the Authorization Box as per contract.
How to create a (new) database.
If the number of database connections exceeds 10, pagination is used for a better overview of the connections.
¶ Overwrite current permissions in Business Central with those of the Authorization Box
All current permissions in Business Central can be overwritten with the ones in the Authorization Box.
Activating this option, means that only the permissions assigned to a user with an Organization role in the Authorization Box, will be valid for the Authorization Box activated users.
Any permissions assigned directly in Business Central will be removed if they are not present in an assigned organization role.
Open a Database(connection) and check the box "Default overwrite Current Permissions"
When saving, the system will ask if this has to be executed for all users.
When completed, use “Synchronize all” in this connection (in the drop down menu of the button 'Database').
¶ Fasttab Users
Shows the number of Users that will be allowed to log on into the Authorization Box as per contract and how many have already been assigned.
Changing the settings of the current User.
Adding users to the Authorization Box.
¶
Adding users to the Authorization Box (video available)
Add a number of users that will be allowed to log on into the Authorization Box as per contract.
Go to Setup => General and click on the fasttab “Users”.
Click on ‘New’ to set up a new user.
Enter the user’s Email address.
'Save & Close' : Saves the user and expands the page for more details.
'Cancel' : Cancels adding a user and closes the page.
After saving, enter the user details:
- Name : Enter the user's Name.
- Phone Number : (optional) Enter the User's Phone Number.
- Function Profile : Select the User Profile. (mandatory to grant access to functionality of the Authorization Box)
The Application Manager has no restrictions on rights.
By choosing the correct Function Profile, a person will be granted specific rights in the Authorization Box.
The most common Profiles used are :
- The Application Manager (has no restriction on rights)
- The Controller
- The Framework Manager
- The Support Employee
- The Support Employee Light (mostly View rights)
- The API User (required if the API has to be accessed)
When a Function Profile has been assigned to an Authorization Box user, the fasttab ‘Roles’ on the usercard will show a check mark for the assigned permissions.
To grant the User access to the available connection(s), click on ‘Select’ in the fasttab ‘Databases’ on the usercard and choose the appropriate ones.
A checkmark will show up for the selected connections. To deselect a connection, click on the selection with the checkmark to remove it.
It is possible to grant the user access to all at once by clicking on 'Select All' or to deny access to all connections at once by clicking on 'Deselect All'.
‘Save’ : Saves assigning / changing access to connections for that user.
'Cancel' : Cancels assigning / changing access to connections for that user.
When a user has been added, the user will receive an email with a temporary password to log in. After first log in, the password has to be changed.
¶ Roles based on Function Profile
An Authorization Box User has to have a Function Profile to have access to the functionality of the Authorization Box.
The Function Profile has certain roles assigned.
The roles can be found based on the Function Profile in the fasttab "Roles".
.png)
¶ Lock or Unlock User
When a user tried to log in several times with a wrong password, this user will be locked out.
In the user overview it is possible to Unlock (or lock) the user.
Press on the ‘lock icon’ to lock or unlock the user.
Press on the 'reset icon' to reset the password. The user will receive an email with the new, temporary, password.
.png)
¶ Multifactor Authentication
Multi Factor Authentication (MFA) requires users to successfully complete two steps to access the Authorization Box.
It involves entering the username and password, including a confirmation code sent by email.
This provides additional control during the login process. When using MFA the user also needs access to that user's mail to be able to log in.
¶ Set up MFA
Go to Setup => General => Edit.
At the bottom of the customer card, choose the required Authentication Method and Multi-Factor Authentication.
.png)
With Authentication Method you have the following options:
- Basic : Log in with your credentials for Authorization Box.
- Microsoft : Log in with your Microsoft Office credentials.
With Multi-Factor Authentication you have the following options:
- Disabled : Multi Factor Authentication is not enabled.
- Mail Code : You will receive a verification code by mail as a second factor for your login attempt.
However, if you already have Multi Factor Authentication set for your Microsoft account, that setting still applies.
In these cases, the MFA in the Authorization Box is usually not enabled.
The Basic c/w disabled setting or Microsoft c/w disabled setting ensures that Multi Factor Authentication is not enabled.
You can activate / deactivate the MFA for the Authorization Box, per user, by toggling the button to on or off.
.png)
When you have chosen for Mail Code, you have the following options:
¶ Basic & Mail Code
Enter your login details for the Authorization Box and click on ‘Login’.
You will receive an email with a confirmation code. This code will be valid only once.
When you log in again, you will receive a new mail with a new code.
In the input field as shown below, enter the code from the email.
Click on 'Save' and you proceed to log in to the Authorization Box.
¶ Microsoft & Mail Code
On the login screen, click on the green button with 'Login with Microsoft'.
The Microsoft Office login screen will appear, where you have to enter you Microsoft email and password.
You will receive an email with a confirmation code. This code will be valid only once.
When you log in again, you will receive a new mail with a new code.
In the input field as shown below, enter the code from the email.
Click on 'Save' and you will proceed logging in to the Authorization Box.
!Note : After 30 minutes of inactivity, you will be logged out automatically.
¶ Setting up Approval settings (has to be set up per database connection) (video)
How to set up the Approval settings, make yourself an Approver and how to create Approval Groups.
¶ Approval settings
Go to Setup => Approval settings to set up the number of Approvers.
- Number of approvers for company groups :
The number of approvers required for a new or changed Company Group.
If the number is set to 0, no approval is required and a change is processed without approval.
A new Company in a Company Group can result in permissions for users with the same assigned Organization Roles in the other companies in that Group! - Number of approvers for permission set groups :
The number of approvers required for a new or changed Permission Set Group.
If the number is set to 0, no approval is required and a change is processed without approval.
A new Permission Set in the Permission Set Group can result in extra permissions for users with the same assigned Organization Roles in this linked Permission Set Group! - Number of approvers for organization roles:
The number of approvers required for a new or changed Organization Role.
If the number is set to 0, no approval is required and a change is processed without approval.
Should the Organization Role be assigned to an Approval Group, the number of approvers will change according the assigned group. - Default number of approvers for Authorization Requests :
The number of approvers that are required for new Authorization Requests.
If the number is set to 0, no approval is required and a new permission assigned to a User will be processed without an approval.
'Save & Close' : Saves the assigned number of approvers per category and closes the page.
‘Cancel’ : Cancels the changes made in the number of approvers per category and changes the settings to the previous settings.
¶ Approvers
Setup => Approvers shows an overview of approvers and the assigned Approval Type
To create a new Approver, click on 'New' in .
- Approver : Select the Authorization Box user to make that user an Approver. You can assign several users at once by clicking on their name. A check mark will appear behind their name(s).
- Approval Type : Select the Approval Type. Here too you can select multiple types at once. A check mark will appear behind the chosen approval type(s).
Depending on the Approval settings, changes in the framework must be approved.
After approval, the Authorization Box will process the change.
The following types of approval are available :
- Assign authorizations : Approve Authorization Requests.
- Revoke authorizations : Revoke any assigned / sent Authorization Requests.
- Create / Change Organization Role : To approve the creation of, or modification to an Organization Role like the addition of an extra Permission Set.
After approval of the creation / change, the request will be processed.
In case of a change, all the users with the already assigned Organization Role, will automatically receive the new Permission Set through a synchronization. - Create / Change Permission Set Group : To approve the creation of, or modification to a Permission Set Group.
Approval of the addition of a Permission Set to a Group adds this Permission Set to any user with that Group already assigned.
The same applies to the removal of Permission sets in that Group. - Create / Change Company Group : To approve the creation of, or the change of a Company Group.
'Save & Close' : Saves the assignment(s) and closes the page.
'Cancel' : Cancels the assignment(s) and closes the page.
¶ Approval Groups
Approval Groups are a group of one or more Approvers that can be assigned to one or more Organization Roles.
When an Approval Group is assigned to an Organization Role, this will overrule the general Approval Settings for that specific role.
For instance: the number of approvers required for approval on an Authorization Request is generally 1, but an Approval Group is set to 2.
When an organization role gets this Approval Group assigned, the number of approvals will be derived of the Approval Group (2) instead of the general settings (1).
¶ Set up an Approval Group
Go to Setup => Approval Groups.
To create a new Approval Group click on 'New'.
- Approval Group : The name of the Approval Group.
- Required approvers : The number of approvers that are required for new Authorization Requests. This number overrules the number of the general settings and has to be 1 or higher.
‘Save & Edit’ : Saves the Approval Group and expands the page for additional details to be filled in.
'Cancel' : Cancels the addition of the Approval Group and closes the page.
When the Approval Group is saved, you can add Approvers to the Group and the Organization Roles to this Group.
¶ Adding Users to an Approval Group
When an Approval Group has been made, you can add one or more Approvers to that Group by moving them from the left to the right column in the fasttab “Users”.
You can do this by double clicking on a user or by selecting a user and clicking on one of the arrow buttons pointing to the right.
When you have finished selecting the user(s) for that Group, click on ‘Save’ in that fasttab.
¶ Adding Organization Roles to an Approval Group
When an Approval Group has been made, you can add one or more Organization Roles to that Group by moving them from the left to the right column in the fasttab "Organization Roles".
You can do this by double clicking on a role or by selecting a role and clicking on one of the arrow buttons pointing to the right.
When you have finished selecting the role(s) for that Group, click on 'Save' in that fasttab.
When you added an Approval Group to an Organization Role, the “Number of approvers authorization request” for that Organization Role will be set to “Conform Approval Group” instead of “According to General Setup (Default)”.
¶ Setting up Notifications (has to be set up per database connection)
You can manage and change your notification settings of the Authorization Box to your preferences.
Click in the upper right corner on your account and click on “Notification Settings”.
You will be prompted with an overview of all notification settings.
All notification settings are categorized.
The following categories are defined:
- User Management,
- Authorization Framework,
- Monitoring,
- Synchronization,
- Database.
Choose “Yes” or “No” with the dropdown if you want to receive notifications in the Authorization Box and / or if you want to receive a notification email.
'Save & Close' : Saves the preferences and closes the page.
'Cancel' : Cancels the (changed) settings and closes the page.
¶ API
At this moment, 2-Controlware has a Web API and an Authorization Request API to access our data.
You can access these through the following links :
Web API : https://api.2-controlware.com
Authorization Request API : https://api.2-controlware.com/authorizationrequest/
The links to the Swagger documentation :
Swagger Web API : https://api.2-controlware.com/swagger/index.html
Swagger Authorization Request API : https://api.2-controlware.com/authorizationrequest/swagger/index.html
You can log on to the API with a Username and Password or with a Personal access token.
This user has to be granted a specific Function Profile (e.g. API User) to be able to access the API.
Which steps to take when using a Personal access token are described below.
When using a Username and Password you can simply go to the Swagger Web API page and use the “POST /api/Authenticate/Login”.
¶ Authorization on Swagger
To get access to our API with a Bearer token, you will have to log into the Authorization Box and click on your name in the top right corner.
Click on “Personal access token”
In the following screen click on 'New'.
Fill in the user name and if you want this token to be valid for a period of time or if you don't want it to expire.
Click on 'Save'.
A pop-up appears with your Personal access token.
Copy it by clicking on the ‘Copy’ icon and click 'Close'.
In the Swagger Web API page scroll down to “Authenticate” and choose the “POST /api/Authenticate/AccessToken”.
Click on 'Try it out'.
Replace “string” with the user name (keep the quotation marks)
and replace the number after “token” with the token you just retrieved from the Authorization Box (keep the quotation marks).
.png)
Click on 'Execute'.
A Server response with Code 200 shows the Bearer token.
Copy this whole token shown in green.
In our sample picture below, the code is hidden but you need what is between the quotation marks.
Click on 'Authorize' on the top of the page.
As per description in the pop up, start the Value with “Bearer” and paste the code which was just generated.
Click on 'Authorize'.
The value will have been changed into ****** and you can now choose ‘Logout’ if you want to leave access to our API or ‘Close’ if you want to use start using Swagger.
The green “Authorize lock” shows it is locked.
¶ Example of use with Swagger documentation
You could use the Swagger documentation to get the number of Organization Roles right from the API by using the “GET /odata/OrgRolesPerUser/$count”.
When you click this option open, you can click on 'Try it out'
The possible response codes are also shown, some with an example response.
As there are no Parameters required for this request, you can now click on ‘Execute’.
.png)
You should now get a Server Response showing you the result.
