Add Optional Expiry to Auth Tokens

[juliannatetreault]

Description

Allow an optional expired_at to be set on authentication API tokens via the provider.

Testing plan

• Ensure that organization and team API tokens that omit the optional expired_at field still work as expected.
• Ensure that an expired_at can be set on organization and team API tokens and that once set, the expiration date displays in the UI (/app/org-name/authentication-tokens) with the expiration date that was provided.
• Ensure that an invalid expired_at cannot be set on organization and team API tokens and that if attempted to be set, an error is returned.

External links

• Related go-tfe PR
• API documentation

Output from acceptance tests

resource_tfe_organization_token_test.go results:

=== RUN   TestAccTFEOrganizationToken_basic
--- PASS: TestAccTFEOrganizationToken_basic (8.99s)
PASS

Process finished with the exit code 0
...
=== RUN   TestAccTFEOrganizationToken_existsWithoutExpiry
--- PASS: TestAccTFEOrganizationToken_existsWithoutExpiry (18.02s)
PASS

Process finished with the exit code 0
...

=== RUN   TestAccTFEOrganizationToken_existsWithExpiry
--- PASS: TestAccTFEOrganizationToken_existsWithExpiry (9.48s)
PASS

Process finished with the exit code 0

resource_tfe_team_token_test.go results:

=== RUN   TestAccTFETeamToken_basic
--- PASS: TestAccTFETeamToken_basic (10.22s)
PASS

Process finished with the exit code 0
...
=== RUN   TestAccTFETeamToken_existsWithoutExpiry
--- PASS: TestAccTFETeamToken_existsWithoutExpiry (10.95s)
PASS

Process finished with the exit code 0
...
=== RUN   TestAccTFETeamToken_existsWithExpiry
--- PASS: TestAccTFETeamToken_existsWithExpiry (10.51s)
PASS

Process finished with the exit code 0

[JarrettSpiker]

If you would like the make the compile errors go away, and allow tests to run or allow other developers to clone + build and test this, you can run + commit

go get github.com/hashicorp/go-tfe@10f40dcbde314dbc81c1c4e35a0aa89823ca0ff0

This will tell go to use your draft version of go-tfe from that commit.

It will need to be updated to an actual released go-tfe version before this can be merged....but it will need to be updated regardless when the actual version of go-tfe is released, so 🤷 no extra work needed by pointing to an unreleased version of go-tfe in the mean time

[JarrettSpiker]

One easy fix in the docs, and a few suggestions on cleaning up the code a bit.

If the requested tests are a bigger lift than I am thinking, let me know!

[JarrettSpiker]

looking good to me, just one more small error in the docs

[JarrettSpiker]

This LGTM!

[brandonc]

I wonder if we should suggest such a dramatically long expiration period in the docs (I think it's 28 years) ... and more generally I wonder if there is more guidance we can give for generating this format in particular.. Example: You can generate this string using the date tool in unix systems.. unfortunately this tool has different flags in linux and darwin and other systems:

darwin:
date -Iseconds -v"+90d"

linux:
date -Iseconds -d"+90 days"

Or you can use a terraform function that doesn't make it easy to work with long durations:

$ terraform console
> timeadd(timestamp(), "2160h")
"2023-08-28T23:04:47Z"

To open up a slightly broader discussion... I don't believe that this format is perfectly suitable for this use case because it must be static to be useful and doesn't lend itself to human readability. What I mean by static is that it would not make sense to invoke a terraform function like timestamp() to define this value because it would force a re-create on the resource every time it was evaluated. Nor is there an easy set of terraform functions to format a more human readable date... We expect users to statically define an expiration date in iso8601 format, which is hard to read and hard to write. So what if we chose a more human readable format that was also easy to produce? Like RFC 5322 (email format)

$ date -v"+90d" -R
Mon, 28 Aug 2023 17:10:48 -0600

This can be reliably parsed with go, looks nice in config, and we could even document the terraform format string for the expected format (it's EEE, DD MMM YYYY hh:mm:ss ZZZZ)

$ terraform console
> formatdate("EEE, DD MMM YYYY hh:mm:ss ZZZZ", timeadd(timestamp(), "2160h"))

Tell me what you think.
/cc @JarrettSpiker

[JarrettSpiker]

@brandonc: @juliannatetreault and I discussed this, and definitely agree that we can improve the documentation with some more realistic examples, and provide the user with some commands they can use to generate an appropriate timestamp.

To open up a slightly broader discussion... I don't believe that this format is perfectly suitable for this use case because it must be static to be useful and doesn't lend itself to human readability.

I don't know that I totally agree here though. Maybe it is personal preference but I don't find 2023-08-28T23:04:47Z harder to read than Mon, 28 Aug 2023 17:10:48 -0600... in both the date is apparent, and I am going to need to plug the time into some sort of time zone conversion tool if it is relevant.

And I think I would actually prefer to write the 2023-08-28T23:04:47Z format, since I find it intuitively less ambiguous (e.g. no needing to guess what the correct format for the month name is).

I would be open to changing the format if there are strong feelings about it. The current format being alright could be just personal preference though...and with all things being equal I lean towards using the format that the API will be using.

On a related note, just googling around I found the time provider...do you think that that would be something worth recommending as a way to generate this timestamp? Something like:

resource "time_static" "example" {}

resource "tfe_organization_token" "token" {
    organization = data.tfe_organization.org.name
    expired_at = timeadd(time_static.example.rfc3339, "2160h")
}

[brandonc]

@JarrettSpiker @juliannatetreault I am super into recommending the time provider in the documentation! I wouldn't mind keeping iso8601 if it makes the examples this simple! Plus, it has the added benefit of being the same standard format that timestamp(), etc. uses.

resource "time_rotating" "example" {
  rotation_days = 90
}

resource "tfe_organization_token" "token" {
    organization = data.tfe_organization.org.name
    expired_at = time_rotating.example.id
}

[brandonc]

👇

[brandonc]

I made a mistake!

[brandonc]

Very close 🎉

[brandonc]

WTG