conjur-api 4.31.0 → 5.0.0.rc1

data/lib/conjur/api/authn.rb

@@ -1,5 +1,5 @@
 #
-# Copyright (C) 2013 Conjur Inc
+# Copyright 2013-2017 Conjur Inc
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy of
 # this software and associated documentation files (the "Software"), to deal in
@@ -23,18 +23,16 @@ require 'conjur/user'
 module Conjur
   class API
     class << self
-      #@!group Authentication Methods
+      #@!group Authentication
 
-      # The Conjur {http://developer.conjur.net/reference/services/authentication/login.html login}
-      #   operation exchanges a username and a password for an api key.  The api key
+      # Exchanges a username and a password for an api key.  The api key
       #   is preferable for storage and use in code, as it can be rotated and has far greater entropy than
       #   a user memorizable password.
       #
-      #  * Note that this method works only for {http://developer.conjur.net/reference/services/directory/user Users}. While
-      #   {http://developer.conjur.net/reference/services/directory/hosts Hosts} possess Conjur identities, they do not
-      #   have passwords.
-      #  * If you pass an api key to this method instead of a password, it will simply return the API key.
-      #  * This method uses Basic Auth to send the credentials.
+      #  * Note that this method works only for {Conjur::User}s. While
+      #   {Conjur::Host}s are roles, they do not have passwords.
+      #  * If you pass an api key to this method instead of a password, it will verify and return the API key.
+      #  * This method uses HTTP Basic Authentication to send the credentials.
       #
       # @example
       #   bob_api_key = Conjur::API.login('bob', 'bob_password')
@@ -43,104 +41,71 @@ module Conjur
       # @param [String] username The `username` or `login` for the
       #   {http://developer.conjur.net/reference/services/directory/user Conjur User}.
       # @param [String] password The `password` or `api key` to authenticate with.
+      # @param [String] account The organization account.
       # @return [String] the API key.
-      # @raise [RestClient::Exception] when the request fails or the identity provided is invalid.
-      def login username, password
+      def login username, password, account: Conjur.configuration.account
         if Conjur.log
-          Conjur.log << "Logging in #{username} via Basic authentication\n"
+          Conjur.log << "Logging in #{username} to account #{account} via Basic authentication\n"
         end
-        RestClient::Resource.new(Conjur::Authn::API.host, user: username, password: password)['users/login'].get
+        RestClient::Resource.new(Conjur.configuration.authn_url, user: username, password: password)[fully_escape account]['login'].get
       end
 
-      # TODO I have NO idea how to document login_cas!
-
-      # This method logs in via CAS.  It is similar to the {.login} method, the only difference being that
-      # you need a `cas_api_url`, provided by the administrator of your `CAS` service.
-      #
-      # @see .login
-      # @param [String] username the Conjur username
-      # @param [String] password the Conjur password
-      # @param [String] cas_api_url the url of the CAS service
-      # @return [String] a `CAS` ticket
-      def login_cas username, password, cas_api_url
-        if Conjur.log
-          Conjur.log << "Logging in #{username} via CAS authentication\n"
-        end
-        require 'cas_rest_client'
-        client = CasRestClient.new(:username => username, :password => password, :uri => [ cas_api_url, 'v1', 'tickets' ].join('/'), :use_cookies => false)
-        client.get("#{Conjur::Authn::API.host}/users/login").body
-      end
-
-      # The Conjur {http://developer.conjur.net/reference/services/authentication/authenticate.html authenticate} operation
-      #    exchanges Conjur credentials for a token.  The token can then be used to authenticate further API calls.
-      #
-      # You will generally not need to use this method, as the API manages tokens automatically for you.
+      # Exchanges Conjur the API key (refresh token) for an access token.  The access token can 
+      # then be used to authenticate further API calls.
       #
       # @param [String] username The username or host id for which we want a token
-      # @param [String] password The password or api key
+      # @param [String] api_key The api key
+      # @param [String] account The organization account.
       # @return [String] A JSON formatted authentication token.
-      def authenticate username, password
+      def authenticate username, api_key, account: Conjur.configuration.account
+        account ||= Conjur.configuration.account
         if Conjur.log
-          Conjur.log << "Authenticating #{username}\n"
+          Conjur.log << "Authenticating #{username} to account #{account}\n"
         end
