RFC 1: CLI Authentication in other STACKIT applications (SDKs, Terraform Provider)

[marceljk]

RFC 1: CLI Authentication in other STACKIT applications (SDKs, Terraform Provider)

Context and Goal

Currently the STACKIT SDKs and Terraform Provider support the Key Flow and Token
Flow authentication. The STACKIT CLI supports beside these two methods also the
authentication with the personal user account. This kind of authentication is
more convenient because it eliminates the effort of creating a new service
account, grant it permissions, creating service account credentials and
configure the application to use these credentials.

So to improve the overall user experience in authenticating within the STACKIT
applications, we want to reuse the more convenient authentication with the
personal user account in other applications e.g. STACKIT Go SDK and STACKIT
Terraform Provider.

Requirements for the CLI Authentication

We set some requirements for this new feature:

• Strong dependency between CLI and SDK should be avoided
• Users should explicit enable the CLI Auth to be aware of this feature
  • Users shouldn't be confused of the behavior of the CLI Auth
• Provide an easy way to authenticate in other STACKIT applications (e.g.
  Terraform Provider)

Target Architecture

STACKIT CLI

The STACKIT CLI will get a new subcommand group which will only be used for the
authentication in other applications. The new commands should be similar to the
existing commands, with the difference that the login session will only be used
for other STACKIT applications and not in the CLI itself. This ensures that
future breaking changes of the existing $ stackit auth commands will not
influence the authentication for the other applications and we have more control
over the interface between the CLI and the Applications that uses it to
authenticate. If users have to login to different accounts within the CLI itself
and with another account to all other applications, this would be possible as
well. The users would gain more control over the authentication within the CLI.

The CLI should only provide the access-token and refresh-token, there will be no
additional configuration shared. So if users need to use a custom endpoint, they
have to configure it in the CLI itself before calling the login command and need
to set custom endpoints in the STACKIT Application e.g. Terraform Provider, SDK.
Synchronizing other configurations lead to unexpected behaviors from user
perspective.

Interface

The interface between the CLI and the application, can be implemented in
different ways.

Option 1: Using the keychain

In Option 1, the CLI would store the credentials for the CLI Auth for other
applications in the keychain, like it already does for the CLI credentials. With
the difference, that it would store it under a different name, to not mix them,
with the existing keychain entries of the CLI.

Pros:

• Keychain acts as a secure layer, to not expose the credentials
• No direct dependency to the CLI

Cons:

• The OS must have a keychain
• Would require to refresh the token inside the SDK
  • New token should be written back to the the origin

Option 2: Using a new file

In Option 2, the CLI would store the credentials for the CLI Auth for other
applications in a new (json) file.

Pros:

• Can be used on every system
  • Would work on systems without a keychain
• No direct dependency to the CLI

Cons:

• The file could be access by any process
  • Potential credentials leak
• Would require to refresh the token inside the SDK
  • New token should be written back to the the origin

Option 3: Accessing the credentials by executing a command

In Option 3, the CLI would get a new command, similar to
$ stackit auth get-access-token. This new command would only exist to share
the application credentials.

Pros:

• Independent of how the credentials are stored from reader perspective
• CLI could return only valid credentials
  • No additional checks in the SDK required

Cons:

• Sharing more data can be difficult, like e.g. the refresh-token
  • If we want to extend the shared data in the future, this could lead to
    breaking changes, because the output of the CLI would change.
• Every process could access the credentials
• Stronger dependency to the CLI
  • Relies on CLI commands and their output

STACKIT SDK

On default the feature will be disabled and need to be explicit enabled by the
developer who uses the SDK. To enabled this feature, it must be explicit enabled
when creating the service client.

package main

import (
    "fmt"
    "os"

    "github.com/stackitcloud/stackit-sdk-go/core/config"
    "github.com/stackitcloud/stackit-sdk-go/services/foo"
)

func main() {
    // Create a new API client, that will authenticate using the CLI authentication
    _, err = foo.NewAPIClient(
        config.WithCliAuth(),
    )
    if err != nil {
        fmt.Fprintf(os.Stderr, "[FOO API] Creating API client: %v\n", err)
        os.Exit(1)
    }
}

The SDK will read the stored access-token and refresh-token from the CLI, to
authenticate in the STACKIT SDK. When at the same time a service account key or
token is explicit defined in the SDK client, they will be tried first. If both
fails, it will try as last option to use the CLI authentication.

Terraform Provider

This feature will be implement in our STACKIT Terraform Provider as well. Here
the authentication will be also disabled on default and must be explicit enabled
by setting cli_auth = true in the provider.

# CLI Auth
provider "stackit" {
  default_region = "eu01"
  cli_auth       = true
}

Our Terraform Provider will have the same behavior as the Go SDK, because it is
build on top of the Go SDK. So when a service account key or token is defined at
the same time, they will be tried first and the cli_auth will be the last
option. It will read the access-token and refresh-token from the CLI like the Go
SDK.

Summary

With the proposed architecture, we ensure that the users have explicit opt-in
for this feature and avoid unexpected behaviors.

Our preferred decision for the interface is to use a combination of Option 1
and 2. If the system has a keychain, we will use it to store there the
credentials. And as fallback we would create a file on the system, to store the
credentials on the disk. With this implementation, the dependency between the
CLI and the SDK is as weak as possible, because it only relies on the keychain
entry or the file and their content.

In the next weeks we will start with implementation in the CLI, where the
credentials for the SDK will be created. After this, we will add the new
authentication method in the Go SDK and integrate it afterwards in the Terraform
Provider. To ensure everything works as expected, we will start with this
feature in beta. After the beta phase, we will integrate this feature in the
Python SDK as well.

Feedback and Discussion

Feel free to give us some feedback to our proposed architecture for the CLI
Authentication.