oauth2ms: XOAUTH2 compatible O365 token fetcher

Table of Contents

• Overview
• Dependencies
• Installation
  • XDG CONFIG HOME
• Usage
  • Encryption
• TODOS

Overview

This tool can be used to fetch oauth2 tokens from the microsoft identity endpoint. Additionally, it can encode the token in the XOAUTH2 format to be used as authentication in IMAP mail servers. Example configuration for emacs given in steps.org.

Dependencies

Requires mbsync >= 1.3. More information available at: https://github.com/harishkrupo/oauth2ms/issues/2#issuecomment-846464452

Installation

Clone the repository and install the requirements.

pip install -r requirements.txt

Then copy the oauth2ms file to any location in your $PATH.

XDG CONFIG HOME

For the app to locate your config file, the $XDG_CONFIG_HOME environment variable must be set. It is generally set to $HOME/.config.

Usage

Create a config file with the below details at $XDG_CONFIG_HOME/oauth2ms/config.json

{
    "tenant_id": "TENANT_ID",
    "client_id": "CLIENT_ID",
    "client_secret": "CLIENT_SECRET",
    "redirect_host": "localhost",
    "redirect_port": "5000",
    "redirect_path": "/getToken/",
    "scopes": ["https://outlook.office.com/IMAP.AccessAsUser.All"]
}

If you aren’t sure how to fetch the the TENANT_ID, CLIENT_ID and CLIENT_SECRET values, read more on steps.org. After creating the config file, execute oauth2ms, it should pop up a browser window asking you to login. Once logged it, it should redirect you to a page which says “Authorization complete.”. On the terminal you should see the token printed. Subsequent fetches should use the refresh token to get the access token. Call oauth2ms with the --encode-xoauth2 to get the token in XOAUTH2 format.

oauth2ms --encode-xoauth2

Optionally, you can add “https://outlook.office.com/SMTP.Send” to the list of scopes to use the token for stmp. See steps.org for information on configuring emacs for sending mail via smtp with xoauth2.

Encryption

Encryption of the fetched token cache can be enabled using the -e (--encrypt-using-fingerprint) option. The option takes the email/fingerprint to identify the gpg key to use for encrypting and decrypting the token cache.

oauth2ms -e <gpg recipient fingerprint>

TODOS

• [x] Use gpg to encrypt the fetched data
• [ ] Add support for encrypted config.json
• [ ] Support more than one account at a time