key_vault accessor function

NAMESPACE

@@ -1,6 +1,7 @@
 # Generated by roxygen2: do not edit by hand
 
 S3method(print,vault_access_policy)
+export(AzureKeyVault)
 export(az_key_vault)
 export(cert_expiry_actions)
 export(cert_issuer_properties)

R/az_vault.R

@@ -163,7 +163,7 @@ public=list(
                           password=self$token$client$client_secret, ...)
     {
         url <- self$properties$vaultUri
-        key_vault$new(url=url, tenant=tenant, app=app, password=password, ...)
+        key_vault(url=url, tenant=tenant, app=app, password=password, ...)
     }
 ))
 

R/certificates.R

@@ -65,7 +65,7 @@
 #' @examples
 #' \dontrun{
 #'
-#' vault <- key_vault$new("mykeyvault")
+#' vault <- key_vault("mykeyvault")
 #'
 #' vault$certificates$create("mynewcert", "CN=mydomain.com")
 #' vault$certificates$list()

R/keys.R

@@ -43,7 +43,7 @@
 #' @examples
 #' \dontrun{
 #'
-#' vault <- key_vault$new("mykeyvault")
+#' vault <- key_vault("mykeyvault")
 #'
 #' vault$keys$create("mynewkey")
 #' vault$keys$create("myRSAkey", key_properties(type="RSA", rsa_key_size=4096))

R/secrets.R

@@ -38,7 +38,7 @@
 #' @examples
 #' \dontrun{
 #'
-#' vault <- key_vault$new("mykeyvault")
+#' vault <- key_vault("mykeyvault")
 #'
 #' vault$secrets$create("mysecret", "secret string")
 #'

R/storage_accounts.R

@@ -43,7 +43,7 @@
 #' @examples
 #' \dontrun{
 #'
-#' vault <- key_vault$new("mykeyvault")
+#' vault <- key_vault("mykeyvault")
 #'
 #' # get the storage account details
 #' library(AzureStor)

R/stored_acct.R

@@ -59,7 +59,7 @@
 #' @examples
 #' \dontrun{
 #'
-#' vault <- key_vault$new("mykeyvault")
+#' vault <- key_vault("mykeyvault")
 #'
 #' # get the storage account details
 #' library(AzureStor)

R/stored_cert.R

@@ -67,7 +67,7 @@
 #' @examples
 #' \dontrun{
 #'
-#' vault <- key_vault$new("mykeyvault")
+#' vault <- key_vault("mykeyvault")
 #'
 #' cert <- vault$certificates$create("mynewcert")
 #' cert$cer

R/stored_key.R

@@ -62,7 +62,7 @@
 #' @examples
 #' \dontrun{
 #'
-#' vault <- key_vault$new("mykeyvault")
+#' vault <- key_vault("mykeyvault")
 #'
 #' vault$keys$create("mynewkey")
 #' # new version of an existing key

R/stored_secret.R

@@ -43,7 +43,7 @@
 #' @examples
 #' \dontrun{
 #'
-#' vault <- key_vault$new("mykeyvault")
+#' vault <- key_vault("mykeyvault")
 #'
 #' vault$secrets$create("mynewsecret", "secret text")
 #' # new version of an existing secret

R/vault_endpoint.R

@@ -1,6 +1,6 @@
 #' Azure Key Vault endpoint class
 #'
-#' Class representing the client endpoint for a key vault, exposing methods for working with it.
+#' Class representing the client endpoint for a key vault, exposing methods for working with it. Use the `[key_vault]` function to instantiate new objects of this class.
 #'
 #' @docType class
 #' @section Fields:
@@ -9,22 +9,8 @@
 #' - `certificates`: A sub-object for working with certificates stored in the vault. See [certificates].
 #' - `storage`: A sub-object for working with storage accounts managed by the vault. See [storage].
 #'
-#' @section Methods:
-#' This class provides one method, for initialization:
-#' ```
-#' new(url, tenant = "common", app = .az_cli_app_id, ...,
-#'     domain = "vault.azure.net", token = NULL)
-#' ```
-#' The arguments are as follows:
-#' - `url`: The location of the vault. This can be a full URL, or the vault name alone; in the latter case, the `domain` argument is appended to obtain the URL.
-#' - `tenant, app, ...`: Authentication arguments that will be passed to [AzureAuth::get_azure_token]. The default is to authenticate interactively.
-#' - `domain`: The domain of the vault; for the public Azure cloud, this is `vault.azure.net`. Also the resource for OAuth authentication.
-#' - `token`: An OAuth token obtained via [AzureAuth::get_azure_token]. If provided, this overrides the other authentication arguments.
-#'
-#' To work with objects stored in the key vault, use the methods provided by one of the sub-objects listed in 'Fields'.
-#'
 #' @seealso
