conjur-api 4.14.0 → 4.15.0

data/lib/conjur/api/roles.rb

@@ -23,18 +23,20 @@ require 'conjur/graph'
 
 module Conjur
   class API
-    ##
-    # Fetch a digraph (or a forest of digraphs) representing of
-    #   role memberships related transitively to any of a list of roles.
-    #
-    # @param [Array<Conjur::Role, String>] roles the  digraph (or forest thereof) of
-    #   the ancestors and descendants of these roles or role ids will be returned
-    # @param [Hash] options options determining the graph returned
-    # @option opts [Boolean] :ancestors Whether to return ancestors of the given roles (true by default)
-    # @option opts [Boolean] :descendants Whether to return descendants of the given roles (true by default)
-    # @option opts [Conjur::Role, String] :as_role Only roles visible to this role will be included in the graph
+    #@!group Authorization: Roles
+
+    # Fetch a {Conjur::Graph} representing the relationships of a given role or roles.  Such graphs are transitive,
+    # and follow the normal permissions for role visibility.
+    #
+    # @param [Array<Conjur::Role, String>, String, Conjur::Role] roles role or or array of roles
+    #   roles whose relationships we're interested in
+    # @param [Hash] options options for the request
+    # @option options [Boolean] :ancestors Whether to return ancestors of the given roles (true by default)
+    # @option options [Boolean] :descendants Whether to return descendants of the given roles (true by default)
+    # @option options [Conjur::Role, String] :as_role Only roles visible to this role will be included in the graph
     # @return [Conjur::Graph] An object representing the role memberships digraph
     def role_graph roles, options = {}
+      roles = [roles] unless roles.kind_of? Array
       roles.map!{|r| normalize_roleid(r) }
       options[:as_role] = normalize_roleid(options[:as_role]) if options.include?(:as_role)
       options.reverse_merge! as_role: normalize_roleid(current_role), descendants: true, ancestors: true
@@ -45,24 +47,108 @@ module Conjur
       Conjur::Graph.new RestClient::Resource.new(Conjur::Authz::API.host, credentials)["#{Conjur.account}/roles?#{query}"].get
     end
 
+    # Create a {Conjur::Role} with the given id.
+    #
+    # ### Permissions
+    # * All Conjur roles can create new roles.
+    # * The creator role (either the current role or the role given by the `:acting_as` option)
+    #   is made a member of the new role.  The new role is also made a member of itself.
+    # * If you give an `:acting_as` option, you must be a (transitive) member of the `:acting_as`
+    #   role.
+    # * The new role is granted to the creator role with *admin option*: that is, the creator role
+    #   is able to grant the created role to other roles.
+    #
+    # @example Basic role creation
+    #   # Current role is 'user:jon', assume the organizational account is 'conjur'
+    #    api.current_role # => 'conjur:user:jon'
+    #
+    #   # Create a Conjur actor to control the permissions of a chron job (rebuild_indices)
+    #   role = api.create_role 'robot:rebuild_indices'
+    #   role.role_id # => "conjur:robot:rebuild_indices"
+    #   role.members.map{ |grant| grant.member.role_id } # => ['conjur:user:jon', 'conjur:robot:rebuild_indices']
+    #   api.role('user:jon').admin_of?(role) # => true
+    #
+    #
+    # @param [String] role a qualified role identifier for the new role
+    # @param [Hash] options options for the action
+    # @option options [String] :acting_as the resource will effectively be created by this role
+    # @return [Conjur::Role] the created role
+    # @raise [RestClient::MethodNotAllowed] if the role already exists.  Note that this differs from
+    #   the `RestClient::Conflict` exception raised when trying to create existing high level (user, group, etc.)
+    #   Conjur assets.
     def create_role(role, options = {})
       role(role).tap do |r|
         r.create(options)
       end
     end
 
