Skip to content

Commit

Permalink
fix(token-url): Updates documentation with changes to flags and attri…
Browse files Browse the repository at this point in the history 
…butes
  • Loading branch information
@rvelaVenafi
rvelaVenafi committed Apr 9, 2024
1 parent 875eb24 commit 5fad1ad
Show file tree
Hide file tree
Showing 3 changed files with 25 additions and 20 deletions.
6 changes: 3 additions & 3 deletions README-CLI-CLOUD.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ VCert supports supplying flag values using environment variables:
| Attribute | Flag | Environment Variable |
|--------------------------------|--------------------|----------------------|
| API key | `-k` or `--apiKey` | `VCERT_APIKEY` |
| JWT from Identity Provider | `--idp-jwt` | `VCERT_IDP_JWT` |
| JWT from Identity Provider | `--external-jwt` | `VCERT_EXTERNAL_JWT` |
| Venafi Control Plane token | `-t` or `--token` | `VCERT_TOKEN` |
| Venafi Control Plane token URL | `--token-url` | `VCERT_TOKEN_URL` |
| Venafi Control Plane URL | `-u` or `--url` | `VCERT_URL` |
Expand Down Expand Up @@ -372,15 +372,15 @@ Options:

### Obtaining an access token from service account
```
vcert getcred -p vcp --token-url https://api.venafi.cloud/v1/oauth2/v2.0/xxx-XXxX/token --idp-jwt "file:jwt.txt"
vcert getcred -p vcp --token-url https://api.venafi.cloud/v1/oauth2/v2.0/aaa-bbb-ccc/token --external-jwt "file:jwt.txt"
```
Options:

| Flag | Description |
|----------------------|-----------------------------------------------------------------------------------------------------------------------|
| `-p` or `--platform` | Use to specify Venafi Control Plane as the platform of choice to connect. Accepted value is `vcp`, no case-sensitive. |
| `--token-url` | The URL used to obtain the access token, provided by Venafi Control Plane's service account page |
| `--idp-jwt` | The JWT of the Identity Provider associated to the service account that is going to grant the access token |
| `--external-jwt` | The JWT of the Identity Provider associated to the service account that is going to grant the access token |

### Generating a new key pair and CSR
```
Expand Down
37 changes: 21 additions & 16 deletions README-PLAYBOOK.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -119,22 +119,27 @@ The top-level structure of the file is described as follows:

### Credentials

| Field | Type | TLSPDC | TLSPC | FIREFLY | Description |
|--------------|--------|----------------|----------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| accessToken | string | *Optional* | *Optional* | n/a | Used when [Connection.platform](#connection) is `tlspdc` for authenticating to the REST API.<br/>If omitted, invalid, or expired, vcert will attempt to use the [Credential.p12Task](#credentials) or [Credential.refreshToken](#credentials) to get a valid accessToken.<br/>Upon successful refresh, this value will be overwritten with the new valid accessToken. |
| apiKey | string | n/a | ***Required*** | n/a | Used when [Connection.platform](#connection) is `tlspc` for authenticating to the REST API. |
| audience | string | n/a | n/a | *Optional* | Used when [Connection.platform](#connection) is `firefly` to map the audience for the authorization token request from the OAuth2 Provider. Not all OAuth2 providers require this value. |
| clientId | string | *Optional* | n/a | *Optional* | Used when [Connection.platform](#connection) is `tlspc` to map to the API integration to be used. If omitted, uses `vcert-sdk` as default.<br/><br/>Used when [Connection.platform](#connection) is `firefly` along with `clientSecret` to follow a `credentials authorization flow`. |
| clientSecret | string | n/a | n/a | *Optional* | Used when [Connection.platform](#connection) is `firefly` along with `clientId` to follow a `credentials authorization flow` to get an authorization token from the OAuth2 Provider. |
| externalJWT | string | n/a | *Optional* | n/a | Used when [Connection.platform](#connection) is `tlspc` along with `tenantId` to request a new authorization token from a service account. |
| p12Task | string | *Optional* | n/a | n/a | Used when [Connection.platform](#connection) is `tlspdc` to reference a configured [CertificateTasks.name](#certificatetask) to be used for certificate authentication.<br/>Will be used to get a new accessToken when `accessToken` is missing, invalid, or expired.<br/>Referenced `certificateTask` must have an installation of type `pkcs12`. |
| password | string | n/a | n/a | *Optional* | Used when [Connection.platform](#connection) is `firefly` along with `user` to follow a `password authorization flow` to request a new authorization token from the OAuth2 Provider. |
| refreshToken | string | *Optional* | n/a | n/a | Used when [Connection.platform](#connection) is `tlspdc` to refresh the `accessToken` if it is missing, invalid, or expired.<br/>If omitted, the `accessToken` will not be refreshed when it expires.<br/>When a refresh token is used, a new accessToken *and* refreshToken are issued and the previous refreshToken is then invalid (one-time use only).<br/>vCert will attempt to update the refreshToken and accessToken fields upon refresh. |
| scope | string | *Optional* | n/a | *Optional* | Used when [Connection.platform](#connection) is `tlspdc` to determine the scope of the token when refreshing the access token, or when getting a new grant using a `pkcs12` certificate. Defaults to `certificate:manage` if omitted.<br/><br/>Used when [Connection.platform](#connection) is `firefly` to determine the scope of the token to be requested to the OAuth2 provider. Some providers may have default scopes while others dont. |
| tenantId | string | n/a | *Optional* | n/a | Used when [Connection.platform](#connection) is `tlspc` along with `externalJWT` to request a new authorization token from a service account. |
| tokenURL | string | ***Required*** | n/a | n/a | Used when [Connection.platform](#connection) is `firefly` to request a new authorization token to the OAuth2 Provider. |
| user | string | n/a | n/a | *Optional* | Used when [Connection.platform](#connection) is `firefly` along with `password` to follow a `password` authorization flow to request a new authorization token from the OAuth2 Provider. |

| Field | Type | TLSPDC | TLSPC | FIREFLY | Description |
|--------------|----------------------------------------------|------------|------------|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| accessToken | string | *Optional* | *Optional* | n/a | Used when [Connection.platform](#connection) is `tlspdc` for authenticating to the REST API.<br/>If omitted, invalid, or expired, vcert will attempt to use the [Credential.p12Task](#credentials) or [Credential.refreshToken](#credentials) to get a valid accessToken.<br/>Upon successful refresh, this value will be overwritten with the new valid accessToken. |
| apiKey | string | n/a | *Optional* | n/a | Used when [Connection.platform](#connection) is `tlspc` for authenticating to the REST API. |
| clientId | string | *Optional* | n/a | *Optional* | Used when [Connection.platform](#connection) is `tlspc` to map to the API integration to be used. If omitted, uses `vcert-sdk` as default.<br/><br/>Used when [Connection.platform](#connection) is `firefly` along with `clientSecret` to follow a `credentials authorization flow`. |
| clientSecret | string | n/a | n/a | *Optional* | Used when [Connection.platform](#connection) is `firefly` along with `clientId` to follow a `credentials authorization flow` to get an authorization token from the OAuth2 Provider. |
| externalJWT | string | n/a | *Optional* | n/a | Used when [Connection.platform](#connection) is `tlspc` along with `tokenURL` to request a new authorization token from a service account. |
| idP | [IdentityProvider](#identityprovider) object | n/a | n/a | ***Required*** | Used when [Connection.platform](#connection) is `firefly` to request a new authorization token to the OAuth2 Provider. |
| p12Task | string | *Optional* | n/a | n/a | Used when [Connection.platform](#connection) is `tlspdc` to reference a configured [CertificateTasks.name](#certificatetask) to be used for certificate authentication.<br/>Will be used to get a new accessToken when `accessToken` is missing, invalid, or expired.<br/>Referenced `certificateTask` must have an installation of type `pkcs12`. |
| password | string | n/a | n/a | *Optional* | Used when [Connection.platform](#connection) is `firefly` along with `user` to follow a `password authorization flow` to request a new authorization token from the OAuth2 Provider. |
| refreshToken | string | *Optional* | n/a | n/a | Used when [Connection.platform](#connection) is `tlspdc` to refresh the `accessToken` if it is missing, invalid, or expired.<br/>If omitted, the `accessToken` will not be refreshed when it expires.<br/>When a refresh token is used, a new accessToken *and* refreshToken are issued and the previous refreshToken is then invalid (one-time use only).<br/>vCert will attempt to update the refreshToken and accessToken fields upon refresh. |
| scope | string | *Optional* | n/a | *Optional* | Used when [Connection.platform](#connection) is `tlspdc` to determine the scope of the token when refreshing the access token, or when getting a new grant using a `pkcs12` certificate. Defaults to `certificate:manage` if omitted.<br/><br/>Used when [Connection.platform](#connection) is `firefly` to determine the scope of the token to be requested to the OAuth2 provider. Some providers may have default scopes while others dont. |
| tokenURL | string | n/a | *Optional* | n/a | Used when [Connection.platform](#connection) is `tlspc` along with `externalJWT` to request a new authorization token from a service account. |
| user | string | n/a | n/a | *Optional* | Used when [Connection.platform](#connection) is `firefly` along with `password` to follow a `password authorization flow` to request a new authorization token from the OAuth2 Provider. |

### IdentityProvider

| Field | Type | TLSPDC | TLSPC | FIREFLY | Description |
|----------|--------|--------|-------|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| audience | string | n/a | n/a | *Optional* | Used when [Connection.platform](#connection) is `firefly` to map the audience for the authorization token request from the OAuth2 Provider. Not all OAuth2 providers require this value. |
| tokenURL | string | | n/a | ***Required*** | Used when [Connection.platform](#connection) is `firefly` to request a new authorization token to the OAuth2 Provider. |

### CertificateTask

Expand Down
2 changes: 1 addition & 1 deletion pkg/endpoint/authentication.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ type Authentication struct {
TokenURL string `yaml:"tokenURL,omitempty"`
ExternalJWT string `yaml:"externalJWT,omitempty"`

// IDP Auth method
// OIDC Auth methods
ClientId string `yaml:"clientId,omitempty"`
ClientSecret string `yaml:"clientSecret,omitempty"`
Scope string `yaml:"scope,omitempty"`
Expand Down

0 comments on commit 5fad1ad

Please sign in to comment.