CLI to manage OAuth 2.0 access tokens

• Features
• Usage
  • Request new access token
  • Refresh access token
  • Show access token
• Installation
• Configuration
  • Google
  • Microsoft
• FAQ
• Sponsoring

• OAuth 2.0 support:
  • Authorization Code Grant ^{rfc6749 #4.1}
  • Refreshing an access token ^{rfc6749 #6}
• PKCE support ^rfc7636
• Native TLS support via native-tls crate (requires native-tls feature)
• Rust TLS support via rustls crate with:
  • AWS crypto support (requires rustls-aws feature)
  • Ring crypto support (requires rustls-ring feature)
• Fake HTTP redirection server
• Shell command and keyring storages (requires command and keyring features)
• Shell command and system notification hooks (requires command and notify features)
• JSON support with --json

Ortie CLI is written in Rust, and relies on cargo features to enable or disable functionalities. Default features can be found in the features section of the Cargo.toml, or on docs.rs.

$ ortie auth get

Created authorization request with:
 - state: RWdzST0ybUIzT1wtMSF9OCMmJHJUVmJrUmhhU0haLz4
 - pkce: oJ-rEXNu9YzqpCWVIPOwD5KvMhLAT73dstk0jye8nZ6

Sending authorization request to your browser…
Spawning fake HTTP redirection server…
Waiting for redirection…

Go to your browser, follow the instructions, then you should see:

Authorization succeeded!

Go back to your terminal, you should see:

Continue authorization process…
Access token successfully issued (expires in 1h)

In case the redirections fails, for example:

$ ortie auth get

Created authorization request with:
 - state: RWdzST0ybUIzT1wtMSF9OCMmJHJUVmJrUmhhU0haLz4
 - pkce: oJ-rEXNu9YzqpCWVIPOwD5KvMhLAT73dstk0jye8nZ6

Sending authorization request to your browser…
Spawn fake HTTP redirection server…
Error: Permission denied (os error 13)

Go to your browser, follow the instructions, then copy the URL you are redirected to (it should fail since the fake HTTP redirection server did not start).

Go back to your terminal, and complete the authorization flow:

ortie auth resume \
  --state RWdzST0ybUIzT1wtMSF9OCMmJHJUVmJrUmhhU0haLz4 \
  --pkce oJ-rEXNu9YzqpCWVIPOwD5KvMhLAT73dstk0jye8nZ6 \
  https://localhost/?code=M.C521_BAY.2.U&state=RWdzST0ybUIzT1wtMSF9OCMmJHJUVmJrUmhhU0haLz4

$ ortie token refresh

Access token successfully refreshed (expires in 1h)

$ ortie token show

EwA4BOl3BAAUcDnR9grBJokeAHaUV8R3+rVHX+IAAQfw9oZLztQS8bo8NvyWmbs…

The --auto-refresh argument (as well as the config option auto-refresh = true) automatically refreshes expired tokens.

You can also inspect token metadata:

$ ortie token inspect

Token type: bearer
Issued: 22h 51m 1s ago
Expires in: 52m 38s
With refresh token: true
With scope: https://outlook.office.com/IMAP.AccessAsUser.All https://outlook.office.com/SMTP.Send

Ortie CLI can be installed with the installer:

As root:

curl -sSL https://raw.githubusercontent.com/pimalaya/ortie/master/install.sh | sudo sh

As a regular user:

curl -sSL https://raw.githubusercontent.com/pimalaya/ortie/master/install.sh | PREFIX=~/.local sh

These commands install the latest binary from the GitHub releases section.

If you want a more up-to-date version than the latest release, check out the releases GitHub workflow and look for the Artifacts section. You should find a pre-built binary matching your OS. These pre-built binaries are built from the master branch, using default features.

Ortie CLI can be installed with cargo:

cargo install ortie

With only Vdir support:

cargo install ortie --no-default-features --features vdir

You can also use the git repository for a more up-to-date (but less stable) version:

cargo install --locked --git https://github.com/pimalaya/ortie.git

Ortie CLI can be installed with Nix:

nix-env -i ortie

You can also use the git repository for a more up-to-date (but less stable) version:

nix-env -if https://github.com/pimalaya/ortie/archive/master.tar.gz

Or, from within the source tree checkout:

nix-env -if .

If you have the Flakes feature enabled:

nix profile install ortie

Or, from within the source tree checkout:

nix profile install

You can also run Ortie directly without installing it:

nix run ortie

The wizard is not yet available (it should come soon), so the only way to configure Ortie CLI is to copy the sample config file, to store it either at ~/.config/ortie.toml or ~/.ortierc then to customize it by commenting or uncommenting the options you need.

You will also need a registered application. This depends on your OAuth 2.0 provider. You can either use an existing application (public registration like Thunderbird) or register your own application. The first option is definitely simpler.

See public Thunderbird application credentials for various providers at github.com/mozilla.

endpoints.authorization = "https://accounts.google.com/o/oauth2/auth"
endpoints.token = "https://www.googleapis.com/oauth2/v3/token"
scopes = ["https://www.googleapis.com/auth/carddav", "https://mail.google.com"] # choose the right scope for your usage

Using public Thunderbird application:

client-id = "406964657835-aq8lmia8j95dhl1a2bvharmfk3t1hgqj.apps.googleusercontent.com"
client-secret.raw = "kSmqreRr0qwBWJgbf5Y-PjSU"
enpoints.redirection = "http://localhost"

Using your own application:

client-id = "<your-client-id>"
client-secret = "<your-client-secret>"

endpoints.authorization = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize"
endpoints.token = "https://login.microsoftonline.com/common/oauth2/v2.0/token"

Using public Thunderbird application:

client-id = "9e5f94bc-e8a4-4e73-b8be-63364c29d753"
endpoints.redirection = "https://localhost"

Using your own application:

client-id = "<your-client-id>"
client-secret = "<your-client-secret>"

• pizauth: daemon-oriented alternative
• oama: haskell alternative
• mutt_oauth2.py: python script alternative

Special thanks to the NLnet foundation and the European Commission that helped the project to receive financial support from various programs:

• NGI Assure in 2022
• NGI Zero Entrust in 2023
• NGI Zero Core in 2024 (still ongoing)

If you appreciate the project, feel free to donate using one of the following providers: