Email OAuth 2.0 Proxy - Transparent OAuth 2.0 for Basic Auth IMAP to Exchange

all right today I'm going to walk through setting up something called email auth to proxy the reason I want to walk through these instructions is that I think it'd be particularly helpful I know that if I had them when I needed them I would have been very very helpful a few weeks ago I was asked to take an existing PHP application it was like this Legacy PHP app that was written by one guy and who had since you know left the company and nobody knew how to maintain it it was uh it has no documentation um there's no Dev environment there's no tests there's no comments and uh and it's an application that's heavily relied on uh in this company so I was asked with like a week to spare something like that you know can we you know would I be able to take this app and make it compliant with oauth 2. um you know with Microsoft deprecating basic Authentication and uh so I I mean I was I was certainly up for giving it a shot and but I I it was quite interesting trying to come up with a strategy for making a change to this application it wasn't just as simple as okay so fine you don't have instructions for a Dev environment but you know the the database was something like I something like a couple hundred gigs it was just ridiculously huge um so I couldn't easily take a copy like a dump of the database and put it on the on my laptop and grab the code and try to do any kind of local testing uh it made me very leery of making any changes on the server um so you know how is I going to make this application work with oauth 2 in exchange it seemed like a daunting task and so I was um I was Googling around and I you know I finally stumbled on uh this this project here email oauth 2 proxy and the beginning of the the first sentence of the description here transparently add oauth 2 support to IMAP and I'm thinking you know is that is that possible is that what I think it is because if it is that potentially means no code changes to this extremely uh brittle application and uh so you know the long story short is that I I did manage to get this installed and I got it it exchange and Azure set up properly and uh and there were no code changes the only change we had to make in the actual code was a change to the host that IMAP connected to so you know just to point to the proxy and then the proxy off to Office 365 were Exchange so I um I figured I've been watching this uh this you know this project on GitHub here for a little while and there's definitely been a number of people seem to have issues getting I know it was tricky for me uh well the the oauth uh mechanism I guess you could call it is the client credential flow and that's where you know the user is not directly involved it's when you have an application on a server and it needs to it needs to use oauth well this is a way to uh to set up oauth in a way that we you don't need that external interaction and uh all the all the grants are applied by the administrator on the server and that's so I'm going to walk through setting up Azure and exchange and then we're also going to build a virtual machine that I've got uh like a vagrant and virtualbox virtual machine if you want to walk through it really step by step with me we'll get that going and then finally install email oauth 2 proxy and then test that out with just a really simple PHP app so um I'll have this I'll close this here and I've got the step-by-step instructions here that I'll link to in the in the description and then you know you'll you'll clone the repository and then you can follow along and run the same VM that I am so before we get started here maybe what I'll do is I'll get the VM building like I'll get that going um actually sorry I already did get that going and you can see that it uh you know it's all this takes a bunch of time and I I got that built before but the command to do that is vagrant up and so you just go to the root of the project in this case sir the directory off the root of the project um and do vagrant up and it'll bring it'll bring the VM up configured and ready to go so we'll leave that for now and we'll go back to the instructions and so the first thing we need to do is get to Azure so I've got Azure up here and we'll go back to the instructions so it says to go to active directory app registrations new registration so we'll go to Azure active directory and then down here on the left app at just app registrations and then view registration and I'm going to call this John test and we leave this at single single tenant and click register and we'll go back next we'll create a client Secret so I'll just go over here and add the secret and new client secret I'm going to call it just drawn test client Secret and it was six months is fine right this is just for a test and on this page you want to pay attention to grabbing the value see this column the value column and you want to copy you want to copy that secret that client secret not the secret ID but the secret value right so we'll copy that and I'm going to put it in a a notepad text file here I'm just going to put in the client secret there and we'll use this later if if you don't um if you don't copy it you won't be able to see this again like once this page is once you refresh this page for security reasons that won't display so open up a file I'd suggest open up a file and save it there and I also put my email address up here or this is the uh this is the mailbox account that you want to have access to so we'll save that and we'll just keep that there and grab these values later when we need them okay so back to the instructions so we created the client secret next we want to add permissions so we go to API permissions add permission apis my organization uses so we go to API permissions and let me go add permission and apis my organization uses so I've got a huge list there and what we want to do is search for Office 365 exchange online so I'll just copy that search and you can see that come up we want to select that and then it says okay we want to go to click application permissions and then search for and select IMAP access as app so we're going to do application permissions and then search for IMAP accesses map we'll expand that and select that permission and add it and at the bottom here so we add it and then we want to click Grant admin consent and click yes if you don't see this you're going to have to have somebody who does have permission to do this but in my case I got to set up a test account with Office 365 and I'm the admin so I can grant that click yes and so that actually leaves us at a point where we've configured as we've done everything we have to do with Azure in terms of configure configuration but now we have to configure exchange right because that's what we want to access so we want to first start to configure stage we have to do this through Powershell and I've got Powershell up here make sure that you that you launch it as the administrator like when you right click on it run as administrator and uh let's go back to the instructions this here we're installing these modules Azure ad active directory and exchange online management so we copy that and we'll paste that in and that should uh and yeah so it's warning us about this it says it's an untrusted Repository from what I understand PS Gallery is basically is a trustworthy repository so I'm just going to put in a here for all and we're just now installing both of those and I'll go back here while it's doing that so we installed the modules and that or that's doing that right now and then next we want to import the modules because now we're going to do we're going to run some commands that reference functionality in those modules so that completed and now we're doing the import module and we're going to import both of those and we go back to the instructions here I want to set these variables because we're going to use them in the commands down here and instead of having to copy and paste while we're doing that let's let's put them into variables and then we'll reference them so I'm going to copy this so tenant ID and here it get the tenant ID go to overview and we go back here right so we got directory or tenant ID we'll copy that and put that in make sure that you got quotes around the value and then um so we got tenant now we want client client ID and let's go back to Azure and get the client so that's application or client ID we copy that and there we go the next next one was the mailbox so that's the if we go back to notepad wherever notepad is there we go sorry I'll get that one in there first so the mailbox we want to set that to the the uh the account that we want to access the mailbox account so in this case that's the same as my administrator account that's actually my account but for you it likely is different um next okay so we got the mailbox and so we're gonna first connect to Azure okay so we're running Azure here and we're specifying the tenant ID and it's going to prompt us to authenticate so I'm going to use my my credentials here as the administrator so you'll put your you know you'll authenticate as your user and I've got a password here that I need to authenticate with me and I'll just skip this but you can see it here that we've now authenticated and we'll now connect to exchange so we're we're uh we got Azure and then exchange and then we'll be able to then we'll be able to grab information from Azure and use it with our commands to exchange so I'm already signed in I'll just do that again for exchange I'll skip that for now it's done and here we want to get the service principle from Azure so we'll grab that and we've got you can see how we're referencing the client ID or Azure calls it the app ID and actually what this has done if I do service principle uh what is it RL I think or LR oh what is that command FL there now you can see that this is the details of the service principle and we'll go back to the instructions close that so now next we we want to configure the service principle and exchange so this command is now going to exchange we got the data from Azure and now we're configuring it in exchange and we did that and now now that we've got the principle in exchange we need to Grant the principal access full access in this case to the mailbox okay oops let's try that again there okay so next I've got build Bev environment we know that that's been accomplished and now we want to install email oauth 2 proxy the vagrant SSH if you're running it on Windows uh and through segwind there's a there's a bug and so you can't you can't use vagrant SSH without some issues if you hit Ctrl C to uh to to you know control break out of a program it'll mess up your terminal so I actually have a workaround for that and so this is just an SSH command so um with the details of grabbing the port you know what's the guest port for on the VM and uh and anyway so we'll walk through that uh here so just to log into the VM you just do bin SSH VM and yes and I like using tmux and I'm going to split this so that we can have multiple panes per window and let's see what do we want to do first go back to the instructions so we ssh in we want to get the release of oauth email oauth 2 proxy so this is as of you know this morning November 3rd this is early morning this is the most recent okay and then we'll unzip that and CD into the directory and from here we'll then run this command to install the requirements you'll notice the no GUI requirements this is because we're running it on the server behind the scenes and uh we'll get all those installed um next now that we've got that all the all of the requirements for oauth2 proxy email oauth to proxy are installed we want to make a copy of the sample config now the original config for email oauth 2 proxy is quite verbose so I've distilled it down to exactly what we need as like just minimally and so we'll just click I mean I've got this open in the root of the project of the video directory anyway and what do we want here we want this sample one we want to copy Ctrl C and paste and I want to rename that to email proxy.config and here we just you know we're defining the service um we're going to listen um to uh import 1993 as opposed to 993 and that's gonna you know we're running on you know localhost and for the account email we'll go back to our Notepad and grab the email address and paste it in there and next we see we've got the tenant ID that we need to replace and we'll go back to Azure for that we'll get the tenant ID go back to the config so here's there's the tenant next is the client ID which is the application ID as far as Azure is concerned and then here we want the client Secret go back to the credentials file and grab the secret [Music] okay so now we'll save that we'll go back to the instructions okay [Music] um now it says to we want to create a backup of the of the original config so I know that we're already in this directory so we'll move or rename that file so here we'll do this move email config right email proxy config to the original and then what we want to do is take is make a symbolic link to slash vagrant and if you're not familiar with vagrant vagrant by default Maps slash vagrant to the root of where the vagrant file is defined so the um or where you've launched it there where you've launched vagrant up so what we're going to do is reference we're going to have a symbolic link from this directory to our to our shared directory in Windows um to reference that config that we just made and let's go back here okay so that's all set up we can do a chat on the email proxy config just sort of show it there that looks that looks right go back to our browser and the instructions so next we're going to test we're going to we're going to test the setup using Apache PHP and IMAP and so I've got a got the proxy there and then we'll do this first so on the on the window on the right here we'll get Apache going and I have a script that that will basically launch the docker container and we just want to change this username to IMAP username we'll change that to the email address of the user and the password and it act that because this this isn't basic auth anymore right the password isn't it's it's not used for authenticating to exchange but the password still has a use with email oauth2 proxy I'm going to just put this in password password one and for now it doesn't really matter what you specify because we've got it all set up through auth2 but then after we do this test I'm going to set up the client credentials so that it's encrypted which is a way to secure uh to add some security to the installation but we'll get to that after we do this initial test so in that case that's where password is going to be important but right now the password doesn't play a role so we'll start it up and because it I've got a Docker container here that it's going to run it has to go out and grab the the image from docker and hopefully this won't uh before when I was at test well yeah so I was going to say before when I tested it it seems to pause sometimes and I don't know like by hitting enter it seems to help I'm not totally sure why anyway I'm not sure maybe I'm Dreaming but anyway so we got we've got Apache running and we'll go back to the instructions so then view PHP app so we'll open that link in a new tab and you can see now that we've got the web server up and we're accessing the port um if you want to test the link here PHP info you can see that I'll show you that I've got IMAP installed and close that and so the next the next thing to do here and maybe well maybe I didn't uh yeah actually I skipped starting up the proxy so I got to get that got to get that started so we'll do that on the other side here on the left and you'll see it says here listing for authentication requests connect your email client to begin so our email client is actually the PHP app and I'll bring that up here so in yeah there it is testy test IMAP connect and you can see that it's grabbing the username and password from the environment and the uh this all gets translated by the proxy those requests but this will connect to the mailbox and then it'll Loop through the messages okay so let's see if we can't it's going to bring that up with that okay let's see if this works so I'm going to click on testimap connect and sure enough it actually worked the first time so that's that's pretty cool the uh now what I'm going to do I'm going to send myself an email just to just to prove that this is working and I'll just give it a couple seconds so I just sent it now I'll hit refresh and just see if we end up seeing it no not yet so we've got two of these testing one two three so let's refresh that again and there it is now we've got you know three of them so we know uh that that's working which is really cool and you can see that there's lots of things happening here in the logs um you know between the PHP app and the proxy uh let's go back to the instructions Okay so we've got these set up and we proved that it works um one thing I'll try just for demonstrating just for demonstration purposes is I'm shutting down Apache I'm going to change the password here to password two and if you take a look at uh we've we do a refresh here you'll notice that it doesn't have any impact right the password doesn't that's it's not authenticating through that those means anymore the um but what we will do now is encrypt the client secret and that's where the password matters because when we send the proxy the password we're going to configure it so that uh this this config here encrypt client secret on first use when that's the case it's going to use the password we send it to encrypt the to encrypt the uh the client Secret and then so any any uh subsequent requests have to have that correct password so it's pretty cool because it ends up encrypting the the key the client secret which is nice um and then but it also ends up becoming an authentication mechanism for the for the clients connecting to the proxy you have to have that you have to have the right password now and and otherwise it won't decrypt the the client's secret can't be decrypted properly um okay so I want to show you before we do the encryption I want to bring up the sample so like you remember that um we set this up but you might notice that we didn't set an access token or the accent access token expiry and you'll notice it even more so now if we do a view would wrap and you'll notice like okay there's this config file it grew considerably since we originally made it and that's why and that's because the application actually stores these values it reads the config in but it also uses the config as a as a config store um which is a little unusual I was kind of surprised at it and one thing that you have to really be careful about is if I so I say okay well I want to set this to Crypt client secret of first use so I set it to True right and then I I go back to the uh the app and uh I'm not sure why that oh did I we'll see that let's start with that Apache again okay so we're gonna we're gonna stop the um the proxy and we'll go back to the proxy config in um in Visual Studio code and and you'll notice that this was set back to false and that's why and that's because when you when we stop the application the application dumps the config back to the config file so if you want to make any config file changes you need to make sure you make them when the application isn't running so we're going to set this to true and we're also going to get rid of these in order for this to be in order for this to work and for it to be the first use we can't have a valid access token in there so we have to take out what we didn't add right this is what the App application added when we set up the connection to exchange so let's save that and we're saying encrypt on first use and we've got our client secret listed there so we want to see what happens now when we start when we start the proxy so we'll start the proxy up again and we'll go and see if anything has changed yet it doesn't look like anything's changed but we haven't used it yet so let's go back to the um this list here so we're going to run the command to connect and get the emails so it's doing its thing and it's done it worked and now when we look at the config you'll notice that this has been written to now but where's the client's secret the client secret is not there anymore it's got the token salt access token and then down here it's now got client secret encrypted okay so that's that's pretty cool because now that that's encrypted and we've got a more secure situation that's not wide open and we can test that by going back to uh let's go back to our Apache install and we'll we'll shut down Apache and here we'll change the password to like say to password three it was at password two when we were testing it there when we generally when we generated the uh encrypted the client secret so now we'll change it to password three and go back to our browser and hit refresh and now we get you know I cannot authenticate to IMAP server so you can see that this is working now if we go or sorry it's working in the sense that it's keeping us locked out because we don't have the right password if we change the password back to password 2 and we go here and refresh you know now was able to decrypt the password properly and and do it and and have the proper credentials to set up the connection with oauth so I'm trying to think if there's anything else that uh I need to cover here um yeah I don't I think that I think that basically it's basically it um yeah if you if you have any questions please feel free to ask them in the comments um and I I really hope that uh people find this useful I know if I if I had these instructions it would have been a big help so anyway let me know what you think and uh I'll see you in the next video

Channel: Jonathan MacDonald

Views: 4,383

Keywords:

Id: GgC42YOBEak

Length: 30min 2sec (1802 seconds)

Published: Thu Nov 03 2022