-        JSON::parse(RestClient::Resource.new(Conjur::Authn::API.host)["users/#{fully_escape username}/authenticate"].post password, content_type: 'text/plain')
+        JSON::parse(RestClient::Resource.new(Conjur.configuration.authn_url)[fully_escape account][fully_escape username]['authenticate'].post api_key, content_type: 'text/plain')
       end
 
-
       # Change a user's password.  To do this, you must have the user's current password.  This does not change or rotate
-      #   api keys.  However, you *can*  use the user's api key as the *current* password, if the user was not created
+      #   api keys. However, you *can* use the user's api key as the *current* password, if the user was not created
       #   with a password.
       #
-      # @param [String] username the name of the user whose password we want to change
-      # @param [String] password the user's *current* password *or* api key
+      # @param [String] username the name of the user whose password we want to change.
+      # @param [String] password the user's *current* password *or* api key.
       # @param [String] new_password the new password for the user.
+      # @param [String] account The organization account.
       # @return [void]
-      def update_password username, password, new_password
+      def update_password username, password, new_password, account: Conjur.configuration.account
         if Conjur.log
-          Conjur.log << "Updating password for #{username}\n"
+          Conjur.log << "Updating password for #{username} in account #{account}\n"
         end
-        RestClient::Resource.new(Conjur::Authn::API.host, user: username, password: password)['users/password'].put new_password
+        RestClient::Resource.new(Conjur.configuration.authn_url, user: username, password: password)[fully_escape account]['password'].put new_password
       end
 
       #@!endgroup
 
       #@!group Password and API key management
 
-      # Rotate the currently authenticated user's API key by generating and returning a new one.
-      # The old API key is no longer valid after calling this method.  You must have the user's current
-      # API key or password to perform this operation.  This method *does not* affect the user's password.
-      #
-      # @note If the user does not have a password, the returned API key will be the **only** way to authenticate as
-      #   the user.  Therefore, you'd best save it.
-      #
-      # @note This feature requires version 4.6 of the Conjur appliance.
+      # Rotate the currently authenticated user or host API key by generating and returning a new one.
+      # The old API key is no longer valid after calling this method.  You must have the current
+      # API key or password to perform this operation.  This method *does not* affect a user's password.
       #
-      # @param [String] username the name of the user whose password we want to change
-      # @param [String] password the user's current password *or* api key
-      # @return [String] the new API key for the user
-      def rotate_api_key username, password
+      # @param [String] username the name of the user or host whose API key we want to change
+      # @param [String] password the user's current api key
+      # @param [String] account The organization account.
+      # @return [String] the new API key
+      def rotate_api_key username, password, account: Conjur.configuration.account
         if Conjur.log
-          Conjur.log << "Rotating API key for self (#{username})\n"
+          Conjur.log << "Rotating API key for self (#{username} in account #{account})\n"
         end
 
         RestClient::Resource.new(
-              Conjur::Authn::API.host,
+              Conjur.configuration.authn_url,
               user: username,
               password: password
-        )['users/api_key'].put('').body
+        )[fully_escape account]['api_key'].put('').body
       end
 
       #@!endgroup
     end
-
-    # @api private
-    # This is used internally to create a user that we can log in as without creating
-    # an actual user in the directory, as with #create_user.
-    def create_authn_user login, options = {}
-      log do |logger|
-        logger << "Creating authn user #{login}"
-      end
-      JSON.parse RestClient::Resource.new(Conjur::Authn::API.host, credentials)['users'].post(options.merge(login: login))
-    end
   end
 end

data/lib/conjur/api/host_factories.rb

@@ -1,5 +1,5 @@
 #
-# Copyright (C) 2014 Conjur Inc
+# Copyright 2013-2017 Conjur Inc
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy of
 # this software and associated documentation files (the "Software"), to deal in
@@ -22,72 +22,52 @@ require 'conjur/host_factory'
 
 module Conjur
   class API
+    #@!group Host Factory
+
     class << self
