clonk 1.0.0alpha3 → 1.0.0alpha4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0c722bf99f97acd973f4cf92eeaa6823b92abc6cdd99cf77f7e32cac22915e7
-  data.tar.gz: d0af13e57c50e1baca63d908dfee9d3c1a5dbec49b890899fdb7451262b3af36
+  metadata.gz: 6f7aa0b12c57241a41d20426c06220f03c74247ae3d685c25a1062052ed2297a
+  data.tar.gz: 16fe259d548ca99777ca99442894377c2ef99bce191ce069af0c507afd85df78
 SHA512:
-  metadata.gz: 392a00ab4d0805bc945b4f0cc45901bc98f51dbf79e2a068812e711e106943496dddba917b7cc13b5f1f4ce211926c36969515c47e51deb2107a02ac28e48adb
-  data.tar.gz: edea7bd7824a35e0e7161a543cff8fb773288c7513c6152b2379c3ee2b17e1bdef181149d1007073b48ae9f131473e37488f7ac1ead6a9d8f8a75c7e1caab63b
+  metadata.gz: 794fd86cc27312327b5b4f42739d151d29dc3c489d28b215c28cca805502e35f0a87ed64447bf358e1791a5327e45fa4e8de814574206bc869d0cc1b542b67e6
+  data.tar.gz: 7a0643e05af7c708f404194d310ab6301848fa1054f8cee66b6344bbd5613ca6015dfc9145cc9dc13bd2bbbabc0bc07c83920c77444adc80b1a1bf0639d1fc52

data/.yardoc/checksums

@@ -0,0 +1,8 @@
+lib/clonk.rb 20e9972dadb66fb1771722d9b06e3ccdad9e1022
+lib/clonk/role.rb 56ea266896bcb2b45cc48ee633c83639d2135296
+lib/clonk/user.rb a7da95bf320c5aaa7cc7708d9fe2ffd10f4eda23
+lib/clonk/group.rb 29edd3c17b7babce87bb544333d42455ec1a5c2e
+lib/clonk/realm.rb 0f933b0fd76545c049a5cb228706f13117fbcbb3
+lib/clonk/client.rb 41af98a3b30b4adff27b5d62c6b26559335b369f
+lib/clonk/policy.rb 8b8840f6763a1a320759a3c9d052758f25b17463
+lib/clonk/permission.rb 4466f7c1d3bef61521df03ee0b92c85f7be6cb66

data/Gemfile.lock

