conjur-api 4.13.0 → 4.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 30c179935696f866037eeb767bc75a37fa852d2f
-  data.tar.gz: dbb483606b3f77c0340e4fd46c97ac954cb72920
+  metadata.gz: fa094471717dc9bb39477d76468d2663895d9fd4
+  data.tar.gz: d688adf16203e25c50646994bc619170d5633b89
 SHA512:
-  metadata.gz: 3b328c7fc9790246d738f07f9983c787d5024643fd41655430992d4526fd07106ddaae791572c4581a6f222b2bff370e6954125de91fa6f56382f7d93d93eed1
-  data.tar.gz: d754a280ea0ad20a031d1b0561ca1338bc08bcff3df5d99b4992e605106c18b2c02b66d5207e3fe108d5b76fba7ed91e3096f04a74e6d2c002a9ec97482504aa
+  metadata.gz: 434da500b0bb392deb9f0e8380dab357394aa2b16f28bb5063f2619a484646c1a1912267ee48eed7e3cea4d9e88ac256e23c466f6bd25faf1123294cce68af58
+  data.tar.gz: d9097541c2faff292c2f2c201a5b2d7dac162ca4c023b45d52093215acb310a17ce295762dc221d3a7c2952554c0efff59b911518853eea4282feca61648e330

data/.yardopts

@@ -0,0 +1 @@
+--hide-void-return --markup markdown --no-private --hide-api private lib/**/*.rb

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+# v4.14.0
+
+* Bump rest-client version, remove the troublesome mime-types patch
+* Make sure SSL certificate verification is enabled
+* Bugfix: Don't escape ids twice when listing records
+* Add a stub so that require 'conjur-api' works
+* Lots of doc updates
+
 # v4.13.0
 
 * Add GID handling utilities

data/Gemfile

@@ -8,4 +8,3 @@ gemspec
 group :development do
   gem 'pry'
 end
-

data/README.md

@@ -2,7 +2,7 @@
 
 Programmatic Ruby access to the Conjur API.
 
-## Installation
+# Installation
 
 Add this line to your application's Gemfile:
 
@@ -16,44 +16,85 @@ Or install it yourself as:
 
     $ gem install conjur-api
 
-## Usage
+# Usage
 
-### Programmatic configuration
+Connecting to Conjur is a two-step process:
 