-      # Creates a host and returns the response Hash.
+      # Use a host factory token to create a new host. Unlike most other methods, this
+      # method does not require a Conjur access token. The host factory token is the
+      # authentication and authorization to create the host.
+      #
+      # The token must be valid. The host id can be a new host, or an existing host. 
+      # If the host already exists, the server verifies that its layer memberships
+      # match the host factory exactly. Then, its API key is rotated and returned with
+      # the response.
+      # 
+      # @param [String] token the host factory token.
+      # @param [String] id the id of a new or existing host.
+      # @param options [Hash] additional host creation options.
+      # @return [Host]
       def host_factory_create_host token, id, options = {}
         token = token.token if token.is_a?(HostFactoryToken)
         http_options = {
           headers: { authorization: %Q(Token token="#{token}") }
         }
-        response = RestClient::Resource.new(Conjur::API.host_factory_asset_host, http_options)["hosts"].post(options.merge(id: id)).body
-        JSON.parse(response)
-      end
-    end
-    
-    # Options:
-    # +layers+ list of host factory layers
-    # +roleid+ host factory role id
-    # +role+ host factory role. If this is provided, it is converted to roleid.
-    def create_host_factory(id, options = {})
-      if options[:layers]
-        options[:layers] = options[:layers].map do |layer|
-          if layer.is_a?(Conjur::Layer)
-            layer.id
-          elsif layer.is_a?(String)
-            layer
-          else
-            raise "Can't interpret layer #{layer}"
-          end
+        response = RestClient::Resource.new(Conjur.configuration.core_url, http_options)["host_factories"]["hosts"].post(options.merge(id: id)).body
+        attributes = JSON.parse(response)
+        Host.new(attributes['id'], {}).tap do |host|
+          host.attributes = attributes
         end
       end
-      if role = options.delete(:role)
-        options[:roleid] = role.roleid
+      
+      # Revokes a host factory token. After revocation, the token can no longer be used to 
+      # create hosts.
+      # 
+      # @param [Hash] credentials authentication credentials of the current user.
+      # @param [String] token the host factory token.
+      def revoke_host_factory_token credentials, token
+        RestClient::Resource.new(Conjur.configuration.core_url, credentials)['host_factory_tokens'][token].delete
       end
-      log do |logger|
-        logger << "Creating host_factory #{id}"
-        unless options.blank?
-          logger << " with options #{options.to_json}"
-        end
-      end
-      options ||= {}
-      options[:id] = id
-      resp = RestClient::Resource.new(Conjur::API.host_factory_asset_host, credentials).post(options)
-      Conjur::HostFactory.build_from_response(resp, credentials)
     end
     
-    def host_factory id
-      Conjur::HostFactory.new(Conjur::API.host_factory_asset_host, credentials)[fully_escape(id)]
-    end
-
+      # Revokes a host factory token. After revocation, the token can no longer be used to 
+      # create hosts.
+      # 
+      # @param [String] token the host factory token.
     def revoke_host_factory_token token
-      token = token.token if token.is_a?(Conjur::HostFactoryToken)
-      RestClient::Resource.new(Conjur::API.host_factory_asset_host, credentials)["tokens/#{token}"].delete
-    end
-    
-    def show_host_factory_token token
-      token = token.token if token.is_a?(Conjur::HostFactoryToken)
-      attrs = JSON.parse(RestClient::Resource.new(Conjur::API.host_factory_asset_host, credentials)["tokens/#{token}"].get.body)
-      Conjur::HostFactoryToken.new(Conjur::API.host_factory_asset_host, credentials)["tokens"][attrs['token']].tap do |token|
-        token.attributes = attrs
-      end
-    end
-    
-    # Creates a Host and returns a Host object.
-    def host_factory_create_host token, id, options = {}
-      attributes = self.class.host_factory_create_host token, id, options
-      Conjur::Host.new(Conjur::API.core_asset_host, credentials)["hosts"][fully_escape attributes['id']].tap do |host|
-        host.attributes = attributes
-      end
+      self.class.revoke_host_factory_token credentials, token
     end
+
+    #@!endgroup
   end
 end

data/lib/conjur/api/policies.rb