@@ -0,0 +1,24 @@
+PATH
+  remote: .
+  specs:
+    clonk (1.0.0alpha3)
+      faraday
+      faraday_middleware
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    faraday (0.15.3)
+      multipart-post (>= 1.2, < 3)
+    faraday_middleware (0.12.2)
+      faraday (>= 0.7.4, < 1.0)
+    multipart-post (2.0.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  clonk!
+
+BUNDLED WITH
+   1.16.2

data/README.md

@@ -0,0 +1,59 @@
+# Clonk [![Gem Version](https://badge.fury.io/rb/clonk.svg)](https://badge.fury.io/rb/clonk)
+
+This is a gem that'll help you seed an instance of Red Hat SSO. Right now, it's still a work-in-progress, but it shouldn't be long before it's got everything I think it needs.
+
+It makes some assumptions about what's in your environment at the moment, using `dotenv`. While developing, I'm keeping the following variables in there.
+
+```
+SSO_REALM="master"
+SSO_BASE_URL="http://localhost:8080/auth"
+SSO_USERNAME="user"
+SSO_PASSWORD="password"
+```
+
+It's recommended to spin up an SSO instance alongside this to see what effects you're having on it. Here, it's important that the `preview` profile is used, so that we can use the `realm-management` client to take care of permissions in the realm.
+
+```
+docker run --rm -p 8080:8080 -e JAVA_OPTS_APPEND="-Dkeycloak.profile=preview" -e SSO_ADMIN_USERNAME=user -e SSO_ADMIN_PASSWORD=password registry.access.redhat.com/redhat-sso-7/sso72-openshift
+```
+
+## Usage
+
+Clonk exposes SSO objects as ActiveRecord-esque models. As a short demonstration:
+
+```
+2.5.1 :003 > Clonk::Group.all
+ => [#<Clonk::Group:0x00007fe7139ecda0 @name="another-test", @id="42b28060-7f4f-4b6d-82fd-6af031881a9e", @realm="master">, #<Clonk::Group:0x00007fe713808228 @name="chaos-chaos", @id="05af3f68-44d6-4973-8834-e957822e43ef", @realm="master">]
+2.5.1 :004 > Clonk::Group.all.first.config
+ => {"id"=>"42b28060-7f4f-4b6d-82fd-6af031881a9e", "name"=>"another-test", "path"=>"/another-test", "attributes"=>{}, "realmRoles"=>[], "clientRoles"=>{}, "subGroups"=>[], "access"=>{"view"=>true, "manage"=>true, "manageMembership"=>true}}
+```
+
+`Group.all` casts all groups in the realm to `Clonk::Group` objects...
+
+...but you can access their plain JSON config with `Group#config`.
+
+Right now, you can check the `lib` folder for details of which methods are exposed, but I'm looking to add documentation in the very near future. Think of this as a soft launch.
+
+## Why?
+
+When developing against Red Hat SSO and Keycloak, I've personally struggled to deal with the documentation. There are a lot of assumptions that are made about what you know and what you don't. So I've made this gem...
+
+### ...to help devs use SSO platforms with their Rails apps
+
+Sometimes, Devise just doesn't cut it, especially if you want to allow users to sign into multiple apps with the same credentials. Running a SSO instance that all your apps can call off to can make things more flexible!
+
+### ...to document API endpoints that are documented either confusingly or not at all
+
+SSO is a huge project, so it's sort of understandable that perhaps its documentation isn't too easy to understand at first glance...especially if you've never used an SSO backend before. Some API endpoints that'll be used in this gem aren't even documented.
+
+### ...to better integrate Ruby/Rails with SSO
+
+I guess this comes back to the first one. SSO integration with Rails apps could be really powerful. Especially if it's wrapped in that familiar ActiveRecord style.
+
+### ...to make seeding SSO a lot more readable in future
+
+I seeded SSO with more `curl` requests than you could shake a stick at. Suffice to say, it didn't look like the prettiest piece of code...
+
+### ...to transfer what I've learned
+
+This gem goes hand-in-hand with a blog post I'm writing, but I'm hoping it'll go further than just that tutorial. Fingers crossed this gem will have its tendrils deep in a lot of SSO instances out there...which sounds a little ominous, but...yeah, you get the gist!

data/clonk.gemspec

@@ -0,0 +1,15 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+Gem::Specification.new do |s|
+  s.name = %q{clonk}
+  s.version = "1.0.0alpha4"
+  s.authors = ["Simon Fish"]
+  s.date = %q{2018-11-19}
+  s.summary = %q{Keycloak/RHSSO admin API client}
+  s.files = `git ls-files`.split("\n")
+  s.require_paths = Dir.glob("lib/**/*")
+  s.add_runtime_dependency 'faraday'
+  s.add_runtime_dependency 'faraday_middleware'
+  s.metadata["yard.run"] = "yardoc"
+end

data/lib/clonk/client.rb

@@ -0,0 +1,162 @@
+module Clonk
+
+  ##
+  # This class represents a client within SSO. A client allows a user to authenticate against SSO with their credentials.
+
+  class Client
+    attr_accessor :id
+    attr_reader :name
+
+    def initialize(clients_response, realm)
+      @id = clients_response['id']
+      @name = clients_response['clientId']
+      @realm = realm
+    end
+
+    ##
+    # Returns the defaults for some fields. The rest should be defined on a relevant call.
+
+    def self.defaults
+      {
+        fullScopeAllowed: false
+      }
+    end
+
+    ##
+    # Creates a client within SSO and returns the created client as a Client.
+    # Note: 'dag' stands for Direct Access Grants
+
+    def self.create(realm: REALM, name: nil, public_client: true, dag_enabled: true)
+      # TODO: Client with a secret
+      response = Clonk.response(
+        protocol: :post,
+        path: "#{Clonk.realm_admin_root(realm)}/clients",
+        data: defaults.merge(
+          clientId: name,
+          publicClient: public_client,
+          directAccessGrantsEnabled: dag_enabled
+        )
+      )
+      new_client_id = response.headers[:location].split('/')[-1]
+      new_from_id(new_client_id, realm)
+    end
+
+    ##
+    # Gets the config inside SSO for a particular client.
+    # This allows for access to many attributes that Clonk might not directly
+    # handle yet.
+    # You may be able to extend Clonk's functionality by using Clonk.response
+    # or Clonk.parsed_response with routes in the SSO API alongside this data.
+
+    def self.get_config(id, realm = REALM)
+      Clonk.parsed_response(
+        path: "#{Clonk.realm_admin_root(realm)}/clients/#{id}"
+      )
+    end
+
+    ##
+    # Gets the config inside SSO for this client.
+
+    def config
+      self.class.get_config(@id, @realm)
+    end
+
+    ##
+    # Creates a new Client instance from a client that exists in SSO
+
+    def self.new_from_id(id, realm = REALM)
+      new(get_config(id, realm), realm)
+    end
+
+    ##
+    # Returns an array of the clients that exist in the given realm.
+
+    def self.all(realm: REALM)
+      Clonk.parsed_response(
+        path: "#{Clonk.realm_admin_root(realm)}/clients"
+      ).map { |client| new_from_id(client['id'], realm) }
+    end
+
+    ##
+    # Searches for clients with the given name in the given realm.
+
+    def self.where(name: nil, realm: REALM)
+      all(realm: realm).select { |client| client.name == name }
+    end
+
+    ##
+    # Searches for exactly one client with the given name in the given realm.
+
+    def self.find_by(name: nil, realm: REALM)
+      where(name: name, realm: realm)&.first
+    end
+
+    ##
+    # Returns the URL that can be used to fetch this client's data from the API.
+
+    def url
+      "#{Clonk.realm_admin_root(@realm)}/clients/#{@id}"
+    end
+
+    ##
+    # Maps the given role into the scope of the client. If a user has that role,
+    # it will be visible in tokens given by this client during authentication.
+
+    def map_scope(client: nil, role: nil, realm: REALM)
+      Clonk.parsed_response(
+        protocol: :post,
+        data: [role.config],
+        path: "#{url}/scope-mappings/clients/#{client.id}"
+      )
+    end
+
+    ##
+    # Creates a role within this client.
+    # it will be visible in tokens given by this client during authentication, 
+    # as it is already in scope.
+
+    def create_role(realm: REALM, name: nil, description: nil, scope_param_required: false)
+      # TODO: Create realm roles
+      Clonk.parsed_response(protocol: :post,
+                      path: "#{url}/roles",
+                      data: {
+                        name: name,
+                        description: description,
+                        scopeParamRequired: scope_param_required
+                      })
+    end
+
+    ##
+    # Lists the client's permission IDs, if permissions are enabled.
+    # These will be returned as either a boolean (false) if disabled,
+    # or a hash of permission types and IDs.
+
+    def permissions
+      Clonk.parsed_response(
+        path: "#{url}/management/permissions"
+      )['scopePermissions'] || false
+    end
+
+    ##
+    # Enables or disables permissions for a client
+
+    def set_permissions(enabled: true)
+      Clonk.parsed_response(
+        protocol: :put,
+        path: "#{url}/management/permissions",
+        data: {
+          enabled: enabled
+        }
+      )
+    end
+
+    ##
+    # Returns the client's secret
+
+    def secret
+      Clonk.parsed_response(
+        path: "#{url}/client-secret"
+      )['value']
+    end
+  end
+end

data/lib/clonk/group.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Clonk
+  class Group
+
+    attr_accessor :id
+    attr_reader :name
+
+    def initialize(group_response, realm = REALM)
+      @name = group_response['name']
+      @id = group_response['id']
+      @realm = realm
+    end
+
+    # Gets config inside SSO for group with ID in realm
+    def self.get_config(id, realm = REALM)
+      Clonk.parsed_response(
+        path: "#{Clonk.realm_admin_root(realm)}/groups/#{id}"
+      )
+    end
+
+    def config
+      self.class.get_config(@id, @realm)
+    end
+
+    # Creates a new Group instance from a group that exists in SSO
+    def self.new_from_id(id, realm = REALM)
+      new(get_config(id, realm), realm)
+    end
+
+    # Creates a new group in SSO and casts it to an instance
+    def self.create(name: nil, realm: REALM)
+      new_group = new({ 'name' => name }, realm)
+      response = new_group.save(realm)
+      new_group.id = response.headers[:location].split('/')[-1]
+      new_group
+    end
+
+    def save(realm = REALM)
+      if @id
+        Clonk.parsed_response(
+          protocol: :put,
+          path: "#{Clonk.realm_admin_root(@realm)}/groups/#{@id}",
+          data: config.merge('name' => @name)
+        )
+      else
+        Clonk.response(
+          protocol: :post,
+          path: "#{Clonk.realm_admin_root(realm)}/groups",
+          data: { name: @name }
+        )
+      end
+    end
+
+    def create_subgroup(name: nil)
+      response = Clonk.parsed_response(
+        protocol: :post,
+        path: "#{url}/children",
+        data: { name: name }
+      )
+      self.class.new_from_id(response['id'], @realm)
+    end
+
+    def subgroups
+      config["subGroups"].map { |group| self.class.new_from_id(group['id'], @realm) }
+    end
+
+    def self.all(realm: REALM, flattened: false)
+      response = Clonk.parsed_response(
+        protocol: :get,
+        path: "#{Clonk.realm_admin_root(realm)}/groups",
+      )
+      response += response.map { |group| group['subGroups'] } if flattened
+      response.flatten
+              .map { |group| new_from_id(group['id'], realm) }
+    end
+
+    def self.where(name: nil, realm: REALM)
+      all(flattened: true, realm: realm)
+        .select { |group| group['name'] == name }
+        .map { |group| new_from_id(group['id'], realm) }
+    end
+
+    def self.find_by(name: nil, realm: REALM)
+      where(name: name, realm: realm)&.first
+    end
+
+    def self.find(id: nil, realm: REALM)
+      if all.find { |group| group['id'] == id }
+        new_from_id(id, realm)
+      end
+    end
+
+    def url
+      "#{Clonk.realm_admin_root(@realm)}/groups/#{@id}"
+    end
+
+    def map_role(role: nil)
+      client_path = role.container_id == @realm ? 'realm' : "clients/#{role.container_id}"
+      response = Clonk.parsed_response(
+        protocol: :post,
+        data: [role.config],
+        path: "#{url}/role-mappings/#{client_path}"
+      )
+    end
+
+    def add_user(user: nil, realm: REALM)
+      Clonk.parsed_response(
+        protocol: :put,
+        path: "#{user.url}/groups/#{@id}",
+        data: {
+          groupId: @id,
+          userId: user.id,
+          realm: @realm
+        }
+      )
+    end
+
+    def set_permissions(enabled: true)
+      Clonk.parsed_response(
+        protocol: :put,
+        path: "#{url}/management/permissions",
+        data: {
+          enabled: enabled
+        }
+      )
+    end
+  end
+end

data/lib/clonk/permission.rb

@@ -0,0 +1,82 @@
+module Clonk
+  class Permission
+    def initialize(permission_response, realm)
+      @id = permission_response['id']
+      @realm = realm
+    end
+
+    ##
+    # Returns the API URL for this permission.
+    # Argument is necessary as permissions are sometimes treated as policies
+    # within SSO for some reason, especially when fetching scopes, resources and
+    # policies.
+
+    def url(prefix: 'permission/scope')
+      client_url = Clonk::Client.find_by(realm: @realm, name: 'realm-management').url
+      "#{client_url}/authz/resource-server/#{prefix}/#{@id}"
+    end
+
+    ##
+    # Creates a new Permission instance from a given permission ID and realm.
+
+    def self.new_from_id(id: nil, realm: REALM)
+      client_url = Clonk::Client.find_by(realm: realm, name: 'realm-management').url
+      response = Clonk.parsed_response(
+        path: "#{client_url}/authz/resource-server/permission/scope/#{id}"
+      )
+      new(response, realm)
+    end
+
+    ##
+    # Returns the config within SSO for this permission.
+
+    def config
+      Clonk.parsed_response(
+        path: "#{url}"
+      )
+    end
+
+    ##
+    # Returns the policy IDs associated with this permission.
+
+    def policies
+      Clonk.parsed_response(
+        path: "#{url(prefix: 'policy')}/associatedPolicies"
+      ).map { |policy| policy['id'] }
+    end
+
+    ##
+    # Returns the resource IDs associated with this permission.
+
+    def resources
+      Clonk.parsed_response(
+        path: "#{url(prefix: 'policy')}/resources"
+      ).map { |resource| resource['_id'] }
+    end
+
+    ##
+    # Returns the scope IDs associated with this permission.
+
+    def scopes
+      Clonk.parsed_response(
+        path: "#{url(prefix: 'policy')}/scopes"
+      ).map { |scope| scope['id'] }
+    end
+
+    ##
+    # Adds the given policy/resource/scope IDs to this permission in SSO.
+
+    def update(policies: [], resources: [], scopes: [])
+      data = config.merge(  
+        policies: self.policies + policies,
+        resources: self.resources + resources,
+        scopes: self.scopes + scopes
+       )
+      Clonk.parsed_response(
+        path: url,
+        data: data,
+        protocol: :put
+      )
+    end
+  end
+end

data/lib/clonk/policy.rb

@@ -0,0 +1,81 @@
+module Clonk
+  class Policy
+
+    attr_accessor :id
+    attr_reader :name
+
+    def initialize(policy_response, realm)
+      @id = policy_response['id']
+      @name = policy_response['name']
+      @realm = realm
+    end
+
+    ##
+    # Gets config inside SSO for policy with ID in realm.
+
+    def self.get_config(id, realm = REALM)
+      Clonk.parsed_response(
+        path: "#{Clonk.realm_admin_root(realm)}/clients/#{Clonk::Client.find_by(name: 'realm-management').id}/authz/resource-server/policy/role/#{id}"
+      )
+    end
+
+    ##
+    # Gets config inside SSO for policy.
+
+    def config
+      self.class.get_config(@id, @realm)
+    end
+
+    ##
+    # Creates a new Policy instance from a policy that exists in SSO
+
+    def self.new_from_id(id, realm = REALM)
+      new(get_config(id, realm), realm)
+    end
+
+    ##
+    # Returns defaults for a policy.
+    # I've found no reason to override these, but then again, I'm not 100% sure
+    # how they work. Overrides will be added to necessary methods if requested.
+
+    def self.defaults
+      {
+        logic: 'POSITIVE',
+        decisionStrategy: 'UNANIMOUS'
+      }
+    end
+
+    ##
+    # Returns a policy definition that can then be used to create a policy in SSO.
+    # Only defines role, group and client policies
+    #--
+    # TODO: Expand to allow for other policy types
+    # TODO: Don't assume role as default type
+    #++
+
+    def self.define(type: :role, name: nil, objects: [], description: nil, groups_claim: nil)
+      defaults.merge(
+        type: type,
+        name: name,
+        roles: (objects.map { |role| { id: role.id, required: true } } if type == :role),
+        groups: (objects.map { |group| { id: group.id, extendChildren: false } } if type == :group),
+        groupsClaim: (groups_claim if type == :group),
+        clients: (objects.map { |client| client.id } if type == :client),
+        description: description
+      ).delete_if { |k,v| v.nil?}
+    end
+
+    ##
+    # Defines and creates a policy in SSO.
+
+    def self.create(type: :role, name: nil, objects: [], description: nil, groups_claim: nil, realm: REALM)
+      data = self.define(type: type, name: name, objects: objects, description: description, groups_claim: groups_claim)
+      realm_management_url = Clonk::Client.find_by(name: 'realm-management', realm: realm).url
+      Clonk.parsed_response(
+        protocol: :post,
+        path: "#{realm_management_url}/authz/resource-server/policy/#{type}",
+        data: data
+      )
+    end
+  end
+end

data/lib/clonk/realm.rb

@@ -0,0 +1,52 @@
+module Clonk
+  class Realm
+    def initialize(realm_response)
+      @name = realm_response['id']
+    end
+
+    ##
+    # Creates a realm with the given name, returning it as a Realm object
+    def self.create(name: nil)
+      Clonk.parsed_response(
+        protocol: :post,
+        path: '/auth/admin/realms',
+        data: { id: name, realm: name, enabled: true }
+      )
+      new_from_id(id: name)
+    end
+
+    ##
+    # Returns all realms in this instance of SSO.
+
+    def self.all
+      Clonk.parsed_response(
+        path: '/auth/admin/realms'
+      ).map { |realm| new_from_id(id: realm['id'])}
+    end
+
+    ##
+    # Returns the realm with the given name.
+
+    def self.find_by(name: nil)
+      Clonk.parsed_response(
+        path: "/auth/admin/realms/#{name}"
+      )
+    end
+
+    ##
+    # Gets the config for this realm in SSO.
+
+    def config
+      Clonk.parsed_response(
+        path: "/auth/admin/realms/#{@name}"
+      )
+    end
+
+    ##
+    # Creates a new Realm object from a given realm ID.
+
+    def self.new_from_id(id: nil)
+      new(find_by(name: id))
+    end
+  end
+end

data/lib/clonk/role.rb

@@ -0,0 +1,74 @@
+module Clonk
+  class Role
+    attr_accessor :id
+    attr_accessor :container_id
+    attr_reader :name
+
+    def initialize(role_response, realm)
+      @id = role_response['id']
+      @realm = realm
+      @container_id = role_response['containerId']
+      @name = role_response['name']
+    end
+
+    ##
+    # Returns all roles for the given client. Can also return all roles
+    # applicable to a specific target object.
+    #--
+    # FIXME: target_type should really be inherited from classname of incoming
+    # object
+    #++
+
+    def self.all(client: nil, target: nil, target_type: nil, realm: REALM)
+      # need this to work with realms too
+      case target
+      when nil
+        path = "#{Clonk.realm_admin_root(realm)}/clients/#{client.id}/roles"
+      else
+        path = "#{Clonk.realm_admin_root(realm)}/#{target_type}s/#{target.id}/role-mappings/clients/#{client.id}/available"
+      end
+      Clonk.parsed_response(
+        path: path
+      ).map { |role| new_from_id(role['id'], realm) }
+    end
+
+    ##
+    # Returns all roles with the given name.
+
+    def self.where(client: nil, target: nil, target_type: nil, realm: REALM, name: nil)
+      all(client: client, target: target, target_type: target_type, realm: realm)
+        .select { |role| role.name == name }
+    end
+
+
+    ##
+    # Returns the first role with the given name.
+
+    def self.find_by(client: nil, target: nil, target_type: nil, realm: REALM, name: nil)
+      where(client: client, target: target, target_type: target_type, realm: realm, name: name)&.first
+    end
+
+    ##
+    # Gets config inside SSO for role with ID in realm
+
+    def self.get_config(id, realm = REALM)
+      Clonk.parsed_response(
+        path: "#{Clonk.realm_admin_root(realm)}/roles-by-id/#{id}"
+      )
+    end
+
+    ##
+    # Gets config inside SSO for this role
+
+    def config
+      self.class.get_config(@id, @realm)
+    end
+
+    ##
+    # Creates a new Role instance from a role that exists in SSO
+
+    def self.new_from_id(id, realm = REALM)
+      new(get_config(id, realm), realm)
+    end
+  end
+end

data/lib/clonk/user.rb

@@ -0,0 +1,107 @@
+module Clonk
+  class User
+    attr_accessor :id
+    attr_reader :username
+
+    def initialize(user_response, realm)
+      @username = user_response['username']
+      @id = user_response['id']
+      @realm = realm
+    end
+
+    ##
+    # Gets config inside SSO for user with ID in realm
+
+    def self.get_config(id, realm = REALM)
+      Clonk.parsed_response(
+        path: "#{Clonk.realm_admin_root(realm)}/users/#{id}"
+      )
+    end
+
+    ##
+    # Gets config inside SSO for this user
+
+    def config
+      self.class.get_config(@id, @realm)
+    end
+
+    ##
+    # Creates a new User instance from a user that exists in SSO
+
+    def self.new_from_id(id, realm = REALM)
+      new(get_config(id, realm), realm)
+    end
+
+    ##
+    # Creates a user in SSO, returning a User instance with their ID and
+    # username
+
+    def self.create(realm: REALM, username: nil, enabled: true)
+      response = Clonk.response(protocol: :post,
+                      path: "#{Clonk.realm_admin_root(realm)}/users",
+                      data: { username: username, enabled: enabled }
+                      )
+      self.new_from_id(response.headers[:location].split('/')[-1], realm)
+    end
+
+    ##
+    # Returns all users in the given realm
+
+    def self.all(realm: REALM)
+      Clonk.parsed_response(
+        path: "#{Clonk.realm_admin_root(realm)}/users"
+      ).map { |user| new_from_id(user['id'], realm) }
+    end
+
+    ##
+    # Returns all users in the given realm with the given username
+
+    def self.where(username: nil, realm: REALM)
+      all(realm: realm).select { |user| user.username == username }
+    end
+
+    ##
+    # returns a user in the given realm with the given username
+
+    def self.find_by(username: nil, realm: REALM)
+      where(username: username, realm: realm)&.first
+    end
+
+    ##
+    # Returns the API URL from which the user is accessible.
+
+    def url
+      "#{Clonk.realm_admin_root(@realm)}/users/#{@id}"
+    end
+
+    ##
+    # Maps a role to a user.
+
+    def map_role(role: nil)
+      client_path = role.container_id == @realm ? 'realm' : "clients/#{role.container_id}"
+      response = Clonk.parsed_response(
+        protocol: :post,
+        data: [role.config],
+        path: "#{url}/role-mappings/#{client_path}"
+      )
+    end
+
+    ##
+    # Sets the user's password.
+    #--
+    # FIXME: Currently always a permanent password Make that temporary flag do things.
+    #++
+
+    def set_password(password: nil, temporary: false)
+      Clonk.parsed_response(
+        protocol: :put,
+        data: {
+          type: 'password',
+          value: password,
+          temporary: false
+        },
+        path: "#{url}/reset-password"
+      )
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clonk
 version: !ruby/object:Gem::Version
-  version: 1.0.0alpha3
+  version: 1.0.0alpha4
 platform: ruby
 authors:
 - Simon Fish
@@ -44,8 +44,23 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardoc/checksums"
+- ".yardoc/complete"
+- ".yardoc/object_types"
+- ".yardoc/objects/root.dat"
+- ".yardoc/proxy_types"
 - Gemfile
+- Gemfile.lock
+- README.md
+- clonk.gemspec
 - lib/clonk.rb
+- lib/clonk/client.rb
+- lib/clonk/group.rb
+- lib/clonk/permission.rb
+- lib/clonk/policy.rb
+- lib/clonk/realm.rb
+- lib/clonk/role.rb
+- lib/clonk/user.rb
 homepage: 
 licenses: []
 metadata:
@@ -53,7 +68,15 @@ metadata:
 post_install_message: 
 rdoc_options: []
 require_paths:
-- lib
+- lib/clonk.rb
+- lib/clonk
+- lib/clonk/realm.rb
+- lib/clonk/group.rb
+- lib/clonk/policy.rb
+- lib/clonk/role.rb
+- lib/clonk/client.rb
+- lib/clonk/permission.rb
+- lib/clonk/user.rb
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="