+    # Return a {Conjur::Role} representing a role with the given id.  Note that the {Conjur::Role} may or
+    # may not exist (see {Conjur::Exists#exists?}).
+    #
+    # ### Permissions
+    # Because this method returns roles that may or may not exist, it doesn't require any permissions to call it:
+    # in fact, it does not perform an HTTP request (except for authentication if necessary).
+    #
+    # @example Create and show a role
+    #   api.create_role 'cat:iggy'
+    #   iggy = api.role 'cat:iggy'
+    #   iggy.exists? # true
+    #   iggy.members.map(&:member).map(&:roleid) # => ['conjur:user:admin']
+    #   api.current_role.roleid # => 'conjur:user:admin' # creator role is a member of created role.
+    #
+    # @example No permissions are required to call this method
+    #   api.current_role # => "user:no-access"
+    #
+    #   # current role is only a member of itself, so it can't see other roles.
+    #   api.current_role.memberships.count # => 1
+    #   admin = api.role 'user:admin' # OK
+    #   admin.exists? # => true
+    #   admin.members # => RestClient::Forbidden: 403 Forbidden
+    #
+    # @param [String] role the id of the role, which must contain at least kind and id tokens (account is optional).
+    # @return [Conjur::Role] an object representing the role
     def role role
       Role.new(Conjur::Authz::API.host, credentials)[self.class.parse_role_id(role).join('/')]
     end
 
+    # Return a {Conjur::Role} object representing the role (typically a user or host) that this api is authenticated
+    # as.  This is derived either from the `login` argument to {Conjur::API.new_from_key} or from the contents of the
+    # `token` given to {Conjur::API.new_from_token}.
+    #
+    # @example Current role for a user
+    #   api = Conjur::API.new_from_key 'jon', 'somepassword'
+    #   api.current_role.roleid # => 'conjur:user:jon'
+    #
+    # @example Current role for a host
+    #   host = api.create_host id: 'exapmle-host'
+    #
+    #   # Host and User have an `api` method that returns an api with their credentials.  Note
+    #   # that this only works with a newly created host or user, which has an `api_key` attribute.
+    #   host.api.current_role.roleid # => 'conjur:host:example-host'
+    #
+    # @return [Conjur::Role] the authenticated role for this API instance
     def current_role
       role_from_username username
     end
 
+
+    #@!endgroup
+
+    # @api private
+    #
+    # Get a Role instance from a username or host id
+    # @param [String] username the username or host id
+    # @return [Conjur::Role]
     def role_from_username username
       role(role_name_from_username username)
     end
 
+    # @api private
+    #
+    # Convert a username or host id to a role identifier.
+    # This handles conversion of logins like 'host/foo' to 'host:foo'
+    # @param [String] username the user name or host id
+    # @return [String] A full role id for the user or host
     def role_name_from_username username = self.username
       tokens = username.split('/')
       if tokens.size == 1
@@ -71,8 +157,14 @@ module Conjur
         [ tokens[0], tokens[1..-1].join('/') ].join(':')
       end
     end
-    
+
     private
+
+    # @api  private
+    # Use of this method is deprecated in favor of Conjur::Cast#cast
+    # @deprecated
+    # @param [String, Conjur::Role] role object to extract a role id from
+    # @return [String] the role id
     def normalize_roleid role
       case role
         when String then role

data/lib/conjur/api/secrets.rb

@@ -22,10 +22,25 @@ require 'conjur/secret'
 
 module Conjur
   class API
+
+    # @api private
+    #
+    # Create a Conjur secret.  Secrets are a low-level construcct upon which variables
+    # are built,
+    #
+    # @param [String] value the secret data
+    # @return [Conjur::Secret] the new secret
     def create_secret(value, options = {})
       standard_create Conjur::Core::API.host, :secret, nil, options.merge(value: value)
     end
-    
+
+    # @api private
+    #
+    # Fetch a Conjur secret by id.  Secrets are a low-level construct upon which variables
+    # are built, and should not generally be used directly.
+    #
+    # @param [String] id the *unqualified* identifier for the secret
+    # @return [Conjur::Secret] an object representing the secret
     def secret id
       standard_show Conjur::Core::API.host, :secret, id
     end

data/lib/conjur/api/users.rb

