EzioAuth (it's been a while)

Friday, Jan 31, 2025

Hey, it’s been a while. I really didn’t mean to leave such a gap between my last post and this one. I think I let perfect be the enemy of good at least a few times in the past few months. One thing that’s hard for me to do is to write about something and have it not be my definition of “high quality”, so although I’ve had ideas on new topics to write about in the past few months, I couldn’t really get myself to write and complete an entire post. I really need to make a little “notes” section on this page where I can write little snippets. I’d definitely post a lot more if I did. A lot has happened in the past few months though. I’m working on an app which might hopefully become something meaningful at some point in the future. I’ve always wanted to create a startup and since I’m (potentially) having meetings with a few VCs later this year, it’s been a bit nerve wracking since I’m working hard to create an MVP. On a similar note, I’m on the job market. It’s scary, and I’m unsure what the future holds, but for now I’m just gritting my teeth, holding my breath, and praying that the next week of my job hunt goes well. Anyway, I digress. The reason I’m writing this post isn’t to ramble about my life (though it is cathartic); it’s to talk about a thing I did build in it’s entirety.

Background

EzioAuth is a little CLI tool I built to solve a problem I was having when developing the app that I’m hopefully going to get funding for. The problem was retrieving access tokens from Keycloak. If you don’t know, Keycloak is an open-source identity an access management software. It can be used as a standalone OpenID Connect server. I’m using it to secure the app I’m building since I need multiple tenants and I’m too cheap to pay Auth0 out of my own pocket (they only give you one free tenant). Keycloak, like any good OIDC server, supports the authorization code flow (for more information, take a look at the openid specs, specifically the information here). Completing the authorization code flow successfully results in you receiving a valid JWT from the OIDC server which you can use to authenticate to a backend API that accepts the token. The core issue is that it’s annoying to get a token without going through the flow in a browser. I need tokens to test my API correctly since all endpoints are behind some kind of authentication, so I wrote a little Go program to do it. Embarassingly, my solution before Ezioauth was to build an entire, minimal frontend which configured all the Keycloak stuff correctly, and then I’d manually go through the flow and output the token in a paragraph tag on the page. Needless to say, this was not ideal.

EzioAuth

EzioAuth can be configured through command line flags, environment variables, a configuration file, or some combination of those. Once configured, it will start a callback server on localhost:<port> (port is configurable). It has a handler that listens on localhost:<port>/callback. Once started, it will prompt you to navigate to a URL printed out in the console. The URL points to the authorization server so that you can authenticate with it. The scope, client_id, redirect_uri, and response_type parameters (some configurable) are used to craft that URL. Once you authenticate, a page (served by the EzioAuth callback server) will be displayed telling you that you can close the tab. A message in the console will appear, telling you that the access token has been copied to your clipboard.

This is all well and good, but the actual time-saving bit of this comes on every subsequent request. EzioAuth caches the access token and refresh token returned by the authorization server in a cache file, which is stored at $XDG_CACHE_HOME/ezioauth/credentials.json (by default–it’s configurable). On subsequent runs, as long as the session established with the authorization server is still valid, there is no interaction needed aside from running the program; Ezioauth will just get the token for you and copy it to your clipboard.

If you’re only interested in using it, you can either

go install github.com/anishsinha-io/ezioauth
build from source, aka git clone git@github.com:anishsinha-io/ezioauth.git && cd ezioauth && just build && ./bin/ezioauth [OPTIONS]

If you’re also interested in how Ezioauth is implemented, feel free to read on (:

Implementation Details

Aside from the Go standard library, Ezioauth depends on xdg, cli, and clipboard. My justifications for these libraries were:

I don’t want to deal with Windows
I don’t want to deal with Windows
I hate flag from the Go standard library
I don’t want to deal with Windows

In all seriousness, I wanted to store data and cache files in the right places regardless of operating system, and have a cross-platform “copy-to-clipboard” abstraction. I used an external CLI package because I loathe flag in the Go standard library. It’s ugly, inflexible, and I generally am miserable when I use it. Anyway, here’s how the CLI is defined.


13 collapsed lines
1
package main
2

3
import (
4
  "context"
5
  "fmt"
6
  "net/url"
7
  "os"
8

9
  "github.com/adrg/xdg"
10
  "github.com/urfave/cli/v3"
11
  "golang.design/x/clipboard"
12
)
13

14
// config represents the application configuration. It is a global variable initialized by `cmd`
15
var config appConfig
16

17
// author represents the author of the application
18
type author struct {
19
  name  string
20
  email string
21
}
22

23
func (a author) String() string {
24
  return a.name + " <" + a.email + ">"
25
}
26

27
// cmd represents the CLI command that initializes and validates the application configuration
28
var cmd *cli.Command = &cli.Command{
29
  Name:    "EzioAuth",
30
  Version: "0.1.0",
31
  Authors: []any{
32
    author{
33
      name:  "Anish",
34
      email: "anishsinha0128@gmail.com",
35
    },
36
  },
37
  Copyright:   "(c) 2025 EzioAuth authors",
38
  Usage:       "Retrieve an access token from an OpenID server using the authorization code flow",
39
  UsageText:   "ezioauth [options]",
40
  Description: "EzioAuth is a CLI utility that lets you retrieve an access token from an OpenID Connect server using the authorization code flow.",
41
  Flags: []cli.Flag{
42
    &cli.StringFlag{
43
      Name:     "config-file",
44
      Usage:    "Path to the config file",
45
      Sources:  cli.EnvVars("CONFIG_FILE"),
46
      Category: "Server",
47
    },
48

49
    &cli.BoolFlag{
50
      Name:     "save-config",
51
      Value:    true,
52
      Usage:    "Save the configuration to the default config file",
53
      Sources:  cli.EnvVars("SAVE_CONFIG"),
54
      Category: "Server",
55
    },
56

57
    &cli.StringFlag{
58
      Name:        "server-auth-url",
59
      Usage:       "URL of the OpenID Connect authentication server",
60
      Sources:     cli.EnvVars("SERVER_AUTH_URL"),
61
      Destination: &config.Server.AuthURL,
62
      Category:    "Server",
63
    },
64

65
    &cli.StringFlag{
66
      Name:        "server-token-url",
67
      Usage:       "Token URL of the OpenID Connect authentication server",
68
      Sources:     cli.EnvVars("SERVER_TOKEN_URL"),
69
      Destination: &config.Server.TokenURL,
70
      Category:    "Server",
71
    },
72

73
    &cli.StringFlag{
74
      Name:        "server-client-id",
75
      Usage:       "ID of the client to authenticate against",
76
      Sources:     cli.EnvVars("SERVER_CLIENT_ID"),
77
      Destination: &config.Server.ClientID,
78
      Category:    "Server",
79
    },
80

81
    &cli.StringFlag{
82
      Name:        "server-client-secret",
83
      Usage:       "Secret of the client to authenticate against",
84
      Sources:     cli.EnvVars("SERVER_CLIENT_SECRET"),
85
      Destination: &config.Server.ClientSecret,
86
      Category:    "Server",
87
    },
88

89
    &cli.StringFlag{
90
      Name:        "server-redirect-uri",
91
      Usage:       "URL to redirect to after authentication",
92
      Sources:     cli.EnvVars("SERVER_REDIRECT_URI"),
93
      Destination: &config.Server.RedirectURI,
94
      Category:    "Server",
95
    },
96

97
    &cli.StringFlag{
98
      Name:        "server-scope",
99
      Usage:       "OpenID scope",
100
      Sources:     cli.EnvVars("SERVER_SCOPE"),
101
      Destination: &config.Server.Scope,
102
      Category:    "Server",
103
    },
104

105
    &cli.StringFlag{
106
      Name:        "callback-server-port",
107
      Usage:       "Port to listen on for the callback server",
108
      Sources:     cli.EnvVars("CALLBACK_SERVER_PORT"),
109
      Destination: &config.CallbackServerPort,
110
      Category:    "Global",
111
    },
112

113
    &cli.StringFlag{
114
      Name:        "credentials-cache",
115
      Usage:       "Path to where the app should cache the credentials",
116
      Sources:     cli.EnvVars("CREDENTIALS_CACHE"),
117
      Destination: &config.CredentialsCache,
118
      Category:    "Global",
119
    },
120

121
    &cli.BoolFlag{
122
      Name:     "skip-cache",
123
      Value:    false,
124
      Usage:    "Skip the cache and force a new token exchange",
125
      Sources:  cli.EnvVars("SKIP_CACHE"),
126
      Category: "Global",
127
    },
128
  },
129

130
  Before: func(ctx context.Context, command *cli.Command) (context.Context, error) {
60 collapsed lines
131
    configFile := command.String("config-file")
132
    var c appConfig
133

134
    xdgConfigPath, err := initXDGConfig()
135
    if err != nil {
136
      return ctx, err
137
    }
138

139
    if configFile != "" {
140
      if err := initFromFile(configFile, &c); err != nil {
141
        return ctx, err
142
      }
143
    } else {
144

145
      if err := initFromFile(xdgConfigPath, &c); err != nil {
146
        return ctx, err
147
      }
148
    }
149

150
    if config.Server.AuthURL == "" {
151
      config.Server.AuthURL = c.Server.AuthURL
152
    }
153

154
    if config.Server.TokenURL == "" {
155
      config.Server.TokenURL = c.Server.TokenURL
156
    }
157

158
    if config.Server.ClientID == "" {
159
      config.Server.ClientID = c.Server.ClientID
160
    }
161

162
    if config.Server.ClientSecret == "" {
163
      config.Server.ClientSecret = c.Server.ClientSecret
164
    }
165

166
    if config.Server.RedirectURI == "" {
167
      config.Server.RedirectURI = c.Server.RedirectURI
168
    }
169

170
    if config.Server.Scope == "" {
171
      config.Server.Scope = c.Server.Scope
172
    }
173

174
    if config.CallbackServerPort == "" {
175
      config.CallbackServerPort = c.CallbackServerPort
176
    }
177

178
    if config.CredentialsCache == "" {
179
      if c.CredentialsCache != "" {
180
        config.CredentialsCache = c.CredentialsCache
181
      } else {
182
        path, err := xdg.CacheFile("ezioauth/credentials.json")
183
        if err != nil {
184
          return ctx, err
185
        }
186
        config.CredentialsCache = path
187
      }
188
    }
189

190
    return ctx, nil
191
  },
192

193
  Action: func(ctx context.Context, command *cli.Command) error {
18 collapsed lines
194
    err := config.validate()
195
    if err != nil {
196
      return err
197
    }
198

199
    if command.Bool("save-config") {
200
      configFilePath, err := xdg.ConfigFile("ezioauth/config.json")
201
      if err != nil {
202
        return err
203
      }
204
      if err := config.save(configFilePath); err != nil {
205
        return err
206
      }
207
    }
208

209
    skipCache := command.Bool("skip-cache")
210

211
    return run(skipCache)
212
  },
213
}

The urfave/cli package allows you to declaratively define your CLI. What I really like about it is that you can define a destination for each flag, e.g. some pointer that you want the value of the flag written to, and that you can load flag values from environment variables. I use these features in most of the flags. This is cool because I can allow a user to provide configuration in a file, but allow environment variables and flags to take precedence over the config. Maybe one part of your config changes frequently but others stay the same, so you store most of the config in a file and pass flags for the rest of the arguments. Or maybe you just want to override values occasionally. urfave/cli makes it easy. The flag standard library package can rot in hell. Also, if you’re curious, appConfig looks like this:

1
type serverConfig struct {
2
  AuthURL      string `json:"auth_url"`
3
  TokenURL     string `json:"token_url"`
4
  ClientID     string `json:"client_id"`
5
  ClientSecret string `json:"client_secret"`
6
  RedirectURI  string `json:"redirect_uri"`
7
  Scope        string `json:"scope"`
8
}
9

10
type appConfig struct {
11
  Server             serverConfig `json:"server"`
12
  CredentialsCache   string       `json:"credentials_cache"`
13
  CallbackServerPort string       `json:"callback_server_port"`
14
}

The function which does the heavy lifting (called at the end of the Action function) is called run. It is responsible for loading cached token data (if any exists), and handling the following cases:

No existing credentials → prompt user to complete the flow again
Refresh failure → display an error message and prompt user to complete the flow again
Refresh success → copy the access token to clipboard.

In either case which requires the user to complete the flow again, the application generates a state parameter, crafts a URL to the authorization server, prints it out, starts the callback server, and blocks until the flow is completed. Upon successful completion, it will attempt to exchange the returned code for a token, cache the access and refresh token, and copy the access token to the user’s clipboard.

The run function is implemented as follows:

1
func run(skipCache bool) error {
2
  if cachedData, err := loadCachedTokenData(); err == nil && !skipCache {
3
    refreshed, err := refreshToken(cachedData.RefreshToken)
4
    if err != nil {
5
      fmt.Printf("Failed to refresh token (%v). Clearing cache...\n", err)
6
      os.Remove(config.CredentialsCache)
7
    } else {
8
      if err := cacheTokenData(refreshed); err != nil {
9
        return err
10
      }
11

12
      clipboard.Write(clipboard.FmtText, []byte(refreshed.AccessToken))
13
      fmt.Println("Token copied to clipboard")
14
      return nil
15
    }
16
  }
17

18
  state := createStateParam(16)
19

20
  authReqURL := fmt.Sprintf("%s?client_id=%s&redirect_uri=%s&response_type=code&scope=%s&state=%s",
21
    config.Server.AuthURL,
22
    url.QueryEscape(config.Server.ClientID),
23
    url.QueryEscape(config.Server.RedirectURI),
24
    url.QueryEscape(config.Server.Scope),
25
    url.QueryEscape(state),
26
  )
27

28
  fmt.Println("Please open the following URL in your browser to continue [cmd+click]:\n" + authReqURL)
29

30
  codeChan := make(chan string)
31
  go startCallbackServer(codeChan, state)
32

33
  authCode := <-codeChan
34

35
  data, err := exchangeCodeForToken(authCode)
36
  if err != nil {
37
    return fmt.Errorf("Failed to exchange code for token: %v", err)
38
  }
39

40
  if err := cacheTokenData(data); err != nil {
41
    return fmt.Errorf("Failed to cache credentials: %v", err)
42
  }
43

44
  clipboard.Write(clipboard.FmtText, []byte(data.AccessToken))
45
  fmt.Println("Token copied to clipboard")
46
  return nil
47
}

The callback server is started on localhost:<port> and a single endpoint is registered (on /callback) which validates the captured authorization code and state from the URL and sends it through the channel passed into the function. There’s also a function called exchangeCodeForToken which actually does the code-for-token exchange. It crafts an HTTP request to the authorization server and requests a token given the code. Lastly, I also want to mention that there are two utility methods (one to refresh a token and one to generate random state). The implementation of all of these is below:


14 collapsed lines
1
package main
2

3
import (
4
  "encoding/json"
5
  "fmt"
6
  "io"
7
  "log"
8
  "math/rand"
9
  "net/http"
10
  "net/url"
11
  "strings"
12
  "time"
13
)
14

15
// startCallbackServer starts a simple HTTP server that listens for the OAuth 2.0 authorization code.
16
func startCallbackServer(codeChan chan<- string, expectedState string) {
17
  http.HandleFunc("/callback", func(w http.ResponseWriter, r *http.Request) {
18
    query := r.URL.Query()
19
    code := query.Get("code")
20
    state := query.Get("state")
21

22
    if code == "" || state != expectedState {
23
      http.Error(w, "Invalid request", http.StatusBadRequest)
24
      return
25
    }
26

27
    fmt.Fprintln(w, "Authorization successful. You can close this tab.")
28

29
    codeChan <- code
30
  })
31

32
  log.Fatal(http.ListenAndServe(fmt.Sprintf(":%s", config.CallbackServerPort), nil))
33
}
34

35
// exchangeCodeForToken exchanges the authorization code for an access token.
36
func exchangeCodeForToken(authCode string) (tokenData, error) {
37
  client := &http.Client{Timeout: 10 * time.Second}
38

39
  data := url.Values{}
40
  data.Set("grant_type", "authorization_code")
41
  data.Set("code", authCode)
42
  data.Set("redirect_uri", config.Server.RedirectURI)
43
  data.Set("client_id", config.Server.ClientID)
44
  data.Set("client_secret", config.Server.ClientSecret)
45

46
  req, err := http.NewRequest("POST", config.Server.TokenURL, strings.NewReader(data.Encode()))
47
  if err != nil {
48
    return tokenData{}, err
49
  }
50
  req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
51

52
  resp, err := client.Do(req)
53
  if err != nil {
54
    return tokenData{}, err
55
  }
56
  defer resp.Body.Close()
57

58
  if resp.StatusCode != http.StatusOK {
59
    body, _ := io.ReadAll(resp.Body)
60
    return tokenData{}, fmt.Errorf("token exchange failed: %s", body)
61
  }
62

63
  var respData tokenData
64
  err = json.NewDecoder(resp.Body).Decode(&respData)
65
  if err != nil {
66
    return tokenData{}, err
67
  }
68

69
  return respData, nil
70
}
71

72
// refreshToken refreshes the access token using the given refresh token
73
func refreshToken(refreshToken string) (tokenData, error) {
74
  client := &http.Client{Timeout: 10 * time.Second}
75

76
  data := url.Values{}
77
  data.Set("grant_type", "refresh_token")
78
  data.Set("refresh_token", refreshToken)
79
  data.Set("client_id", config.Server.ClientID)
80
  data.Set("client_secret", config.Server.ClientSecret)
81

82
  req, err := http.NewRequest("POST", config.Server.TokenURL, strings.NewReader(data.Encode()))
83
  if err != nil {
84
    return tokenData{}, err
85
  }
86

87
  req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
88

89
  resp, err := client.Do(req)
90
  if err != nil {
91
    return tokenData{}, err
92
  }
93

94
  if resp.StatusCode != http.StatusOK {
95
    return tokenData{}, fmt.Errorf("token refresh failed: %s", resp.Status)
96
  }
97

98
  var respData tokenData
99

100
  if err := json.NewDecoder(resp.Body).Decode(&respData); err != nil {
101
    return tokenData{}, err
102
  }
103

104
  return respData, nil
105
}
106

107
// createStateParam generates a random string of the specified length. It can be used as the OAuth 2.0 state parameter.
108
func createStateParam(length int) string {
109
  const charset = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
110
  result := make([]byte, length)
111
  for i := range result {
112
    result[i] = charset[rand.Intn(len(charset))]
113
  }
114
  return string(result)
115
}

Final Notes

EzioAuth was fun to make. Also, if you haven’t caught on, the name is a pun. It’s a reference to Assassins Creed and it also sounds kind of like “Easy OAuth” if you say it fast enough :P. It’s been really useful to me and if you want to try it out or star it on GitHub I’d be really grateful. Also, more detailed docs on how to use it are on the readme, along with the unabridged source.

I’ll try to post more frequently! Hopefully at some point I’ll get around to making a “notes” section. Anyways, I hope this was useful to someone! See you next time (:

openid-connect

cli