Skip to content

identity.md

Latest commit

 

History

History
382 lines (271 loc) · 7.47 KB

identity.md

File metadata and controls

382 lines (271 loc) · 7.47 KB

Identity

This document shows you the identity service (or user management) available with fog-proxmox.

Proxmox supports many authentication sources (PAM, LDAP, Active Directory) and an authorization management (ACL, privileges).

You can see more details in Proxmox user management wiki page

Starting irb console

irb
require 'fog/proxmox'

Create identity service

with access ticket:

identity = Fog::Proxmox::Identity.new(
	proxmox_url: 'https://localhost:8006/api2/json', 
	proxmox_auth_method: 'access_ticket', 
	proxmox_username: 'your_user@your_realm', 
	proxmox_password: 'his_password',
	connection_options: { ... }
)

with API user token:

identity = Fog::Proxmox::Identity.new(
	proxmox_url: 'https://localhost:8006/api2/json', 
	proxmox_auth_method: 'user_token', 
	proxmox_userid: 'your_user@your_realm', 
	proxmox_tokenid: 'his_tokenid',
	proxmox_token: 'his_token',
	connection_options: { ... }
)

connection_options are also available and optional.

Fog Abstractions

Fog provides both a model and request abstraction. The request abstraction provides the most efficient interface and the model abstraction wraps the request abstraction to provide a convenient ActiveModel like interface.

Request Layer

The request abstraction maps directly to the Proxmox VE API. It provides an interface to the Proxmox Identity service.

To see a list of requests supported by the identity service:

identity.requests

To learn more about Identity request methods refer to source files.

To learn more about Excon refer to Excon GitHub repo.

Model Layer

Fog models behave in a manner similar to ActiveModel. Models will generally respond to create, save, persisted?, destroy, reload and attributes methods. Additionally, fog will automatically create attribute accessors.

Here is a summary of common model methods:

Method Description
create Accepts hash of attributes and creates object.
Note: creation is a non-blocking call and you will be required to wait for a valid state before using resulting object.
update Updates object.
Note: not all objects support updating object.
destroy Destroys object.
Note: this is a non-blocking call and object deletion might not be instantaneous.
attributes Returns a hash containing the list of model attributes and values.
identity Returns the identity of the object.
Note: This might not always be equal to object.id.

The remainder of this document details the model abstraction.

Users management

List all users:

identity.users.all

This returns a collection of Fog::Proxmox::Identity::User models:

Create a user:

identity.users.create({
    userid: 'bobsinclar@pve',
    password: 'bobsinclar1',
    firstname: 'Bob',
    lastname: 'Sinclar',
    email: 'bobsinclar@proxmox.com'
})

Get a user:

user = identity.users.find_by_id 'bobsinclar@pve'

Change his password:

user.password = 'bobsinclar2'
user.change_password

Add groups to user:

user.groups = %w[group1 group2]
user.update

Delete user:

user.destroy

Groups management

Proxmox supports permissions management by group.

Proxmox recommends to manage permissions by group instead of by user.

List all groups:

identity.groups.all

This returns a collection of Fog::Proxmox::Identity::Group models:

Create a group:

identity.groups.create({
    groupid: 'group1'
})

Get a group:

group = identity.groups.find_by_id 'group1'

Add a comment:

group.comment = 'Group 1'
group.update

Delete group:

group.destroy

Domains management

Proxmox supports 4 domains or realms (sources of authentication): PAM, PVE, LDAP and Active Directory.

Proxmox server has two default domains: PAM and PVE.

List all domains:

identity.domains.all

This returns a collection of Fog::Proxmox::Identity::Domain models:

Create a LDAP domain:

identity.domains.create({
        realm: 'LDAP',
        type: 'ldap',
        base_dn: 'ou=People,dc=ldap-test,dc=com',
        user_attr: 'LDAP',
        server1: 'localhost',
        port: 389,
        default: 0,
        secure: 0
      })

Get a domain:

ldap = identity.domains.find_by_id 'LDAP'

Add a comment and a two factor authentication (OATH) to LDAP realm:

ldap.type.comment = 'Test domain LDAP'
ldap.type.tfa = 'type=oath,step=30,digits=8'
ldap.update

Delete domain:

ldap.destroy

Roles management

Proxmox supports roles management to give permissions to group of users.

Proxmox server has several defaults roles already created. See Proxmox user management wiki page

List all roles:

identity.roles.all

This returns a collection of Fog::Proxmox::Identity::Role models:

Create a new role:

identity.roles.create({ roleid: 'PVETestAuditor' })

Get the role:

role = identity.groups.find_by_id 'PVETestAuditor'

Add privileges to this new role:

role.privs = 'Datastore.Audit Sys.Audit VM.Audit'
role.update

List of all available privileges can be seen at Proxmox user management wiki page

Delete role:

role.destroy

Permissions management

Proxmox supports permissions management. Access permissions are assigned to objects, such as a virtual machines, storages or pools of resources. It uses path to identify these objects. Path is the same as REST API path.

See more details in Proxmox user management wiki page

List all permissions:

identity.permissions.all

This returns a collection of Fog::Proxmox::Identity::Permission models:

Add a new permission (manage users) to a user:

identity.permissions.add({
    path: '/access/users',
    roles: 'PVEUserAdmin',
    users: 'bobsinclar@pve'
})

Add a new permission (manage users) to a group of users:

identity.permissions.add({
    path: '/access/users',
    roles: 'PVEUserAdmin',
    groups: 'group1'
})

Remove a permission to a user:

identity.permissions.remove({
    path: '/access/users',
    roles: 'PVEUserAdmin',
    users: 'bobsinclar@pve'
})

User permissions:

bob = identity.users.get 'bobsinclar@pve'
bob.permissions

Pools management

Proxmox supports pools management of VMs or storages. It eases managing permissions on these.

Create a pool:

identity.pools.create { poolid: 'pool1' }

Get a pool:

pool1 = identity.pools.find_by_id 'pool1'

Add comment, server 100 and storage local-lvm to the pool:

pool1.comment = 'Pool 1'
pool1.update
pool1.add_server 100
pool1.add_storage 'local-lvm '

Get all pools:

identity.pools.all

Delete pool:

# you need to remove all members before deleting pool
pool1.remove_server 100
pool1.remove_storage 'local-lvm '
pool1.destroy

Examples

More examples can be seen at examples/identity.rb or spec/identity_spec.rb.