Merge pull request #155 from jfrog/add-support-for-expiring-token-and…

…-access-token-config

Add support for expiring token and access token config

CHANGELOG.md

@@ -1,3 +1,20 @@
+## 1.3.0 (Feburary 27, 2023)
+
+IMPROVEMENTS:
+
+* Add support for username specific user token configuration path: `config/user_token/<username>`
+* Add ability to override `access_token` in `config/user_token/<username>` path.
+* Add `refresh_token` field to allow manual refreshing of access token.
+* When access token expires, plugin now attempts to get a new access token using the refresh token
+* Update README with more details documentation for all paths
+
+BUG FIXES:
+
+* Fix `refreshable` and `include_reference_token` parameters not working for user token. Issue: [#154](https://github.com/jfrog/artifactory-secrets-plugin/issues/154)
+* Fix `default_ttl`, `max_ttl`, etc. logic and applies to token expiration (when applicable).
+
+PR: [155](https://github.com/jfrog/vault-plugin-secrets-artifactory/pull/155)
+
 ## 1.2.0 (January 10, 2023)
 
 IMPROVEMENTS:

Makefile

@@ -53,12 +53,12 @@ upgrade: build register
 	vault plugin reload -plugin=$(PLUGIN_NAME)
 
 test:
-	go test -v ./...
+	go test -v -count=1 ./...
 
 acceptance:
 	export VAULT_ACC=true && \
 	export JFROG_ACCESS_TOKEN=$(JFROG_ACCESS_TOKEN) && \
-		go test -run TestAcceptance -cover -coverprofile=coverage.txt -v -p 1 -timeout 5m ./...
+		go test -run TestAcceptance -cover -coverprofile=coverage.txt -v -p 1 -count=1 -timeout 5m ./...
 
 alltests:
 	export VAULT_ACC=true && \

README.md

@@ -272,7 +272,7 @@ Create a role (scope for artifactory >= 7.21.1)
 ```sh
 vault write artifactory/roles/jenkins \
     scope="applied-permissions/groups:automation " \
-    default_ttl=1h max_ttl=3h
+    default_ttl=3600 max_ttl=10800
 ```
 
 Also supports `grant_type=[Optional, default: "client_credentials"]`, and `audience=[Optional, default: *@*]` see [JFrog documentation][artifactory-create-token].
@@ -338,7 +338,7 @@ path "artifactory/user_token/{{identity.entity.aliases.azure-ad-oidc.metadata.up
 }
 ```
 
-Default values for the token's `access_token`, `description`, `ttl`, `max_ttl`, `audience`, `refreshable`, `include_reference_token`, and `use_expiring_tokens` may be configured at the `/artifactory/config/user_token` path.
+Default values for the token's `access_token`, `description`, `ttl`, `max_ttl`, `audience`, `refreshable`, `include_reference_token`, and `use_expiring_tokens` may be configured at the `/artifactory/config/user_token` or `/artifactory/config/user_token/<user-name>` path.
 
 `access_token` field allows the use of user's identity token in place of the admin access token from the `/artifactory/config/admin` path, enabling creating access token scoped to that user only.
 
@@ -347,7 +347,10 @@ TTL rules follow Vault's [general cases](https://developer.hashicorp.com/vault/d
 Example Token Configuration:
 
 ```console
-vault write artifactory/config/user_token default_description="Generated by Vault" max_ttl=604800 default_ttl=86400
+vault write artifactory/config/user_token \
+  default_description="Generated by Vault" \
+  max_ttl=604800 \
+  default_ttl=86400
 ```
 
 ```console
@@ -382,6 +385,190 @@ token_id           3c6b2e63-87dc-4d26-9698-ffdfb282a6ee
 username           admin
 ```
 
+## References
+
+### Admin Config
+
+| Command | Path |
+| ------- | ---- |
+| write   | artifactory/config/admin |
+| read    | artifactory/config/admin |
+| delete  | artifactory/config/admin |
+
+Configure the parameters used to connect to the Artifactory server integrated with this backend.
+
+The two main parameters are `url` which is the absolute URL to the Artifactory server. Note that `/artifactory/api`
+is prepended by the individual calls, so do not include it in the URL here.
+
+The second is `access_token` which must be an access token enough permissions to generate the other access tokens you'll
+be using. This value is stored seal wrapped when available. Once set, the access token cannot be retrieved, but the backend
+will send a sha256 hash of the token so you can compare it to your notes. If the token is a JWT Access Token, it will return
+additional information such as `jfrog_token_id`, `username` and `scope`.
+
+An optional `username_template` parameter will override the built-in default username_template for dynamically generating
+usernames if a static one is not provided.
+
+An optional `bypass_artifactory_tls_verification` parameter will enable bypassing the TLS connection verification with Artifactory.
+
+No renewals or new tokens will be issued if the backend configuration (config/admin) is deleted.
+
+#### Parameters
+
+* `url` (string) - Address of the Artifactory instance, e.g. https://my.jfrog.io
+* `access_token` (stirng) - Administrator token to access Artifactory
+* `username_template` (string) - Optional. Vault Username Template for dynamically generating usernames.
+* `use_expiring_tokens` (boolean) - Optional. If Artifactory version >= 7.50.3, set `expires_in` to `max_ttl` (admin token) or `ttl` (user token) and `force_revocable = true`. Default to `false`.
+* `bypass_artifactory_tls_verification` (boolean) - Optional. Bypass certification verification for TLS connection with Artifactory. Default to `false`.
+
+#### Example
+
+```console
+vault write artifactory/config/admin url=$JFROG_URL \
+  access_token=$JFROG_ACCESS_TOKEN \
+  username_template="v_{{.DisplayName}}_{{.RoleName}}_{{random 10}}_{{unix_time}}" \
+  use_expiring_tokens=true \
+  bypass_artifactory_tls_verification=true
+```
+
+### User Token Config
+
+| Command | Path |
+| ------- | ---- |
+| write   | artifactory/user_config |
+| read    | artifactory/user_config |
+| write   | artifactory/user_config/:username |
+| read    | artifactory/user_config/:username |
+
+Configures default values for the `user_token/:user-name` path. The optional `username` field allows the configuration to be set for specific username.
+
+#### Parameters
+
+* `access_token` (stirng) - Optional. User identity token to access Artifactory. If `username` is not set then this token will be used for *all* users.
+* `refresh_token` (string) - Optional. Refresh token for the user access token. If `username` is not set then this token will be used for *all* users.
+* `audience` (string) - Optional. See the JFrog Platform REST documentation on [Create Token](https://jfrog.com/help/r/jfrog-rest-apis/create-token) for a full and up to date description. Service ID must begin with valid JFrog service type. Options: jfrt, jfxr, jfpip, jfds, jfmc, jfac, jfevt, jfmd, jfcon, or *. For instructions to retrieve the Artifactory Service ID see this [documentation](https://jfrog.com/help/r/jfrog-rest-apis/get-service-id)
+* `refreshable` (boolean) - Optional. A refreshable access token gets replaced by a new access token, which is not what a consumer of tokens from this backend would be expecting; instead they'd likely just request a new token periodically. Set this to `true` only if your usage requires this. See the JFrog Platform documentation on [Generating Refreshable Tokens](https://jfrog.com/help/r/jfrog-platform-administration-documentation/generating-refreshable-tokens) for a full and up to date description. Defaults to `false`. 
+* `include_reference_token` (boolean) - Optional. Generate a Reference Token (alias to Access Token) in addition to the full token (available from Artifactory 7.38.10). A reference token is a shorter, 64-character string, which can be used as a bearer token, a password, or with the `X-JFrog-Art-Api`header. Note: Using the reference token might have performance implications over a full length token. Defaults to `false`. 
+* `use_expiring_tokens` (boolean) - Optional. If Artifactory version >= 7.50.3, set `expires_in` to `ttl` and `force_revocable = true`. Defaults to `false`. 
+* `default_ttl` (int64) - Optional. Default TTL for issued user access tokens. If unset, uses the backend's `default_ttl`. Cannot exceed `max_ttl`. 
+* `default_description` (string) - Optional. Default token description to set in Artifactory for issued user access tokens.
+
+#### Examples
+
+```console
+# Set user token configuration for ALL users
+vault write artifactory/config/user_token \
+  access_token="eyJ2Z...3sT9r6nA" \
+  refresh_token="4ab...471" \
+  default_ttl=60s
+
+vault read artifactory/config/user_token
+
+# Set user token configuration for 'myuser' user
+vault write artifactory/config/user_token/myuser \
+  access_token="eyJ2Z...3sT9r6nA" \
+  refresh_token="4ab...471" \
+  audience="jfrt@* jfxr@*"
+
+vault read artifactory/config/user_token/myuser
+
+vault delete artifactory/config/user_token/myuser
+```
+
+### Role
+
+| Command | Path |
+| ------- | ---- |
+| write   | artifactory/role/:rolename |
+| patch   | artifactory/role/:rolename |
+| read    | artifactory/role/:rolename |
+| delete  | artifactory/role/:rolename |
+
+#### Parameters
+
+* `grant_type` (stirng) - Optional. Defaults to `client_credentials` when creating the access token. You likely don't need to change this.
+* `username` (string) - Optional. Defaults to using the username_template. The static username for which the access token is created. If the user does not exist, Artifactory will create a transient user. Note that non-administrative access tokens can only create tokens for themselves.
+* `scope` (string) - Space-delimited list. See the JFrog Artifactory REST documentation on ["Create Token"](https://jfrog.com/help/r/jfrog-rest-apis/create-token) for a full and up to date description.
+* `refreshable` (boolean) - Optional. A refreshable access token gets replaced by a new access token, which is not what a consumer of tokens from this backend would be expecting; instead they'd likely just request a new token periodically. Set this to `true` only if your usage requires this. See the JFrog Platform documentation on [Generating Refreshable Tokens](https://jfrog.com/help/r/jfrog-platform-administration-documentation/generating-refreshable-tokens) for a full and up to date description. Defaults to `false`.
+* `audience` (string) - Optional. See the JFrog Platform REST documentation on [Create Token](https://jfrog.com/help/r/jfrog-rest-apis/create-token) for a full and up to date description. Service ID must begin with valid JFrog service type. Options: jfrt, jfxr, jfpip, jfds, jfmc, jfac, jfevt, jfmd, jfcon, or *. For instructions to retrieve the Artifactory Service ID see this [documentation](https://jfrog.com/help/r/jfrog-rest-apis/get-service-id)
+* `include_reference_token` (boolean) - Optional. Generate a Reference Token (alias to Access Token) in addition to the full token (available from Artifactory 7.38.10). A reference token is a shorter, 64-character string, which can be used as a bearer token, a password, or with the `X-JFrog-Art-Api`header. Note: Using the reference token might have performance implications over a full length token. Defaults to `false`.
+* `default_ttl` (int64) - Default TTL for issued user access tokens. If unset, uses the backend's `default_ttl`. Cannot exceed `max_ttl`.
+* `max_ttl` (int64) - Maximum TTL that an access token can be renewed for. If unset, uses the backend's `max_ttl`. Cannot exceed backend's `max_ttl`. 
+
+#### Examples
+
+```console
+vault write artifactory/roles/test \
+  scope="applied-permissions/groups:readers applied-permissions/groups:ci" \
+  max_ttl=3h \
+  default_ttl=2h
+
+vault read artifactory/roles/test
+
+vault delete artifactory/roles/test
+```
+
+### Admin Token
+
+| Command | Path |
+| ------- | ---- |
+| read   | artifactory/token/:rolename |
+
+Create an Artifactory access token using paramters from the specified role.
+
+#### Parameters
+
+* `ttl` (int64) - Optional. Override the default TTL when issuing this access token. Cannot exceed smallest (system, backend, role, this request) maximum TTL.
+* `max_ttl` (int64) - Optional. Override the maximum TTL for this access token. Cannot exceed smallest (system, backend) maximum TTL.
+
+#### Examples
+
+```console
+vault read artifactory/token/test \
+  ttl=30m \
+  max_ttl=1h
+```
+
+### Rotate Admin Token
+
+| Command | Path |
+| ------- | ---- |
+| write   | artifactory/config/rotate |
+
+This will rotate the `access_token` used to access artifactory from this plugin. A new access token is created first then revokes the old access token.
+
+#### Examples
+
+```console
+vault write artifactory/config/rotate
+```
+
+### User Token
+
+| Command | Path |
+| ------- | ---- |
+| read    | artifactory/user_token/:username |
+
+Provides optional parameters to override default values for the user_token/:username path
+
+#### Parameters
+
+* `description` (string) - Optional. Override the token description to set in Artifactory for issued user access tokens.
+* `refreshable` (boolean) - Optional. Override the `refreshable` for this access token. Defaults to `false`.
+* `include_reference_token` (boolean) - Optional. Override the `include_reference_token` for this access token. Defaults to `false`.
+* `use_expiring_tokens` (boolean) - Optional. Override the `use_expiring_tokens` for this access token. If Artifactory version >= 7.50.3, set `expires_in` to `ttl` and `force_revocable = true`. Defaults to `false`. 
+* `ttl` (int64) - Optional. Override the default TTL when issuing this access token. Cannot exceed smallest (system, backend, role, this request) maximum TTL.
+* `max_ttl` (int64) - Optional. Override the maximum TTL for this access token. Cannot exceed smallest (system, backend) maximum TTL.
+
+#### Examples
+
+```console
+vault read artifactory/user_token/test_user \
+  description="Refreshable token for Test user"
+  refreshable=true \
+  include_reference_token=true \
+  use_expiring_tokens=true
+```
+
 ## Development
 
 ### Local Development Prerequisites