@@ -7,7 +7,7 @@
 # use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 # the Software, and to permit persons to whom the Software is furnished to do so,
 # subject to the following conditions:
-#
+##
 # The above copyright notice and this permission notice shall be included in all
 # copies or substantial portions of the Software.
 #
@@ -22,16 +22,80 @@ require 'conjur/user'
 
 module Conjur
   class API
+    #@!group Directory: Users
+
+    # Create a {http://developer.conjur.net/reference/services/directory/user Conjur User}.  Conjur users
+    # are identities for humans.
+    #
+    # When you create a user for the first time, the returned object will have an `api_key` field.  You can then
+    # use this to set a password for the user if you want to.  Note that when the user is fetched later with the {#user}
+    # method, it **will not have an api_key**.  Use it or lose it.
+    #
+    # ### Permissions
+    # Any authenticated role may call this method.
+    #
+    # @example Create a user 'alice' and set her password to 'frogger'
+    #   alice = api.create_user 'alice', password: 'frogger'
+    #
+    #   # Now we can login as 'alice'.
+    #   alice_api = Conjur::API.new_from_key 'alice', 'frogger'
+    #   alice_api.current_role # => 'conjur:user:alice'
+    #
+    # @example Create a user and save her `api_key` for later use
+    #    alice = api.create_user 'alice' # note that we're not giving a password
+    #    save_api_key 'alice', alice.api_key
+    #
+    # @param [String] login the login for the new user
+    # @param [Hash] options options for user creation
+    # @option options [String] :acting_as Qualified id of a role to perform the action as
+    # @option options [String, Integer] :uidnumber UID number to assign to the new user.  If not given, one will be generated.
+    # @option options [String] :password when present, the user will be given a password in addition to a randomly
+    #   generated api key.
+    # @return [Conjur::User] an object representing the new user
+    # @raise [RestClient::Conflict] If the user already exists, or a user with the given uidnumber exists.
     def create_user(login, options = {})
       standard_create Conjur::Core::API.host, :user, nil, options.merge(login: login)
     end
 
+    # Return an object representing a user with the given login. The {Conjur::User} object returned
+    # may or may not exist.  You can check whether it exists with the {Conjur::Exists#exists?} method.
+    #
+    # The returned {Conjur::User} will *not* have an api_key.
+    #
+    # ### Permissions
+    # Any authenticated role may call this method.
+    #
+    # @param [String] login the user's login
+    # @return [Conjur::User] an object representing the user
     def user login
       standard_show Conjur::Core::API.host, :user, login
     end
 
+    # @api private
+    #
+    # @note In the future, further options for search may be added, but presently this only supports uid search.
+    #
+    # Find users by uidnumber.
+    #
+    #
+    # When a user is created it is assigned a uid number.  When the uid number is not specified when creating the user,
+    # a sequential uid number will be generated, starting at 1000.  uidnumbers are used when synchronizing with LDAP directories
+    # and to assign a UNIX user id number when using {http://developer.conjur.net/tutorials/ssh/conjur-ssh.html Conjur SSH login}.
+    #
+    # ### Note
+    # Although users are uniquely identified by their uidnumber, the result of this method is an array of user ids for compatibility
+    # reasons.
+    #
+    # ### Permissions
+    # Only roles of which you are a member will be returned
+    #
+    # @param [Hash] options query to send
+    # @option options [String, Integer] :uidnumber (required) the uidnumber to search for
+    # @return [Array<String>] a one element array containing the users login.
     def find_users options
       JSON.parse( RestClient::Resource.new(Conjur::Core::API.host, credentials)["users/search?#{options.to_query}"].get )
     end
+
+    #@!endgroup
   end
 end

data/lib/conjur/api/variables.rb

@@ -22,14 +22,77 @@ require 'conjur/variable'
 
 module Conjur
   class API