-#' [az_key_vault], [keys], [secrets], [certificates], [storage]
+#' [key_vault], [keys], [secrets], [certificates], [storage]
 #'
 #' [Azure Key Vault documentation](https://docs.microsoft.com/en-us/azure/key-vault/),
 #' [Azure Key Vault API reference](https://docs.microsoft.com/en-us/rest/api/keyvault)
@@ -32,20 +18,20 @@
 #' @examples
 #' \dontrun{
 #'
-#' key_vault$new("mykeyvault")
-#' key_vault$new("https://mykeyvault.vault.azure.net")
+#' key_vault("mykeyvault")
+#' key_vault("https://mykeyvault.vault.azure.net")
 #'
 #' # authenticating as a service principal
-#' key_vault$new("mykeyvault", tenant="myaadtenant", app="app_id", password="password")
+#' key_vault("mykeyvault", tenant="myaadtenant", app="app_id", password="password")
 #'
 #' # authenticating with an existing token
 #' token <- AzureAuth::get_azure_token("https://vault.azure.net", "myaadtenant",
 #'                                     app="app_id", password="password")
-#' key_vault$new("mykeyvault", token=token)
+#' key_vault("mykeyvault", token=token)
 #'
 #' }
 #' @export
-key_vault <- R6::R6Class("key_vault", public=list(
+AzureKeyVault <- R6::R6Class("AzureKeyVault", public=list(
     
     token=NULL,
     url=NULL,
@@ -55,17 +41,10 @@ key_vault <- R6::R6Class("key_vault", public=list(
     certificates=NULL,
     storage=NULL,
 
-    initialize=function(url, tenant="common", app=.az_cli_app_id, ..., domain="vault.azure.net", token=NULL)
+    initialize=function(token, url)
     {
-        if(!is_url(url))
-            url <- sprintf("https://%s.%s", url, domain)
-
-        # "https://vault.azure.net/" (with trailing slash) will fail
-        if(is.null(token))
-            token <- get_azure_token(sprintf("https://%s", domain), tenant=tenant, app=app, ...)
-
-        self$url <- httr::parse_url(url)
         self$token <- token
+        self$url <- url
 
         self$keys <- vault_keys$new(self$token, self$url)
         self$secrets <- vault_secrets$new(self$token, self$url)
@@ -87,3 +66,54 @@ key_vault <- R6::R6Class("key_vault", public=list(
         invisible(self)
     }
 ))
+
+
+#' Azure Key Vault client
+#'
+#' @param url The location of the vault. This can be a full URL, or the vault name alone; in the latter case, the `domain` argument is appended to obtain the URL.
+#' @param tenant,app,... Authentication arguments that will be passed to [AzureAuth::get_azure_token]. The default is to authenticate interactively.
+#' @param domain The domain of the vault; for the public Azure cloud, this is `vault.azure.net`. Also the resource for OAuth authentication.
+#' @param token An OAuth token obtained via [AzureAuth::get_azure_token]. If provided, this overrides the other authentication arguments.
+#'
+#' @details
+#' This function creates a new Key Vault client object. It includes the following component objects for working with data in the vault:
+#'
+#' - `keys`: A sub-object for working with encryption keys stored in the vault. See [keys].
+#' - `secrets`: A sub-object for working with secrets stored in the vault. See [secrets].
+#' - `certificates`: A sub-object for working with certificates stored in the vault. See [certificates].
+#' - `storage`: A sub-object for working with storage accounts managed by the vault. See [storage].
+#'
+#' @seealso
+#' [keys], [secrets], [certificates], [storage]
+#'
+#' [Azure Key Vault documentation](https://docs.microsoft.com/en-us/azure/key-vault/),
+#' [Azure Key Vault API reference](https://docs.microsoft.com/en-us/rest/api/keyvault)
+#'
+#' @examples
+#' \dontrun{
+#'
+#' key_vault("mykeyvault")
+#' key_vault("https://mykeyvault.vault.azure.net")
+#'
+#' # authenticating as a service principal
+#' key_vault("mykeyvault", tenant="myaadtenant", app="app_id", password="password")
+#'
+#' # authenticating with an existing token
+#' token <- AzureAuth::get_azure_token("https://vault.azure.net", "myaadtenant",
+#'                                     app="app_id", password="password")
+#' key_vault("mykeyvault", token=token)
+#'
+#' }
+#' @export
+key_vault <- function(url, tenant="common", app=.az_cli_app_id, ..., domain="vault.azure.net", token=NULL)
+{
+    if(!is_url(url))
+        url <- sprintf("https://%s.%s", url, domain)
+
+    # "https://vault.azure.net/" (with trailing slash) will fail
+    if(is.null(token))
+        token <- get_azure_token(sprintf("https://%s", domain), tenant=tenant, app=app, ...)
+
+    AzureKeyVault$new(token, httr::parse_url(url))
+}
+

README.md

@@ -43,10 +43,10 @@ kv$add_principal(svc,
 
 ## Client interface
 
-The client interface is R6-based. To access the vault, instantiate a new object of class `key_vault`. This object includes sub-objects for interacting with keys, secrets, certificates and managed storage accounts.
+The client interface is R6-based. To instantiate a new client object, call the `key_vault` function. This object includes sub-objects for interacting with keys, secrets, certificates and managed storage accounts.
 
 ```r
-vault <- key_vault$new("https://mykeyvault.vault.azure.net")
+vault <- key_vault("https://mykeyvault.vault.azure.net")
 
 # can also be done from the ARM resource object
 vault <- kv$get_endpoint()

man/AzureKeyVault.Rd

@@ -0,0 +1,46 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/vault_endpoint.R
+\docType{class}
+\name{AzureKeyVault}
+\alias{AzureKeyVault}
+\title{Azure Key Vault endpoint class}
+\format{An object of class \code{R6ClassGenerator} of length 24.}
+\usage{
+AzureKeyVault
+}
+\description{
+Class representing the client endpoint for a key vault, exposing methods for working with it. Use the \code{[key_vault]} function to instantiate new objects of this class.
+}
+\section{Fields}{
+
+\itemize{
+\item \code{keys}: A sub-object for working with encryption keys stored in the vault. See \link{keys}.
+\item \code{secrets}: A sub-object for working with secrets stored in the vault. See \link{secrets}.
+\item \code{certificates}: A sub-object for working with certificates stored in the vault. See \link{certificates}.
+\item \code{storage}: A sub-object for working with storage accounts managed by the vault. See \link{storage}.
+}
+}
+
+\examples{
+\dontrun{
+
+key_vault("mykeyvault")
+key_vault("https://mykeyvault.vault.azure.net")
+
+# authenticating as a service principal
+key_vault("mykeyvault", tenant="myaadtenant", app="app_id", password="password")
+
+# authenticating with an existing token
+token <- AzureAuth::get_azure_token("https://vault.azure.net", "myaadtenant",
+                                    app="app_id", password="password")
+key_vault("mykeyvault", token=token)
+
+}
+}
+\seealso{
+\link{key_vault}, \link{keys}, \link{secrets}, \link{certificates}, \link{storage}
+
+\href{https://docs.microsoft.com/en-us/azure/key-vault/}{Azure Key Vault documentation},
+\href{https://docs.microsoft.com/en-us/rest/api/keyvault}{Azure Key Vault API reference}
+}
+\keyword{datasets}

man/certificate.Rd

@@ -78,7 +78,7 @@ For \code{set_version}, the key object with the updated version.
 \examples{
 \dontrun{
 
-vault <- key_vault$new("mykeyvault")
+vault <- key_vault("mykeyvault")
 
 cert <- vault$certificates$create("mynewcert")
 cert$cer

man/certificates.Rd

@@ -70,7 +70,7 @@ For \code{backup}, a string representing the backup blob for a certificate. If t
 \examples{
 \dontrun{
 
-vault <- key_vault$new("mykeyvault")
+vault <- key_vault("mykeyvault")
 
 vault$certificates$create("mynewcert", "CN=mydomain.com")
 vault$certificates$list()

man/key.Rd

@@ -72,7 +72,7 @@ For \code{set_version}, the key object with the updated version.
 \examples{
 \dontrun{
 
-vault <- key_vault$new("mykeyvault")
+vault <- key_vault("mykeyvault")
 
 vault$keys$create("mynewkey")
 # new version of an existing key

man/key_vault.Rd

@@ -1,18 +1,26 @@
 % Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/vault_endpoint.R
-\docType{class}
 \name{key_vault}
 \alias{key_vault}
-\title{Azure Key Vault endpoint class}
-\format{An object of class \code{R6ClassGenerator} of length 24.}
+\title{Azure Key Vault client}
 \usage{
-key_vault
+key_vault(url, tenant = "common", app = .az_cli_app_id, ...,
+  domain = "vault.azure.net", token = NULL)
+}
+\arguments{
+\item{url}{The location of the vault. This can be a full URL, or the vault name alone; in the latter case, the \code{domain} argument is appended to obtain the URL.}
+
+\item{tenant, app, ...}{Authentication arguments that will be passed to \link[AzureAuth:get_azure_token]{AzureAuth::get_azure_token}. The default is to authenticate interactively.}
+
+\item{domain}{The domain of the vault; for the public Azure cloud, this is \code{vault.azure.net}. Also the resource for OAuth authentication.}
+
+\item{token}{An OAuth token obtained via \link[AzureAuth:get_azure_token]{AzureAuth::get_azure_token}. If provided, this overrides the other authentication arguments.}
 }
 \description{
-Class representing the client endpoint for a key vault, exposing methods for working with it.
+Azure Key Vault client
 }
-\section{Fields}{
-
+\details{
+This function creates a new Key Vault client object. It includes the following component objects for working with data in the vault:
 \itemize{
 \item \code{keys}: A sub-object for working with encryption keys stored in the vault. See \link{keys}.
 \item \code{secrets}: A sub-object for working with secrets stored in the vault. See \link{secrets}.
@@ -20,44 +28,25 @@ Class representing the client endpoint for a key vault, exposing methods for wor
 \item \code{storage}: A sub-object for working with storage accounts managed by the vault. See \link{storage}.
 }
 }
-
-\section{Methods}{
-
-This class provides one method, for initialization:\preformatted{new(url, tenant = "common", app = .az_cli_app_id, ...,
-    domain = "vault.azure.net", token = NULL)
-}
-
-The arguments are as follows:
-\itemize{
-\item \code{url}: The location of the vault. This can be a full URL, or the vault name alone; in the latter case, the \code{domain} argument is appended to obtain the URL.
-\item \code{tenant, app, ...}: Authentication arguments that will be passed to \link[AzureAuth:get_azure_token]{AzureAuth::get_azure_token}. The default is to authenticate interactively.
-\item \code{domain}: The domain of the vault; for the public Azure cloud, this is \code{vault.azure.net}. Also the resource for OAuth authentication.
-\item \code{token}: An OAuth token obtained via \link[AzureAuth:get_azure_token]{AzureAuth::get_azure_token}. If provided, this overrides the other authentication arguments.
-}
-
-To work with objects stored in the key vault, use the methods provided by one of the sub-objects listed in 'Fields'.
-}
-
 \examples{
 \dontrun{
 
-key_vault$new("mykeyvault")
-key_vault$new("https://mykeyvault.vault.azure.net")
+key_vault("mykeyvault")
+key_vault("https://mykeyvault.vault.azure.net")
 
 # authenticating as a service principal
-key_vault$new("mykeyvault", tenant="myaadtenant", app="app_id", password="password")
+key_vault("mykeyvault", tenant="myaadtenant", app="app_id", password="password")
 
 # authenticating with an existing token
 token <- AzureAuth::get_azure_token("https://vault.azure.net", "myaadtenant",
                                     app="app_id", password="password")
-key_vault$new("mykeyvault", token=token)
+key_vault("mykeyvault", token=token)
 
 }
 }
 \seealso{
-\link{az_key_vault}, \link{keys}, \link{secrets}, \link{certificates}, \link{storage}
+\link{keys}, \link{secrets}, \link{certificates}, \link{storage}
 
 \href{https://docs.microsoft.com/en-us/azure/key-vault/}{Azure Key Vault documentation},
 \href{https://docs.microsoft.com/en-us/rest/api/keyvault}{Azure Key Vault API reference}
 }
-\keyword{datasets}

man/keys.Rd

@@ -47,7 +47,7 @@ For \code{backup}, a string representing the backup blob for a key. If the key h
 \examples{
 \dontrun{
 
-vault <- key_vault$new("mykeyvault")
+vault <- key_vault("mykeyvault")
 
 vault$keys$create("mynewkey")
 vault$keys$create("myRSAkey", key_properties(type="RSA", rsa_key_size=4096))

man/secrets.Rd

@@ -42,7 +42,7 @@ For \code{backup}, a string representing the backup blob for a secret. If the se
 \examples{
 \dontrun{
 
-vault <- key_vault$new("mykeyvault")
+vault <- key_vault("mykeyvault")
 
 vault$secrets$create("mysecret", "secret string")
 

man/storage_account.Rd

@@ -104,7 +104,7 @@ For \code{set_version}, the secret object with the updated version.
 \examples{
 \dontrun{
 
-vault <- key_vault$new("mykeyvault")
+vault <- key_vault("mykeyvault")
 
 # get the storage account details
 library(AzureStor)
@@ -125,7 +125,7 @@ stor$show_sas("newsas")
 }
 \dontrun{
 
-vault <- key_vault$new("mykeyvault")
+vault <- key_vault("mykeyvault")
 
 vault$secrets$create("mynewsecret", "secret text")
 # new version of an existing secret

man/storage_accounts.Rd

@@ -48,7 +48,7 @@ For \code{backup}, a string representing the backup blob for a storage account.
 \examples{
 \dontrun{
 
-vault <- key_vault$new("mykeyvault")
+vault <- key_vault("mykeyvault")
 
 # get the storage account details
 library(AzureStor)

tests/testthat/test02_keys.R

@@ -8,7 +8,7 @@ vaultname <- Sys.getenv("AZ_TEST_KEYVAULT")
 if(tenant == "" || app == "" || password == "" || vaultname == "")
     skip("Key tests skipped: vault credentials not set")
 
-vault <- key_vault$new(vaultname, tenant=tenant, app=app, password=password)
+vault <- key_vault(vaultname, tenant=tenant, app=app, password=password)
 
 try({
     vault$keys$delete("rsakey", confirm=FALSE)

tests/testthat/test03_secrets.R

@@ -8,7 +8,7 @@ vaultname <- Sys.getenv("AZ_TEST_KEYVAULT")
 if(tenant == "" || app == "" || password == "" || vaultname == "")
     skip("Secret tests skipped: vault credentials not set")
 
-vault <- key_vault$new(vaultname, tenant=tenant, app=app, password=password)
+vault <- key_vault(vaultname, tenant=tenant, app=app, password=password)
 
 try({
     vault$secrets$delete("secret1", confirm=FALSE)

tests/testthat/test04_certs.R

@@ -8,7 +8,7 @@ vaultname <- Sys.getenv("AZ_TEST_KEYVAULT")
 if(tenant == "" || app == "" || password == "" || vaultname == "")
     skip("Certificate tests skipped: vault credentials not set")
 
-vault <- key_vault$new(vaultname, tenant=tenant, app=app, password=password)
+vault <- key_vault(vaultname, tenant=tenant, app=app, password=password)
 
 try({
     vault$certificates$delete("rsacert", confirm=FALSE)

tests/testthat/test05_storage.R

@@ -13,8 +13,8 @@ if(tenant == "" || app == "" || password == "" || vaultname == "" ||
     skip("Storage account tests skipped: vault credentials not set")
 
 # currently storage acct management requires a user principal, not svc principal
-#vault <- key_vault$new(vaultname, tenant=tenant, app=app, password=password)
-vault <- key_vault$new(vaultname)
+#vault <- key_vault(vaultname, tenant=tenant, app=app, password=password)
+vault <- key_vault(vaultname)
 
 try({
     vault$storage$remove("stor1", confirm=FALSE)

vignettes/intro.Rmd

@@ -45,10 +45,10 @@ kv$add_principal(svc,
 
 ## Client interface
 
-The client interface is R6-based. To access the vault, instantiate a new object of class `key_vault`. This object includes component objects for interacting with keys, secrets, certificates and managed storage accounts.
+The client interface is R6-based. To instantiate a new client object, call the `key_vault` function. This object includes sub-objects for interacting with keys, secrets, certificates and managed storage accounts.
 
 ```r
-vault <- key_vault$new("https://mykeyvault.vault.azure.net")
+vault <- key_vault("https://mykeyvault.vault.azure.net")
 
 # can also be done from the ARM resource object
 vault <- kv$get_endpoint()