conjur-api 5.3.8.pre.8 → 5.3.8.pre.194

data/lib/conjur/acts_as_user.rb

@@ -0,0 +1,68 @@
+#
+# 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.
+#
+module Conjur
+  # This module provides methods for things that are like users (specifically, those that have
+  # api keys).
+  module ActsAsUser
+    # @api private
+    def self.included(base)
+      base.include ActsAsRolsource
+    end
+
+    # Returns a newly created user's api_key.
+    #
+    # @note The API key is not returned by {API#resource}. It is only available
+    # via {API#login}, when the object is newly created, and when the API key is rotated.
+    #
+    # @return [String] the api key
+    # @raise [Exception] when the object isn't newly created.
+    def api_key
+      attributes['api_key'] or raise "api_key is only available on a newly created #{kind}"
+    end
+
+    # Create an api logged in as this user-like thing.
+    #
+    # @note As with {#api_key}, this method only works on newly created instances.
+    # @see #api_key
+    # @return [Conjur::API] an api logged in as this user-like thing.
+    def api
+      Conjur::API.new_from_key login, api_key, account: account
+    end
+
+    # Rotate this role's API key. You must have `update` permission on the user to do so.
+    #
+    # @note You will not be able to access the API key returned by this method later, so you should
+    #   probably hang onto it it.
+    #
+    # @note You cannot rotate your own API key with this method. To do so, use `Conjur::API.rotate_api_key`.
+    #
+    # @note This feature requires a Conjur appliance running version 4.6 or higher.
+    #
+    # @return [String] the new API key for this user.
+    def rotate_api_key
+      if login == username
+        raise 'You cannot rotate your own API key via this method. To do so, use `Conjur::API.rotate_api_key`'
+      end
+
+      url_for(:authn_rotate_api_key, credentials, account, id).put("").body
+    end
+  end
+end

data/lib/conjur/api/authenticators.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'conjur/webservice'
+
+module Conjur
+  # API contains each of the methods for access the Conjur API endpoints
+  #-- :reek:DataClump for authenticator identifier fields (name, id, account)
+  class API
+    # @!group Authenticators
+
+    # List all configured authenticators
+    def authenticator_list
+      JSON.parse(url_for(:authenticators).get)
+    end
+
+    # Enables an authenticator in Conjur. The authenticator must be defined and
+    # loaded in Conjur policy prior to enabling it.
+    # 
+    # @param [String] authenticator the authenticator type to enable (e.g. authn-k8s)
+    # @param [String] id the service ID of the authenticator to enable
+    def authenticator_enable authenticator, id, account: Conjur.configuration.account
+      url_for(:authenticator, account, authenticator, id, credentials).patch(enabled: true)
+    end
+
+    # Disables an authenticator in Conjur.
+    # 
+    # @param [String] authenticator the authenticator type to disable (e.g. authn-k8s)
+    # @param [String] id the service ID of the authenticator to disable
+    def authenticator_disable authenticator, id, account: Conjur.configuration.account
+      url_for(:authenticator, account, authenticator, id, credentials).patch(enabled: false)
+    end
+
+    # @!endgroup
+  end
+end

data/lib/conjur/api/authn.rb

