user.rb in conjur-api-4.15.0

- old
+ new
@@ -19,17 +19,69 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
   class InvalidToken < Exception
   end
-  
+
+  # This class represents a {http://developer.conjur.net/reference/services/directory/user Conjur User}.
   class User < RestClient::Resource
     include ActsAsAsset
     include ActsAsUser
-    
-    alias login id
 
+    # Using a method instead of an alias here to make the docs look nicer :-/ - jjm
+
+    # This method is simply an alias for {#id}.  It returns the user's *unqualified* id, which is referred to as
+    # `login` here because it can be used to login to Conjur.
+    # @return [String] the login for this user
+    def login; id end
+
+    # Assign new attributes to the user.  Currently, this method only lets you change the
+    # `:uidnumber` attribute.
+    #
+    # If a user with the given `:uidnumber` already exists, this method will raise `RestClient::Forbidden`, with
+    # the response body providing additional details if possible.
+    #
+    # ### Permissions
+    # You must be a member of the user's role to call this method.
+    #
+    # @note This feature requires Conjur server version 4.3 or later.
+    #
+    # @param [Hash] options attributes to change
+    # @option options [FixNum] :uidnumber the new uidnumber for this user.  This option *must* be present.
+    # @return [void]
+    # @raise [RestClient::Conflict] if the uidnumber is already in use
+    # @raise [ArgumentError] if uidnumber isn't a `Fixnum` or isn't present in `options`
     def update options
+      # Currently the server raises a 400 Bad Request if uidnumber is missing, require it here
+      raise ArgumentError "options[:uidnumber] is required" unless uidnumber = options[:uidnumber]
+      raise ArgumentError, "options[:uidnumber] must be a Fixnum" unless uidnumber.kind_of?(Fixnum)
       self.put(options)
+    end
+
+    # Get the user's uidnumber, which is used by LDAP and SSH login, among other things.
+    #
+    # ### Permissions
+    # You must have the `'show'` permission on the user's resource to call this method
+    #
+    # @note This feature requires Conjur server version 4.3 or later.
+    #
+    # @return [Fixnum] the uidnumber
+    # @raise [RestClient::Forbidden] if you don't have permission to `show` the user.
+    def uidnumber
+      attributes['uidnumber']
+    end
+
+    # Set the user's uidnumber, which is used by LDAP and SSH login.
+    #
+    # ### Permissions
+    # You must be a member of the user's role to call this method.
+    #
+    # @note This feature requires Conjur server version 4.3 or later.
+    #
+    # @param [Fixnum] uidnumber the new uidnumber
+    # @return [void]
+    # @raise [RestClient::Conflict] if the uidnumber is already in use.
+    def uidnumber= uidnumber
+      update uidnumber: uidnumber
     end
   end
 end