OOauth2 Script

The script ooauth2.py is a python script that can be used to obtain the initial refresh token and access token for an app, or to renew an access token, and in both cases obtain the encoded base64 string that is used to add to an authenticate command in an IMAP or SMTP server.

The script assumes that you already registered your app with Microsoft, and that you were given a client-id. For purposes of giving examples, our app will be Alpine. You will see that the name of the app will appear in some of the images below, but we will never give the name of the app in the command line, since it is not necessary.

Microsoft only requires a client-secret for web apps. This script does not use the client-secret, so it cannot be used for web apps. For purposes of this demonstration we assume the client-id is f21dac2f-9145-665a-a876-fde739fe41fb, so we use the option --client_id=f21dac2f-9145-665a-a876-fde739fe41fb in the examples below.

Microsoft asks you to chose the tenant for your app. Your app might be an app for an organization, school, work, a mixture of these, or for everyone. We assume here that we want to use an app that can be used by everyone in the world. This is the default option for the script, but if you want to use a special tenant, you would specify it by adding the --tenant option. For example --tenant=organization. In none of the examples below we use the --tenant option, and this is equivalent to using --tenant=common.

• In order to get the initial refresh token and access token, with the default tenant, you would use a command like
   
  ooauth2 --generate_refresh_and_access_token --client_id=f21dac2f-9145-665a-a876-fde739fe41fb
  The script will give you a url and a code.
   
  To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code BPXAD4YXL to authenticate.
  Go to the URL above, complete the authorizaion process, and press ENTER when you are done
   
  Open the url with a browser and enter the code BPXAD4YXL, as indicated above, in the box, and click Next.
   
  
   
  You will be redirected to login with your username and password.
   
  
   
  After a succesful login, you will be asked to authorize the app by clicking Yes.
   
  
   
  Once you have authorized the app, you will be given a notice that the process is over.
   
  
   
  Now you close this window in the browser and go back to the script. All you have to do is to press ENTER. The script ignores any input you give to it. Then the script contacts Microsoft servers and prints out the Refresh Token, Access Token, and the amount of time the access token is valid. Here is a sample output. Notice that the real output is very long, but each output is given in one line. For purposes of clarity, we have truncated these values.
   
  Refresh Token: MCfW7m!...
  Access Token: EwBIA+l...
  Access Token Expiration Seconds: 3600
   
  You should save the Refresh Token in a file. because you will use it later to generate more access tokens. Saving the access token in a file is also a good idea, if your program requires you to input this string.
   
  
• Another way in which you can use this script is by requesting a new access token. For this you also need the tenant, client-id and refresh token that you got in your previous process. You only need a new access token when the one you have has already expired. The refresh token might contain characters such as !, *, $, etc. that could be interpreted by your shell, and so your string might need to be escaped before copying it. Since this string is very long, it is better to save the refresh token in a file. That file would be one line long, containing the value of the refresh token. We assume we saved the refresh token in the file refresh-token.txt. Then the command you would use to get a new access token would be
   
  ooauth2 --generate_access_token --client_id=f21dac2f-9145-665a-a876-fde739fe41fb \
  --refresh-token=`cat refresh-token.txt`
   
  this will give you an output that looks as follows (line has been shortened for brevity)
   
  EwBIA+l3BAAUFFpUAo7J3Ve0bjLBWZW.....
   
  Observe that in this case the output does not contain the prefix "Access Token". It is just the raw access token, and can be redirected to a file, or captured by another program.
   
  
• The last way to use this script is by asking the script to encode the access token so that it can be placed as part of an IMAP "AUTHENTICATE XOAUTH2" command or a SMTP "AUTH XOAUTH2" command. This is done by adding --encoded to the previous examples. In this case, you will not see the access token. Given that the authentication commands with XOAUTH2 require your username, you must also provide it. Here is an example of the use of the script while obtaining the refresh and access tokens for the first time, but we receive the encoded string instead of the access token:
   
  ooauth2 --generate_refresh_and_access_token --client_id=f21dac2f-9145-665a-a876-fde739fe41fb \
  --encoded --user=YourId@outlook.com
   
  a sample output looks like
   
  Refresh Token: MCfW7m!...
  dXNlcj1lZHVhcmRv...
  Access Token Expiration Seconds: 3600
   
  Observe that the encoded string is the only line of the three lines that does not contain a prefix, and therefore is the only line that does not contain a colon.
   
  The second use is to obtain a new access code from a refresh token. This could be done with a command such as
   
  ooauth2 --generate_access_token --client_id=f21dac2f-9145-665a-a876-fde739fe41fb \
  --refresh-token=`cat refresh-token.txt` --encoded --user=YourId@outlook.com
   
  a sample output looks like
   
  dXNlcj1lZHVhcmRv...
   
  and this can be captured directly by other programs or sent directly to a file.

Please send me any and all feedback about this script to eduardo.chappa@gmx.com. New versions of this script can be found in the scripts directory of the Alpine repository at https://repo.or.cz/alpine.git/tree/HEAD:/scripts

Page created on Sun Jun 14 01:55:49 MDT 2020.