@@ -0,0 +1,125 @@
+#
+# 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/user'
+
+module Conjur
+  class API
+    class << self
+      #@!group Authentication
+
+      # 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 {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')
+      #   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.
+      # @param [String] account The organization account.
+      # @return [String] the API key.
+      def login username, password, account: Conjur.configuration.account
+        if Conjur.log
+          Conjur.log << "Logging in #{username} to account #{account} via Basic authentication\n"
+        end
+        url_for(:authn_login, account, username, password).get
+      end
+
+      # 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] api_key The api key
+      # @param [String] account The organization account.
+      # @return [String] A JSON formatted authentication token.
+      def authenticate username, api_key, account: Conjur.configuration.account
+        account ||= Conjur.configuration.account
+        if Conjur.log
+          Conjur.log << "Authenticating #{username} to account #{account}\n"
+        end
+        JSON.parse url_for(:authn_authenticate, account, username).post(api_key, content_type: 'text/plain')
+      end
+
+      # Obtains an access token from the +authn_local+ service. 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] account The organization account.
+      # @return [String] A JSON formatted authentication token.
+      def authenticate_local username, account: Conjur.configuration.account, expiration: nil, cidr: nil
+        account ||= Conjur.configuration.account
+        if Conjur.log
+          Conjur.log << "Authenticating #{username} to account #{account} using authn_local\n"
+        end
+
+        require 'json'
+        require 'socket'
+        message = url_for(:authn_authenticate_local, username, account, expiration, cidr)
+        JSON.parse(UNIXSocket.open(Conjur.configuration.authn_local_socket) {|s| s.puts message; s.gets })
+      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.
+      # @param [String] account The organization account.
+      # @return [void]
+      def update_password username, password, new_password, account: Conjur.configuration.account
+        if Conjur.log
+          Conjur.log << "Updating password for #{username} in account #{account}\n"
+        end
+        url_for(:authn_update_password, account, username, password).put new_password
+      end
+
+      #@!endgroup
+
+      #@!group Password and API key management
+
+      # 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 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} in account #{account})\n"
+        end
+
+        url_for(:authn_rotate_own_api_key, account, username, password).put('').body
+      end
+
+      #@!endgroup
+    end
+  end
+end

data/lib/conjur/api/host_factories.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# Copyright 2013-2018 CyberArk Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'conjur/host_factory'
+
+module Conjur
+  class API
+    #@!group Host Factory
+
+    class << self
+      # 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)
+        response = url_for(:host_factory_create_host, token)
+          .post(options.merge(id: id)).body
+
+        attributes = JSON.parse(response)
+        # in v4 'id' is just the identifier
+        host_id = attributes['roleid'] || attributes['id']
+
+        Host.new(host_id, {}).tap do |host|
+          host.attributes = attributes
+        end
+      end
+      
+      # 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
+        url_for(:host_factory_revoke_token, credentials, token).delete
+      end
+    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
+      self.class.revoke_host_factory_token credentials, token
+    end
+
+    #@!endgroup
+  end
+end

data/lib/conjur/api/ldap_sync.rb

@@ -0,0 +1,38 @@
+#
+# Copyright 2013-2018 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.
+#
+
+module Conjur
+  class API
+    
+    # Retrieve the policy for the given LDAP sync
+    # configuration. Configurations created through the Conjur UI are
+    # named +default+, so the default value of +config_name+ can be
+    # used.
+    #
+    # For details on the use of LDAP sync, see
+    # https://developer.conjur.net/reference/services/ldap_sync/ .
+    #
+    # @param [String] config_name the name of the LDAP sync configuration.
+    def ldap_sync_policy config_name: 'default'
+      JSON.parse(url_for(:ldap_sync_policy, credentials, config_name).get)
+    end
+  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 = url_for(:policies_load_policy, credentials, account, id)
+      PolicyLoadResult.new JSON.parse(request.send(method, policy))
+    end
+
+    #@!endgroup
+  end
+end

data/lib/conjur/api/pubkeys.rb

@@ -0,0 +1,53 @@
+#
+# 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.
+#
+
+module Conjur
+
+  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
+        url_for(:public_keys_for_user, account, username).get
+      end
+
+      #@!endgroup
+    end
+  end
+end