-To configure the API to connect to Conjur, specify the account and appliance_url (both of which are required) like this:
+* **Configuration** Instruct the API where to find the Conjur endpoint and how to secure the connection.
+* **Authentication** Provide the API with credentials that it can use to authenticate.
+
+## Configuration
+
+The simplest way to configure the Conjur API is to use the configuration file stored on the machine.
+If you have configured the machine with [conjur init](http://developer.conjur.net/reference/tools/init.html),
+it's default location is `~/.conjurrc`. 
+
+The Conjur configuration process also checks `/etc/conjur.conf` for global settings. This is typically used
+in server environments.
+
+For custom scenarios, the location of the file can be overridden using the `CONJURRC` environment variable. 
+
+You can load the Conjur configuration file using the following Ruby code:
 
 ```ruby
-Conjur.configuration.account = 'my-account'
-Conjur.configuration.appliance_url = 'https://conjur.mydomain.com/api'
+require 'conjur/cli'
+Conjur::Config.load
+Conjur::Config.apply
 ```
 
-You can also specify these values in environment variables, which is often a bit more convenient.  Environment variables are mapped to configuration variables by prepending CONJUR_ to the all-caps name of the configuration variable, for example, `appliance_url` is `CONJUR_APPLIANCE_URL`, `account` is `CONJUR_ACCOUNT`, etc.
+**Note** this code requires the [conjur-cli](https://github.com/conjurinc/cli-ruby) gem, which should also be in your
+gemset or bundle.
 
-In either case, if you are using Conjur's self-signed cert, you will also need to configure certificate trust:
+## Authentication
+
+Once Conjur is configured, the connection can be established like this:
 
 ```ruby
-OpenSSL::SSL::SSLContext::DEFAULT_CERT_STORE.add_file "/path/to/conjur-youraccount.pem"
+conjur = Conjur::Authn.connect nil, noask: true
 ```
 
-### Using Conjur system configuraiton
+To [authenticate](http://developer.conjur.net/reference/services/authentication/authenticate.html), the API client must
+provide a `login` name and `api_key`. The `Conjur::Authn.connect` will attempt the following, in order:
+
+1. Look for `login` in environment variable `CONJUR_AUTHN_LOGIN`, and `api_key` in `CONJUR_AUTHN_API_KEY` 
+2. Look for credentials on disk. The default credentials file is `~/.netrc`. The location of the credentials file
+can be overridden using the configuration file `netrc_path` option. 
+3. Prompt for credentials. This can be disabled using the option `noask: true`.
+
+## Connecting Without Files
 
-To instantiate the API using configuration stored stored in `/etc/conjur.conf` and/or `~/.conjurrc`:
+It's possible to configure and authenticate the Conjur connection without using any files, and without requiring
+the `conjur-cli` gem.
+
+To accomplish this, apply the configuration settings directly to the [Conjur::Configuration](https://github.com/conjurinc/api-ruby/blob/master/lib/conjur/configuration.rb) 
+object.
+
+For example, specify the `account` and `appliance_url` (both of which are required) like this:
 
 ```ruby
-require 'conjur/cli'
-Conjur::Config.load
-Conjur::Config.apply
-conjur = Conjur::API.new_from_key username, api_key
+Conjur.configuration.account = 'my-account'
+Conjur.configuration.appliance_url = 'https://conjur.mydomain.com/api'
 ```
 
-`username` and `api_key` can also be provided by environment variables: `CONJUR_AUTHN_LOGIN` and `CONJUR_AUTHN_API_KEY`. If the login is a host, the `CONJUR_AUTHN_LOGIN` should be prefixed with `host/`. For example: `host/myhost.example.com`.
+You can also specify these values using environment variables, which is often a bit more convenient. 
+Environment variables are mapped to configuration variables by prepending `CONJUR_` to the all-caps name of the 
+configuration variable. For example, `appliance_url` is `CONJUR_APPLIANCE_URL`, `account` is `CONJUR_ACCOUNT`.
+
+In either case, you will also need to configure certificate trust. For example:
+
+```ruby
+OpenSSL::SSL::SSLContext::DEFAULT_CERT_STORE.add_file "/etc/conjur-yourorg.pem"
+```
 
-If the login and API key are provided by `netrc` or by the environment, you can construct an API client using:
+Once Conjur is configured, you can create a new API client by providing a `login` and `api_key`:
 
 ```ruby
-conjur = Conjur::Authn.connect
+Conjur::API.new_from_key login, api_key
 ```
 
+Note that if you are connecting as a [Host](http://developer.conjur.net/reference/services/directory/host), the login should be 
+prefixed with `host/`. For example: `host/myhost.example.com`, not just `myhost.example.com`.
+
 ## Contributing
 
 1. Fork it

data/conjur-api.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |gem|
   gem.required_ruby_version = '>= 1.9'
 
   
-  gem.add_dependency 'rest-client', '= 1.6.7' # with newer versions adding certificates to OpenSSL does not work
+  gem.add_dependency 'rest-client', '~> 1.7', '>= 1.7.3'
   gem.add_dependency 'activesupport'
   
   gem.add_development_dependency 'rake'
@@ -33,4 +33,5 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'yard'
   gem.add_development_dependency 'redcarpet'
   gem.add_development_dependency 'timecop'
+  gem.add_development_dependency 'inch'
 end

data/lib/conjur/acts_as_asset.rb

@@ -20,15 +20,12 @@
 #
 module Conjur
   module ActsAsAsset
-    def self.included(base)
-      base.instance_eval do
-        include HasId
-        include Exists
-        include HasOwner
-        include ActsAsResource
-        include HasAttributes
-      end
-    end
+    include HasId
+    include Exists
+    include HasOwner
+    include ActsAsResource
+    include HasAttributes
+
       
     def add_member(role_name, member, options = {})
       owned_role(role_name).grant_to member, options

data/lib/conjur/acts_as_role.rb

@@ -19,29 +19,76 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
+
+  # This module provides methods for things that have an associated {Conjur::Role}.
+  #
+  # All high level Conjur assets (groups and users, for example) are composed of both a role and a resource.  This allows
+  # these assets to have permissions on other assets, and for other assets to have permission
+  # on them.
+  #
+  # The {Conjur::ActsAsRole} module itself should be considered private, but it's methods are
+  # public when added to a Conjur asset class.
   module ActsAsRole
+
+    # The qualified identifier for the role associated with this asset.  A *qualified* identifier
+    # prepends the asset's account and kind, for example, a {Conjur::User} with login `'bob'` in a
+    # system with organizational account `'conjur'` would have a `roleid` of `'conjur:user:bob'`
+    #
+    # @return [String] the qualified role id
     def roleid
       [ core_conjur_account, role_kind, id ].join(':')
     end
-    
+    alias role_id roleid
+
+    # The `kind` of a role.  This may be any value, but standard ones correspond to various high level
+    # Conjur assets, for example, `'user'`, `'group'`, or `'variable'`.
+    #
+    # Note that this method derives the role kind from the asset's class name.
+    #
+    # @return [String] the role kind
     def role_kind
       self.class.name.split('::')[-1].underscore
     end
-   
-    # NOTE: parse_role_id returns tuple of path components 
-    # (basically, same components as in 'roleid' plus some prefixes)
+
+    # Get a {Conjur::Role} instance corresponding to the `role` associated with this asset.
     def role
       require 'conjur/role'
       Conjur::Role.new(Conjur::Authz::API.host, self.options)[Conjur::API.parse_role_id(self.roleid).join('/')]
     end
-    
-    # Permit this role to perform a privileged action.
+
+    # Permit the asset to perform `privilege` on `resource`.  You can also use this method to control whether the role
+    # is able to grant the privilege on the resource to other roles by passing a `:grant_option` option.
+    #
+    # This method is primarily intended for use in the
+    # {http://developer.conjur.net/reference/tools/utilities/policy-load.html Conjur Policy DSL},
+    # and simply delegates to {Conjur::Resource#permit}.  For code clarity, you might consider using
+    # that method instead.
+    #
+    # ### Permissions
+    #
+    # To call this method, you must *own* the resource, or have the privilege on it with grant option set to true.
+    #
+    # @api dsl
+    # @param [String] privilege the privilege to allow this role to perform, e.g. `'execute'` or `'update'`
+    # @param [Conjur::Resource, #resource_id, String] resource the resource to grant `privilege` on.
+    # @param [Hash] options Options to pass through to RestClient::Resource#post
+    # @option options [Boolean] :grant_option whether this role will be able to grant the privilege to other roles.
+    # @return [void]
     def can(privilege, resource, options = {})
       require 'conjur/resource'
       Conjur::Resource.new(Conjur::Authz::API.host, self.options)[Conjur::API.parse_resource_id(resource).join('/')].permit privilege, self.roleid, options
     end
 
-    # Deny this role from performing perform a privileged action.
+    # Deny the asset's role the ability to perform `privilege` on `resource`.  This operation is the inverse of {#can}.
+    #
+    # This method is primarily intended for use in the
+    # {http://developer.conjur.net/reference/tools/utilities/policy-load.html Conjur Policy DSL},
+    # and simply delegates to {Conjur::Resource#permit}.  For code clarity, you might consider using
+    # that method instead.
+    #
+    # @see Conjur::Resource#deny
+    #
+    # @api dsl
     def cannot(privilege, resource, options = {})
       require 'conjur/resource'
       Conjur::Resource.new(Conjur::Authz::API.host, self.options)[Conjur::API.parse_resource_id(resource).join('/')].deny privilege, self.roleid

data/lib/conjur/annotations.rb

@@ -19,13 +19,26 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
+  # Conjur allows {http://developer.conjur.net/reference/services/authorization/resource Resource}
+  #   instances to be {http://developer.conjur.net/reference/services/authorization/resource/annotate.html annotated}
+  #   with arbitrary key-value data.  This data is generally for "user consumption", and it *is not* governed
+  #   by any particular schema or constraints.  Your applications can define their own schema for annotations they
+  #   use.  If you do so, we recommend prefixing your annotations, for example, `'myapp:Name'`, in order to avoid
+  #   conflict with annotations used, for example, by the Conjur  UI.
+  #
   # An Annotations instance acts like a Hash: you can fetch an annotation
-  # with '[]' and update with '[]=', 'each' it, and 'merge!' to do bulk updates
-  # (although merge! is not more efficient than setting each pair with '[]=').
+  #   with {#[]} and update with {#[]=}, {#each} it, and {#merge!} to do bulk updates.
+  #
   class Annotations
     include Enumerable
-    
-    # @api private
+
+    # Create an `Annotations` instance for the given {Conjur::Resource}.
+    #
+    # Note that you will generally use the {Conjur::Resource#annotations} method to get
+    # the `Annotations` for a {Conjur::Resource}.
+    #
+    # @param resource [Conjur::Resource]
+    #
     def initialize resource
       @resource = resource
     end
@@ -37,11 +50,15 @@ module Conjur
       annotations_hash[name.to_sym]
     end
     
-    # Set an annotation value
+    # Set an annotation value.  This will perform an api call to set the annotation
+    #   on the server.
+    #
     # @param [String, Symbol] name the annotation name
     # @param [String] value the annotation value
+    #
+    # @return [String] the new annotation value
     def []= name, value
-      update_annotation name, value
+      update_annotation name.to_sym, value
       value
     end
     
@@ -52,31 +69,48 @@ module Conjur
       self
     end
 
-    # Set annotations from key,value pairs in +hash+
-    # @param [#each] hash
+    # Set annotations from key,value pairs in `hash`.
+    #
+    # @note this is currently no more efficient than setting each
+    #   annotation with {#[]=}.
+    #
+    # @param [Hash, #each] hash
     # @return [Conjur::Annotations] self
     def merge! hash
       hash.each{|k,v| self[k] = v }
       self
     end
     
-    # Return a proper hash containing a +copy+ of ourself.  Note that
+    # Return a proper hash containing a **copy** of the annotations.  Note that
     # updates to this hash have no effect on the actual annotations.
+    #
     # @return [Hash]
     def to_h
       annotations_hash.dup
     end
-    
+
+    # Return the annotations hash as a string.  This method simply delegates to
+    # `Hash#to_s`.
+    #
+    # @return [String]
     def to_s
       annotations_hash.to_s
     end
-    
+
+    # Return an informative representation of the annotations, including
+    # the resource to which they're attached.  Suitable for debugging.
+    #
+    # @return [String]
     def inspect
       "<Annotations for #{@resource.resourceid}: #{to_s}>"
     end
     
     protected
-    
+    #@api private
+    # Update an annotation on the server.
+    # @param name [String]
+    # @param value [String, #to_s]
+    # @return [void]
     def update_annotation name, value
       @resource.invalidate do
         @annotations_hash = nil
@@ -84,11 +118,15 @@ module Conjur
         RestClient::Resource.new(Conjur::Authz::API.host, @resource.options)[path].put name: name, value: value
       end
     end
-    
+
+    # @api private
+    # Our internal {Hash} of annotations.  Lazily loaded.
     def annotations_hash
       @annotations_hash ||= fetch_annotations
     end
-    
+
+    # @api private
+    # Fetch the annotations from the server.
     def fetch_annotations
       {}.tap do |hash|
         @resource.attributes['annotations'].each do |annotation|

data/lib/conjur/api/audit.rb

@@ -20,24 +20,70 @@
 
 require 'conjur/event_source'
 module Conjur
+
+
   class API
-    # Return all events visible to the current authorized role
+    #@!group Audit Service
+
+    # Return up to 100 audit events visible to the current authorized role.
+    #
+    # An audit event is visible to a role if that role or one of it's ancestors is in the
+    #   event's `:roles` field, or the role has a privilege any of the event's `:resources` field.
+    #
+    # @param options [Hash]
+    # @option options [Time, nil] :till only show events before this time
+    # @option options [Time, nil] :since only show events after this time
+    # @option options [Boolean] :follow block the current thread and call `block` with `Array` of
+    #   audit events as the occur.
+    #
+    # @see #audit_role
+    #
+    # @return [Array<Hash>] the audit events
     def audit options={}, &block
       audit_event_feed "", options, &block
     end
-    
-    # Return audit events related to the given role_id.  Identitical to audit_events
-    # except that a String may be given instead of a Role object.
-    # @param role [String] the role for which events should be returned.
+
+    # Return up to 100 audit events visible to the current role and related to the given role.
+    #
+    # See {#audit} for the conditions under which an event is visible to a role.
+    #
+    # An event is said to be "related to" a role iff the role is a member of the event's
+    # `:roles` field.
+    #
+    # @param role [Conjur::Role, String, #roleid] the role to audit (if a string is given, it must
+    #   be of the form `'account:kind:id'`).
+    # @param options [Hash]
+    # @option options [Time, nil] :till only show events before this time
+    # @option options [Time, nil] :since only show events after this time
+    # @option options [Boolean] :follow block the current thread and call `block` with `Array` of
+    #   audit events as the occur.
+    #
+    # @return [Array<Hash>] the audit events
     def audit_role role, options={}, &block
       audit_event_feed "roles/#{CGI.escape cast(role, :roleid)}", options, &block
     end
-    
-    # Return audit events related to the given resource
+
+    # Return up to 100 audit events visible to the current role and related to the given resource.
+    #
+    # See {#audit} for the conditions under which an event is visible to a role.
+    #
+    # An event is said to be "related to" a role iff the role is a member of the event's
+    #   `:roles` field.
+    # @param resource [Conjur::Resource, String, #resourceid] the resource to audit (when a string is given, it must be
+    #   of the form `'account:kind:id'`).
+    # @param options [Hash]
+    # @option options [Time, nil] :till only show events before this time
+    # @option options [Time, nil] :since only show events after this time
+    # @option options [Boolean] :follow block the current thread and call `block` with `Array` of
+    #   audit events as the occur.
+    #
+    # @return [Array<Hash>] the audit events
     def audit_resource resource, options={}, &block
       audit_event_feed "resources/#{CGI.escape cast(resource, :resourceid)}", options, &block
     end
-    
+
+    #@!endgroup
+
     private
     def audit_event_feed path, options={}, &block
       query = options.slice(:since, :till)

data/lib/conjur/api/authn.rb

@@ -23,7 +23,28 @@ require 'conjur/user'
 module Conjur
   class API
     class << self
-      # Perform login by Basic authentication.
+      #@!group Authentication Methods
+
+      # 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
+      #   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.
+      #
+      # @example
+      #   bob_api_key = Conjur::API.login('bob', 'bob_password')
+      #   bob_api_key == Conjur::API.login('bob', bob_api_key)  # => true
+      #
+      # @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.
+      # @return [String] the API key.
+      # @raise [RestClient::Exception] when the request fails or the identity provided is invalid.
       def login username, password
         if Conjur.log
           Conjur.log << "Logging in #{username} via Basic authentication\n"
@@ -31,7 +52,16 @@ module Conjur
         RestClient::Resource.new(Conjur::Authn::API.host, user: username, password: password)['users/login'].get
       end
 
-      # Perform login by CAS authentication.
+      # 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"
@@ -41,27 +71,42 @@ module Conjur
         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.
+      #
+      # @param [String] username The username or host id for which we want a token
+      # @param [String] password The password or api key
+      # @return [String] A JSON formatted authentication token.
       def authenticate username, password
         if Conjur.log
           Conjur.log << "Authenticating #{username}\n"
         end
         JSON::parse(RestClient::Resource.new(Conjur::Authn::API.host)["users/#{fully_escape username}/authenticate"].post password, 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
+      #   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] new_password the new password for the user.
+      # @return [void]
       def update_password username, password, new_password
         if Conjur.log
           Conjur.log << "Updating password for #{username}\n"
         end
         RestClient::Resource.new(Conjur::Authn::API.host, user: username, password: password)['users/password'].put new_password
       end
+
+      #@!endgroup
     end
 
-    # Options:
-    # +password+
-    #
-    # Response:
-    # +login+
-    # +api_key+
+    # @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}"

data/lib/conjur/api/groups.rb

@@ -20,29 +20,92 @@
 require 'conjur/group'
 
 module Conjur
+
+
   class API
+    # @!group Directory: Groups
+
+    # List all Conjur groups visible to the current role.  This method does not
+    # support advanced query options.  If you want those, use `#resources` with
+    # the `:kind` option set to `'group'`.
+    #
+    # @example
+    #   api.groups.count # => 163 (yikes!)
+    #
+    # @param options [Hash] included for compatibility.  Do not use this parameter!
+    # @return [Array<Conjur::Group>]
     def groups(options={})
       standard_list Conjur::Core::API.host, :group, options
     end
 
+    # Create a new group with the given identifier.
+    #
+    # Groups can be created with a gidnumber attribute, which is used when mapping LDAP/ActiveDirectory groups
+    # to Conjur groups, and when performing PAM authentication to assign a unix GID.
+    #
+    #
+    # @example
+    #   group = api.create_group 'cats'
+    #   puts group.attributes
+    #   # Output
+    #   {"id"=>"cats",
+    #     "userid"=>"admin",
+    #     "ownerid"=>"conjur:user:admin",
+    #     "gidnumber"=>nil,
+    #     "roleid"=>"conjur:group:cats",
+    #     "resource_identifier"=>"conjur:group:cats"}
+    #
+    # @example Create a group with a GID number.
+    #   group = api.create_group 'dogs', gidnumber: 1337
+    #   puts group.attributes['gidnumber']
+    #   # Output
+    #   1337
+    #
+    # @param [String] id the identifier for this group
+    # @param [Hash] options options for group creation
+    # @option options [FixNum] :gidnumber gidnumber to assign to this group (if not present, the
+    #   group will *not* have a gidnumber, in contrast to Conjur {Conjur::User} instances).
+    # @return [Conjur::Group] the group created.
     def create_group(id, options = {})
       standard_create Conjur::Core::API.host, :group, id, options
     end
 
+
+    # Fetch a group with the given id.  Note that the id is *unqualified* -- it must not contain
+    # `account` or `id` parts.  For example,
+    #
+    # @example
+    #   group = api.create_group 'fish'
+    #   right = api.group 'fish'
+    #   wrong = api.group 'conjur:group:fish'
+    #   right.exists? # => true
+    #   wrong.exists? # => false
+    #
+    # @param [String] id the identifier of the group
+    # @return [Conjur::Group] the group, which may or may not exist (you must check this using the {Conjur::Exists#exists?})
+    #   method.
     def group id
       standard_show Conjur::Core::API.host, :group, id
     end
 
-    # Find groups by GID.
+    # Find groups by GID.  Note that gidnumbers are *not* unique for groups.
+    #
+    # @example
+    #   dogs = api.create_group 'dogs', gidnumber: 42
+    #   cats = api.create_group 'cats', gidnumber: 42
+    #   api.find_groups gidnumber: 42
+    #   # => ['cats', 'dogs']
+    #
+    # @example
+    #   groups = api.find_groups(gidnumber: 42).map{|id| api.group(id)}
+    #   groups.map(&:class) # => [Conjur::Group, Conjur::Group]
     #
     # @param [Hash] options search criteria
     # @option options [Integer] :gidnumber GID number
     # @return [Array<String>] group names matching the criteria
-    #
-    # @note You can get a {Conjur::Group} by calling {Conjur::API#group}, eg.:
-    #   +api.find_groups(gidnumber: 12345).map(&api.method(:group))+
     def find_groups options
       JSON.parse(RestClient::Resource.new(Conjur::Core::API.host, credentials)["groups/search?#{options.to_query}"].get)
     end
+    #@!endgroup
   end
 end