preparations
Exchange (Outlook) preparations!
exchange preparations
In the steps below we will describe the steps needed to prepare the Exchange (Outlook) side for the ORB connection.
initial requirements
Before we can start the preparations it’s important to know what all the requirements are to start.
The ORB needs two user accounts to work as intended. These accounts are the API user and the Fallback user. Both accounts need a mailbox (the minimal license required for this is a “Exchange Kiosk” license). The API user will be used to check and create Exchange bookings. The API user will do this for both the rooms and the personal calendars. The Fallback user will be used when a person is not known in one of the platforms. The meeting will still be created but it will be attached to the Fallback account. This way the time slot is always reserved even when a person is unknown in one of the platforms. All communication with Exchange is done with EWS.
For the API user the Application Impersonation right is required.
The Fallback user will need Full Acces rights for all the rooms that will be monitored by the ORB.
Both users can be created with a name that is recognizable and in line with the rest of the naming in your tenant. In the steps below we will describe how both accounts can be configured.
- API user (Exchange Kiosk license)
- Fallback user (Exchange Kiosk license)
preperations API USER
With these steps we will describe how the needed rights can be assigned to the API user when using a On-Prem Exchange environment. The right we will be assigning in this step is the “Application impersonation” right.
You go through the step-by-step instructions by completing the steps described and continuing with the next step (tab) in the bar above.
WHY?
The API user is used to check and create Exchange bookings for both the rooms and the personal calendars. This account is essentialy used for the insight in the Exchange environment, and to create the reservations.
WHAT DOES IT YIELD?
After following this step-by-step instruction you will have configured the following:
- Created and assigned the required rights for the API user.
To start the next steps the following needs to be arranged:
- A Exchange admin account
- At least one Exchange Kiosk license needs to be available.
1. Got to https://admin.exchange.microsoft.com/.
2. Open “Roles” and click “Admin roles”.
3. Click “Add role group“
4. Give a name and description (if desirable) to the ApplicationImpersionation group we will be creating. When done click “Next”.
5. Search for the “ApplicationImpersonation” right in the list, enable it and when done click “Next”.
6. Assign an Admin for the Role group we have just created and click “Next“.
7. Please check all the settings, and if they are all correct you can click “Add role group“.
Now the group has been created, all we have to do is assign the created API user to the role group as described below:
1. Open the newly created Role Group.
2. Go to the tab “Assigned” and click “Add“.
3. Search for the created API user and click on “Add“.
The user has now succesfully been added, you can continue to the next step.
preparartions fallback user
With these steps we will describe how the required rights can be assigned to the Fallback user.
You go through the step-by-step instructions by completing the steps described and continuing with the next step (tab) in the bar above.
WHY?
A fallback user is required to fall back on when necessary. This will happen when a person is not known or not correctly configured in TimeEdit or Exchange. When a booking is made the booking will be created with the Fallback user so the room is still reserved for the timeslot. The Fallback account needs to be available in TimeEdit and Exchange.
In this step we will describe how the necessary rights can be assigned on the Exchange side.
WHAT DOES IT YIELD?
After following this step-by-step instruction you will have configured the following:
- Assigned the required rights to the Fallback user
TIPS?!
The Fallback user needs Full Acces rights to all the rooms that will be monitored by the ORB. This can be done two ways, trough the Exchange Admin Centre or with Powershell.
We recommend Powershell because this will be less work for you, but the choice is yours!
To start the next steps the following needs to be arranged:
- A Exchange admin account.
- At least one Exchange Kiosk license needs to be available.
1. Go to https://admin.exchange.microsoft.com/.
2. Open “Recipients” and click “Resources”.
3. Search for the first room that will be monitored by the ORB with the search field or the list.
4. Open the resource by clicking it:
5. Press the button “Delegation”. When you’re there press the ”Edit” button underneath the option “Read and manage (Full Acces)”
6. Click “Add members”
7. Search for the created Fallback user and when added click “Save”.
8. Click “Confirm”.
9. All changes are now saved. You can go back to the first step and repeat this for all rooms that will be monitored.
To set the rights with Powershell the commands below can be used, if you want to use a script you are free to do so ofcrourse 🙂
Connect-ExchangeOnline
Add-MailboxPermission -Identity “NAAM VAN RUIMTE” -User “Fallback User Account” -AccessRights FullAccess -InheritanceType All
preparations OAuth 2.0
With these steps we will describe how the OAauth 2.0 authentication can be set up in Azure.
The ORB communicates with Exchange trough EWS, the authentication for this is handled by the OAuth 2.0 protocol. For further infomation about this protocol the following Microsoft page can be consulted: https://learn.microsoft.com/nl-nl/azure/active-directory/fundamentals/auth-oauth2
WHY?
OAuth 2.0 is an open standard which is used by Microsoft. It provides a safe way to authenticate within Azure.
WHAT DOES IT YIELD?
After following the steps you will have done the following:
- Created an OAuth 2.0 registration in Azure.
- Have safely stored the necessary authentication information for the ORB.
- An account with Azure admin rights
1. Go to the Azure Active Directory and select (or click the hyperlink) “App registrations”. Click “New registration”.
2. Give the application a recognizable name, in our example we will use “ORB OAuth Example“. Select the option: ”Accounts in this organizational directory only (Tenant naam only – single tenant)” and click on “Register”.
3. In this step we will be editing the Manifest. We will do this so the authentication can be set to App-Only. We will do this by clicking “Manifest” on the left hand side.
4. We need to edit three values from the “requiredResourceAccess” property. Namely the resourceAppId and the underlying ID and Type values. The values will need to be setup like described underneath. For further information the Microsoft documentation can be consulted. When all the changes are completed we can save the changes by clicking “Save“.
“resourceAppId“: “00000002-0000-0ff1-ce00-000000000000”,
“id“: “dc890d15-9560-4a4c-9b7f-a736ec74ec40”,
“type“: “Role”
5. Now we will navigate to “Certificates & secrets”. Click on “Client secrets” and select “New client secret”.
6. Give the client secret a recognizable name. In our example we will use “ORB Oauth Example secret“. Then choose how long the client secret may be valid, in our example we chose 180 days. When done click “Add” WATCH OUT! The client secret needs to be timely renewed by your organisation.
7. Copy the client password, and store it in a safe location. WATCH OUT! This password is only temporarily visible so make sure to save it.
8. Next go to the Tab “API permissions” and click: “Grant admin consent“. As the last step click: “Yes“