data/lib/conjur/api/resources.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+# Copyright 2013-2018 CyberArk Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'conjur/resource'
+
+module Conjur
+  class API
+    include QueryString
+    include BuildObject
+
+    #@!group Resources
+
+    # Find a resource by its id.
+    # @note The id given to this method must be fully qualified.
+    #
+    # ### Permissions
+    #
+    # The resource **must** be visible to the current role.  This is the case if the current role is the owner of
+    # the resource, or has any privilege on it.
+    #
+    # @param id [String] a fully qualified resource identifier
+    # @return [Conjur::Resource] the resource, which may or may not exist
+    def resource id
+      build_object id
+    end
+
+    # Find all resources visible to the current role that match the given search criteria.
+    #
+    # ## Full Text Search
+    # Conjur supports full text search over the identifiers and annotation *values*
+    # of resources.  For example, if `opts[:search]` is `"pubkeys"`, any resource with
+    # an id containing `"pubkeys"` or an annotation whose value contains `"pubkeys"` will match.
+    #
+    # **Notes**
+    #   * Annotation *keys* are *not* indexed for full text search.
+    #   * Conjur indexes the content of ids and annotation values by word.
+    #   * Only resources visible to the current role (either owned by that role or
+    #       having a privilege on it) are returned.
+    #   * If you do not provide `:offset` or `:limit`, all records will be returned. For systems
+    #       with a huge number of resources, you may want to paginate as shown in the example below.
+    #   * If `:offset` is provided and `:limit` is not, 10 records starting at `:offset` will be
+    #       returned.  You may choose an arbitrarily large number for `:limit`, but the same performance
+    #       considerations apply as when omitting `:offset` and `:limit`.
+    #
+    # @example Search for resources annotated with the text "WebService Route"
+    #    webservice_routes = api.resources search: "WebService Route"
+    #
+    # @example Restrict the search to 'group' resources
+    #   groups = api.resources kind: 'group'
+    #
+    #   # Correct behavior:
+    #   expect(groups.all?{|g| g.kind == 'group'}).to be_true
+    #
+    # @example Get every single resource in a performant way
+    #   resources = []
+    #   limit = 25
+    #   offset = 0
+    #   until (batch = api.resources limit: limit, offset: offset).empty?
+    #     offset += batch.length
+    #     resources.concat results
+    #   end
+    #   # do something with your resources
+    #
+    # @param options [Hash] search criteria
+    # @option options [String]   :search find resources whose ids or annotations contain this string
+    # @option options [String]   :kind find resources whose `kind` matches this string
+    # @option options [Integer]  :limit the maximum number of records to return (Conjur may return fewer)
+    # @option options [Integer]  :offset offset of the first record to return
+    # @option options [Boolean]  :count return a count of records instead of the records themselves when set to true
+    # @return [Array<Conjur::Resource>] the resources matching the criteria given
+    def resources options = {}
+      options = { host: Conjur.configuration.core_url, credentials: credentials }.merge options
+      options[:account] ||= Conjur.configuration.account
+
+      host, credentials, account, kind = options.values_at(*[:host, :credentials, :account, :kind])
+      fail ArgumentError, "host and account are required" unless [host, account].all?
+      %w(host credentials account kind).each do |name|
+        options.delete(name.to_sym)
+      end
+
+      result = JSON.parse(url_for(:resources, credentials, account, kind, options).get)
+
+      result = result['count'] if result.is_a?(Hash)
+
+      if result.is_a?(Numeric)
+        result
+      else
+        result.map do |result|
+          resource(result['id']).tap do |r|
+            r.attributes = result
+          end
+        end
+      end
+    end
+  end
+end

data/lib/conjur/api/roles.rb

@@ -0,0 +1,98 @@
+#
+# 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/role'
+
+module Conjur
+  class API
+    include BuildObject
+
+    #@!group Roles
+
+    # 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
+    #   iggy = api.role 'cat:iggy'
+    #   iggy.exists? # true
+    #   iggy.members.map(&:member).map(&:id) # => ['conjur:user:admin']
+    #   api.current_role.id # => '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 id [String] a fully qualified role identifier
+    # @return [Conjur::Role] an object representing the role
+    def role id
+      build_object id, default_class: Role
+    end
+
+    # Return a {Conjur::Role} object representing the role (typically a user or host) that this API instance 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} or {Conjur::API.new_from_token_file}.
+    #
+    # @example Current role for a user
+    #   api = Conjur::API.new_from_key 'jon', 'somepassword'
+    #   api.current_role.id # => '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.id # => 'conjur:host:example-host'
+    #
+    # @param [String] account the organization account 
+    # @return [Conjur::Role] the authenticated role for this API instance
+    def current_role account
+      self.class.role_from_username self, username, account
+    end
+
+    #@!endgroup
+
+    class << self
+      # @api private
+      def role_from_username api, username, account
+        api.role role_name_from_username(username, account)
+      end
+
+      # @api private
+      def role_name_from_username username, account
+        tokens = username.split('/')
+        if tokens.size == 1
+          [ account, 'user', username ].join(':')
+        else
+          [ account, tokens[0], tokens[1..-1].join('/') ].join(':')
+        end
+      end
+    end
+  end
+end