+    #@!group Directory: Variables
+
+    # Create a {http://developer.conjur.net/reference/services/directory/variable Conjur Variable}.
+    # See {Conjur::Variable} for operations on Conjur variables.
+    #
+    # ### Permissions
+    # Any authenticated role may call this method
+    #
+    # @example Create a variable to store a database connection string
+    #   db_uri = "mysql://username:password@mysql.somehost.com/mydb"
+    #   var = api.create_variable 'text/plain', 'mysql-connection-string', id: 'production/mysql/uri'
+    #   var.add_value db_uri
+    #
+    #   # Alternatively, we could have done this:
+    #   var = api.create_variable 'text/plain', 'mysql-connection-string',
+    #         id: 'production/mysql/uri',
+    #         value: db_uri
+    #
+    # @example Create a variable with a unique random id
+    #   var = api.create_variable 'text/plain', 'secret'
+    #   var.id # => 'kngeqg'
+    #
+    # @param [String] mime_type MIME type for the variable value, used to set the `"Content-Type"`header
+    #   when serving the variable's value.  Must be non-empty.
+    # @param [String] kind user defined `kind` for the variable.  This is useful as a simple way to document
+    #   the variable's purpose.  Must be non-empty
+    # @param [Hash] options options for the new variable
+    # @option options [String] :id specify an id for the new variable. Must be non-empty.
+    # @option options [String] :value specify an initial value for the variable
+    # @return [Conjur::Variable] an object representing the new variable
+    # @raise [RestClient::Conflict] if you give an `:id` option and the variable already exists
+    # @raise [RestClient::UnprocessableEntity] if `mime_type`, `kind`, or `options[:id]` is the empty string.
     def create_variable(mime_type, kind, options = {})
       standard_create Conjur::Core::API.host, :variable, nil, options.merge(mime_type: mime_type, kind: kind)
     end
-    
+
+    # Retrieve an object representing a {http://developer.conjur.net/reference/services/directory/variable Conjur Variable}.
+    # The {Conjur::Variable} returned may or may not exist, and
+    # your permissions on the corresponding resource determine the operations you can perform on it.
+    #
+    # ### Permissions
+    # Any authenticated role can call this method.
+    #
+    # @param [String] id the unqualified id of the variable
+    # @return [Conjur::Variable] and object representing the variable.
     def variable id
       standard_show Conjur::Core::API.host, :variable, id
     end
 
+    # Fetch the values of a list of variables.  This operation is more efficient than fetching the
+    # values one by one.
+    #
+    # This method will fail unless:
+    #   * All of the variables exist
+    #   * You have permission to `'execute'` all of the variables
+    #
+    # @example Fetch multiple variable values
+    #   values = variable_values ['postgres_uri', 'aws_secret_access_key', 'aws_access_key_id']
+    #   values # =>
+    #   {
+    #      "postgres_uri" => "postgres://..."
+    #      "aws_secret_access_key" => "..."
+    #      "aws_access_key_id" => "..."
+    #   }
+    #
+    # This method is used to implement the {http://developer.conjur.net/reference/tools/utilities/conjurenv `conjur env`}
+    # commands.  You may consider using that instead to run your program in an environment with the necessary secrets.
+    #
+    # @param [Array<String>] varlist list of variable ids to fetch
+    # @return [Hash] a hash mapping variable ids to variable values
+    # @raise [RestClient::Forbidden, RestClient::ResourceNotFound] if any of the variables don't exist or aren't accessible.
     def variable_values(varlist)
       raise ArgumentError, "Variables list must be an array" unless varlist.kind_of? Array 
       raise ArgumentError, "Variables list is empty" if varlist.empty?
@@ -42,5 +105,6 @@ module Conjur
       end
     end
 
+    #@!endgroup
   end
 end

data/lib/conjur/audit-api.rb

@@ -23,6 +23,9 @@ module Conjur
   module Audit
     class API < Conjur::API
       class << self
+        # The URL for the audit service
+        #
+        # @return [String] the audit service url.
         def host
           Conjur.configuration.audit_url
         end

data/lib/conjur/authn-api.rb

@@ -22,6 +22,10 @@ module Conjur
   module Authn
     class API < Conjur::API
       class << self