@@ -0,0 +1,56 @@
+#
+# Copyright 2013-2017 Conjur Inc
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# 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.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+require 'conjur/policy_load_result'
+require 'conjur/policy'
+
+module Conjur
+  class API
+    #@!group Policy management
+    
+    # Append only.
+    POLICY_METHOD_POST = :post
+    # Allow explicit deletion statements, but don't delete implicitly delete data.
+    POLICY_METHOD_PATCH = :patch
+    # Replace the policy entirely, deleting any existing data that is not declared in the new policy.
+    POLICY_METHOD_PUT = :put
+
+    # Load a policy document into the server.
+    #
+    # The modes are support for policy loading:
+    #
+    # * POLICY_METHOD_POST Policy data will be added to the named policy. Deletions are not allowed.
+    # * POLICY_METHOD_PATCH Policy data can be added to or deleted from the named policy. Deletions
+    # are performed by an explicit `!delete` statement.
+    # * POLICY_METHOD_PUT The policy completely replaces the name policy. Policy data which is present
+    # in the server, but not present in the new policy definition, is deleted.
+    #
+    # @param id [String] id of the policy to load.
+    # @param policy [String] YAML-formatted policy definition. 
+    # @param account [String] Conjur organization account
+    # @param method [Symbol] Policy load method to use: {POLICY_METHOD_POST} (default), {POLICY_METHOD_PATCH}, or {POLICY_METHOD_PUT}.
+    def load_policy id, policy, account: Conjur.configuration.account, method: POLICY_METHOD_POST
+      request = RestClient::Resource.new(Conjur.configuration.core_url, credentials)['policies'][path_escape account]['policy'][path_escape id]
+      PolicyLoadResult.new JSON.parse(request.send(method, policy))
+    end
+
+    #@!endgroup
+  end
+end

data/lib/conjur/api/pubkeys.rb

@@ -1,5 +1,5 @@
 #
-# Copyright (C) 2013 Conjur Inc
+# Copyright 2013-2017 Conjur Inc
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy of
 # this software and associated documentation files (the "Software"), to deal in
@@ -21,165 +21,41 @@
 
 module Conjur
 
-   class API
-    # @!group Public Keys Service
-
-    # Fetch *all*  public keys for the user.  This method returns a newline delimited
-    # String for compatibility with the authorized_keys SSH format.
-    #
-    #
-    # If the given user does not exist, an empty String will be returned.  This is to prevent attackers from determining whether
-    # a user exists.
-    #
-    # ## Permissions
-    # You do not need any special permissions to call this method, since public keys are, well, public.
-    #
-    #
-    # @example
-    #   puts api.public_keys('jon')
-    #   # ssh-rsa [big long string] jon@albert
-    #   # ssh-rsa [big long string] jon@conjurops
-    #
-    # @param [String] username the *unqualified* Conjur username
-    # @return [String] newline delimited public keys
-    def public_keys username
-      public_keys_resource(username).get
-    end
-
-    
-    # Fetch a specific key by name.  The key name is the last token in the public key itself,
-    # typically formatted as `'<login>@<hostname>'`.
-    #
-    # ## Permissions
-    # You do not need any special permissions to call this method, since public keys are, well, public.
-    #
-    # @example Get bob's key for  'bob@somehost'
-    #   key = begin
-    #     api.public_key 'bob', 'bob@somehost'
-    #   rescue RestClient::ResourceNotFound
-    #     puts "Key or user not found!"
-    #     # Deal with it
-    #   end
-    #
-    #
-    # @param [String] username A Conjur username
-    # @param [String] keyname The name or identifier of the key
-    # @return [String] the public key
-    # @raise [RestClient::ResourceNotFound] if the user or key does not exist.
-    def public_key username, keyname
-      public_keys_resource(username, keyname).get
-    end
-
-    # List the public key names for the given user.
-    #
-    # If the given user does not exist, an empty Array will be returned.  This is to prevent attackers from determining whether
-    # a user exists.
-    #
-    # ## Permissions
-    # You do not need any special permissions to call this method, since public keys are, well, public.
-    #
-    #
-    # @example List the names of public keys for 'otto'
-    #   api.public_key_names('otto').each{|n| puts n}
-    #   # otto@somehost
-    #   # admin@someotherhost
-    #
-    # @example A non existent user has no public keys
-    #   user = api.user('doesnotexist')
-    #   user.exists? # => false
-    #   user.public_key_names # => []
-    #
-    # @param [String] username the Conjur username
-    # @return [Array<String>] the names of the user's public keys
-     def public_key_names username
-      public_keys(username).lines.map{|s| s.split(' ')[-1]}
-    end
-
-    # Add an SSH public key for `username`.
-    #
-    # ## Key Format
-    #
-    # This method will raise an exception if `key` is not of the format
-    # `"<algorithm> <data> <name>"` (that is, key.split(\s+\)).length must be 3).  The `<name>` field is used by the service
-    # to identify individual keys for a user.
-    #
-    # ## Permissions
-    #
-    # You must have permission to `'update'` the pubkeys service resource.  When the Conjur appliance
-    # is configured, it creates the pubkeys service resource with this identifier
-    # `'<organizational account>:service:pubkeys-1.0/public-keys'`.
-    #
-    # Rather than granting permissions to this resource directly to user roles, we recommend that you add them to the
-    # 'key-managers' group, whose *unqualified identifier* is 'pubkeys-1.0/key-managers', which has permission to add public
-    # keys.
-    #
-    # ## Hiding Existence
-    #
-    # Because attackers could use this method to determine the existence of Conjur users, it will not
-    # raise an error if the user does not exist.
-    #
-    # @example add a user's public key
-    #   # Check that the user exists so that we can fail when he doesn't.  Otherwise, this method
-    #   # will silently fail.
-    #   raise "No such user!" unless api.user('bob').exists?
-    #
-    #   # Add a key from a file
-    #   key = File.read('/path/to/public/key.pub')
-    #   api.add_public_key('bob', key)
-    #
-    # @param [String] username the name of the Conjur
-    # @param [String] key an SSH formated public key
-    # @return void
-    # @raise RestClient::BadRequest when the key is not in the correct format.
-    def add_public_key username, key
-      public_keys_resource(username).post key
-    end
-
-    # Delete a specific public key for a user.
-    #
-    # ## Permissions
-    # You must have permission to `'update'` the pubkeys service resource.  When the Conjur appliance
-    # is configured, it creates the pubkeys service resource with this identifier
-    # `'<organizational account>:service:pubkeys-1.0/public-keys'`.
-    #
-    # Rather than granting permissions to this resource directly to user roles, we recommend that you add them to the
-    # 'key-managers' group, whose *unqualified identifier* is 'pubkeys-1.0/key-managers', which has permission to add public
-    # keys.
-    #
-    # ## Hiding Existence
-    #
-    # Because attackers could use this method to determine the existence of Conjur users, it will not
-    # raise an error if the user does not exist.
-    #
-    # @example Delete all public keys for 'bob'
-    #
-    #   api.public_key_names('bob').count # => 6
-    #   api.public_key_names('bob').each do |keyname|
-    #     api.delete_public_key 'bob', keyname
-    #   end
-    #   api.public_key_names('bob').count # => 0
-    #
-    #
-    # @param [String] username the Conjur username/login
-    # @param [String] keyname the individual key to delete.
-    # @return [void]
-    def delete_public_key username, keyname
-      public_keys_resource(username, keyname).delete
-    end
-
-    #@!endgroup
-    
-    protected
-    # @api private
-    # Returns a RestClient::Resource with the pubkeys host and the given path.
-    def public_keys_resource *path
-      RestClient::Resource.new(Conjur::API.pubkeys_asset_host, credentials)[public_keys_path *path]
-    end
-
-    # @api private
-    # This method simply escapes each segment in `args` and joins them around `/`.
-    def public_keys_path *args
-      args.map{|a| fully_escape(a)}.join('/')
+  class API
+    class << self
+      # @!group Public Keys
+
+      # Fetch *all*  public keys for the user.  This method returns a newline delimited
+      # String for compatibility with the authorized_keys SSH format.
+      #
+      #
+      # If the given user does not exist, an empty String will be returned.  This is to prevent attackers from determining whether
+      # a user exists.
+      #
+      # ## Permissions
+      # You do not need any special permissions to call this method, since public keys are, well, public.
+      #
+      #
+      # @example
+      #   puts api.public_keys('jon')
+      #   # ssh-rsa [big long string] jon@albert
+      #   # ssh-rsa [big long string] jon@conjurops
+      #
+      # @param [String] username the *unqualified* Conjur username
+      # @return [String] newline delimited public keys
+      def public_keys username, account: Conjur.configuration.account
+        public_keys_resource(username, account).get
+      end
+
+      #@!endgroup
+      
+      protected
+
+      # @api private
+      # Returns a RestClient::Resource with the pubkeys host and the given path.
+      def public_keys_resource username, account
+        RestClient::Resource.new(Conjur.configuration.core_url)['public_keys'][fully_escape account]['user'][path_escape username]
+      end
     end
   end
 end