+
+        # The URL for the audit service
+        #
+        # @return [String] the audit service url.
         def host
           Conjur.configuration.authn_url
         end

data/lib/conjur/authz-api.rb

@@ -22,6 +22,10 @@ module Conjur
   module Authz
     class API < Conjur::API
       class << self
+
+        # The URL for the audit service
+        #
+        # @return [String] the audit service url.
         def host
           Conjur.configuration.authz_url
         end

data/lib/conjur/base.rb

@@ -35,31 +35,7 @@ require 'conjur/cast'
 module Conjur
   # NOTE: You have to put all 'class level' api docs here, because YARD is stoopid :-(
 
-  # This class provides access to Conjur services
-  # **TODO MOAR**
-  #
-  # # Conjur Services
-  #
-  # ### Public Keys Service
-  # The {http://developer.conjur.net/reference/services/pubkeys Conjur Public Keys} service provides a
-  # simple database of public keys with access controlled by Conjur.  Reading a user's public keys requires
-  # no authentication at all -- the user's public keys are public information, after all.
-  #
-  # Adding or deleting a public key may only be done if you have permission to update the *public keys
-  # resource*, which is created when the appliance is launched, and has a resource id
-  # `'<organizational account>:service:pubkeys-1.0/public-keys'`.  The appliance also comes with a Group named
-  # `'pubkeys-1.0/key-managers'` that has this permission.  Rather than granting each user permission to
-  # modify the public keys database, you should consider adding users to this group.
-  #
-  # A very common use case is {http://developer.conjur.net/tutorials/ssh public key management for SSH}
-  #
-  #
-  # ### Audit Service
-  #
-  # The {http://developer.conjur.net/reference/services/audit Conjur Audit Service} allows you to
-  # fetch audit records.
-  #
-  # Generally you will need to have *at least one* privilege on the subject of an event in order to see it.
+  # This class provides access to the Conjur services.
   class API
     include Escape
     include LogSource
@@ -184,19 +160,37 @@ module Conjur
 
       raise "Expecting ( username and api_key ) or token" unless ( username && api_key ) || token
     end
-    
+
+    #@!attribute [r] api_key
+    # The api key used to create this instance.  This is only present when you created the api with {Conjur::API.new_from_key}.#
+    #
+    # @return [String] the api key, or nil if this instance was created from a token.
     attr_reader :api_key
 
+    # The name of the user as which this api instance is authenticated.  This is available whether the api
+    # instance was created from credentials or an authentication token.
     #
+    # @return [String] the login of the current user.
     def username
       @username || @token['data']
     end
 
-
+    # @api private
+    # used to delegate to host providing subclasses.
+    # @return [String] the host
     def host
       self.class.host
     end
 
+    # The token used to authenticate requests made with the api.  The token will be fetched
+    # if it hasn't already, or if it has expired.  Accordingly, this method may raise a RestClient::Unauthorized
+    # exception if the credentials are invalid.
+    #
+    # @note calling this method on an {Conjur::API} instance created with {Conjur::API.new_from_token} will have
+    # undefined behavior if the token is expired.
+    #
+    # @return [Hash] the authentication token as a Hash
+    # @raise [RestClient::Unauthorized] if the username and api key are invalid.
     def token
       @token = nil unless token_valid?
 
@@ -206,15 +200,22 @@ module Conjur
 
       return @token
     end
-    
-    # Authenticate the username and api_key to obtain a request token.
-    # Tokens are cached by username for a short period of time.
+
+    # Credentials that can be merged with options to be passed to `RestClient::Resource` HTTP request methods.
+    # These include a username and an Authorization header containing the authentication token.
+    #
+    # @return [Hash] the options.
+    # @raise [RestClient::Unauthorized] if fetching the token fails.
+    # @see {#token}
     def credentials
       { headers: { authorization: "Token token=\"#{Base64.strict_encode64 token.to_json}\"" }, username: username }
     end
 
     private
 
+    # Check to see if @token is defined, and whether it's expired
+    #
+    # @return [Boolean] whether or not the token is valid.
     def token_valid?
       return false unless @token