Documentation
¶
Overview ¶
Package ipa is a Go client for the FreeIPA JSON-RPC API. It is a maintained continuation of github.com/ubccr/goipa.
A Client logs in with a password (Login for Kerberos, RemoteLogin for the web API), a keytab (LoginWithKeytab), a credentials cache (LoginFromCCache), or an existing session (NewDefaultClientWithSession, SetSessionID). A *Client is safe for concurrent use.
A FreeIPA error is returned as a bare *IpaError: match it with errors.Is against ErrNotFound and the other sentinels, or with a type assertion.
Every method that talks to the server has a ...Context twin that bounds the request with a context, except Login, LoginWithKeytab and LoginFromCCache (gokrb5 is not cancellable). RPC calls any command goipa does not wrap.
Index ¶
- Constants
- Variables
- func ParseDateTime(str string) time.Time
- type Client
- func (c *Client) AddOTPToken(token *OTPToken) (*OTPToken, error)
- func (c *Client) AddOTPTokenContext(ctx context.Context, token *OTPToken) (*OTPToken, error)
- func (c *Client) ChangePassword(username, oldPasswd, newPasswd, otpcode string) error
- func (c *Client) ChangePasswordContext(ctx context.Context, username, oldPasswd, newPasswd, otpcode string) error
- func (c *Client) ClearSession()
- func (c *Client) DisableOTPToken(tokenUUID string) error
- func (c *Client) DisableOTPTokenContext(ctx context.Context, tokenUUID string) error
- func (c *Client) EnableOTPToken(tokenUUID string) error
- func (c *Client) EnableOTPTokenContext(ctx context.Context, tokenUUID string) error
- func (c *Client) FetchOTPTokens(owner string) ([]*OTPToken, error)
- func (c *Client) FetchOTPTokensContext(ctx context.Context, owner string) ([]*OTPToken, error)
- func (c *Client) Host() string
- func (c *Client) Login(username, password string) error
- func (c *Client) LoginFromCCache(cpath string) error
- func (c *Client) LoginWithKeytab(ktab, username string) error
- func (c *Client) Ping() (*Response, error)
- func (c *Client) PingContext(ctx context.Context) (*Response, error)
- func (c *Client) RPC(method string, args []string, options Options) (*Response, error)
- func (c *Client) RPCContext(ctx context.Context, method string, args []string, options Options) (*Response, error)
- func (c *Client) Realm() string
- func (c *Client) RemoteLogin(uid, passwd string) error
- func (c *Client) RemoteLoginContext(ctx context.Context, uid, passwd string) error
- func (c *Client) RemoveOTPToken(tokenUUID string) error
- func (c *Client) RemoveOTPTokenContext(ctx context.Context, tokenUUID string) error
- func (c *Client) ResetPassword(username string) (string, error)
- func (c *Client) ResetPasswordContext(ctx context.Context, username string) (string, error)
- func (c *Client) SessionID() string
- func (c *Client) SetAuthTypes(username string, types []string) error
- func (c *Client) SetAuthTypesContext(ctx context.Context, username string, types []string) error
- func (c *Client) SetPassword(username, oldPasswd, newPasswd, otpcode string) error
- func (c *Client) SetPasswordContext(ctx context.Context, username, oldPasswd, newPasswd, otpcode string) error
- func (c *Client) SetSessionID(sessionID string)
- func (c *Client) StickySession(enable bool)
- func (c *Client) UserAdd(user *User, random bool) (*User, error)
- func (c *Client) UserAddContext(ctx context.Context, user *User, random bool) (*User, error)
- func (c *Client) UserAddWithPassword(user *User, password string) (*User, error)
- func (c *Client) UserAddWithPasswordContext(ctx context.Context, user *User, password string) (*User, error)
- func (c *Client) UserDelete(preserve, stopOnError bool, usernames ...string) error
- func (c *Client) UserDeleteContext(ctx context.Context, preserve, stopOnError bool, usernames ...string) error
- func (c *Client) UserDisable(username string) error
- func (c *Client) UserDisableContext(ctx context.Context, username string) error
- func (c *Client) UserEnable(username string) error
- func (c *Client) UserEnableContext(ctx context.Context, username string) error
- func (c *Client) UserFind(options Options) ([]*User, error)
- func (c *Client) UserFindContext(ctx context.Context, options Options) ([]*User, error)
- func (c *Client) UserMod(user *User) (*User, error)
- func (c *Client) UserModContext(ctx context.Context, user *User) (*User, error)
- func (c *Client) UserShow(username string) (*User, error)
- func (c *Client) UserShowContext(ctx context.Context, username string) (*User, error)
- type HTTPError
- type IpaError
- type Message
- type OTPToken
- type Options
- type Response
- type Result
- type SSHAuthorizedKey
- type User
Constants ¶
const ( CodeVersion = 901 CodeCommand = 905 CodeReferer = 911 CodeACI = 2100 CodeRequirement = 3007 CodeValidation = 3009 CodeNotFound = 4001 CodeDuplicateEntry = 4002 CodeAlreadyActive = 4009 CodeAlreadyInactive = 4010 CodeNotGroupMember = 4012 CodeAlreadyGroupMember = 4014 CodeAttrValueNotFound = 4026 CodeAlreadyContainsValue = 4038 CodeEmptyModlist = 4202 CodeDatabase = 4203 )
FreeIPA error codes (ipalib.errors).
const ( DefaultKerbConf = "/etc/krb5.conf" IpaClientVersion = "2.237" IpaDatetimeFormat = "20060102150405Z" )
const ( AlgorithmSHA1 = "sha1" AlgorithmSHA256 = "sha256" AlgorithmSHA384 = "sha384" AlgorithmSHA512 = "sha512" )
OTP Token hash Algorithms supported by FreeIPA
const ( TokenTypeTOTP = "totp" TokenTypeHOTP = "hotp" )
OTP Token types supported by FreeIPA
Variables ¶
var ( ErrNotFound = &IpaError{Code: CodeNotFound, Name: "NotFound", Message: "not found"} ErrDuplicateEntry = &IpaError{Code: CodeDuplicateEntry, Name: "DuplicateEntry", Message: "entry already exists"} ErrACI = &IpaError{Code: CodeACI, Name: "ACIError", Message: "insufficient access"} ErrEmptyModlist = &IpaError{Code: CodeEmptyModlist, Name: "EmptyModlist", Message: "no modifications to be performed"} )
Sentinels for common FreeIPA errors. They are matched with errors.Is by code only; any other code is available through errors.As and IpaError.Code.
var ( // ErrPasswordPolicy is returned when a password does not conform to the password policy ErrPasswordPolicy = errors.New("password does not conform to policy") // ErrInvalidPassword is returned when a password is invalid ErrInvalidPassword = errors.New("invalid current password") // ErrExpiredPassword is returned when a password is expired ErrExpiredPassword = errors.New("password expired") ErrUnauthorized = errors.New("unauthorized") // ErrUserExists is returned when user account already exists. UserAdd // returns it for FreeIPA's DuplicateEntry (4002). ErrUserExists = errors.New("user exists") )
Functions ¶
func ParseDateTime ¶
Parse a FreeIPA datetime. Datetimes in FreeIPA are returned using a class-hint system. Values are stored as an array with a single element indicating the type and value, for example, '[{"__datetime__": "YYYY-MM-DDTHH:MM:SSZ"]}'
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
FreeIPA Client
Methods with a Context suffix bound the HTTP request with the given context. Kerberos login and SPNEGO header generation are not cancellable (gokrb5 has no context support), so Login, LoginWithKeytab and LoginFromCCache have no Context twins.
func NewClientCustomHttp ¶
New IPA Client with host, realm and custom http client
func NewDefaultClient ¶
func NewDefaultClient() *Client
New default IPA Client using host and realm from /etc/ipa/default.conf
func NewDefaultClientWithSession ¶
New default IPA Client with existing sessionID using host and realm from /etc/ipa/default.conf
func (*Client) AddOTPToken ¶
Add OTP token. Returns new OTPToken
func (*Client) AddOTPTokenContext ¶ added in v0.2.0
AddOTPTokenContext is like AddOTPToken but bounds the request with ctx.
func (*Client) ChangePassword ¶
Change user password. This will run the passwd ipa command. Optionally provide an OTP if required
func (*Client) ChangePasswordContext ¶ added in v0.2.0
func (c *Client) ChangePasswordContext(ctx context.Context, username, oldPasswd, newPasswd, otpcode string) error
ChangePasswordContext is like ChangePassword but bounds the request with ctx.
func (*Client) DisableOTPToken ¶
Disable OTP token.
func (*Client) DisableOTPTokenContext ¶ added in v0.2.0
DisableOTPTokenContext is like DisableOTPToken but bounds the request with ctx.
func (*Client) EnableOTPToken ¶
Enable OTP token.
func (*Client) EnableOTPTokenContext ¶ added in v0.2.0
EnableOTPTokenContext is like EnableOTPToken but bounds the request with ctx.
func (*Client) FetchOTPTokens ¶
Fetch OTP tokens by owner.
func (*Client) FetchOTPTokensContext ¶ added in v0.2.0
FetchOTPTokensContext is like FetchOTPTokens but bounds the request with ctx.
func (*Client) LoginFromCCache ¶
Login to FreeIPA using credentials cache
func (*Client) LoginWithKeytab ¶
Login to FreeIPA using local kerberos login with keytab and username
func (*Client) PingContext ¶ added in v0.2.0
PingContext is like Ping but bounds the request with ctx.
func (*Client) RPC ¶ added in v0.2.0
RPC calls any FreeIPA command, an escape hatch for commands goipa does not wrap. It uses the client's HTTP client, session or Kerberos credentials and API version. A FreeIPA failure is returned as a bare *IpaError. options is not modified; a "version" in options wins over IpaClientVersion.
func (*Client) RPCContext ¶ added in v0.2.0
func (c *Client) RPCContext(ctx context.Context, method string, args []string, options Options) (*Response, error)
RPCContext is like RPC but ends the request when ctx is done.
func (*Client) RemoteLogin ¶
Login to FreeIPA using web API with uid/passwd and set the FreeIPA session id on the client for subsequent requests.
func (*Client) RemoteLoginContext ¶ added in v0.2.0
RemoteLoginContext is like RemoteLogin but bounds the request with ctx.
func (*Client) RemoveOTPToken ¶
Remove OTP token
func (*Client) RemoveOTPTokenContext ¶ added in v0.2.0
RemoveOTPTokenContext is like RemoveOTPToken but bounds the request with ctx.
func (*Client) ResetPassword ¶
Reset user password and return new random password
func (*Client) ResetPasswordContext ¶ added in v0.2.0
ResetPasswordContext is like ResetPassword but bounds the request with ctx.
func (*Client) SetAuthTypes ¶
Update user authentication types.
func (*Client) SetAuthTypesContext ¶ added in v0.2.0
SetAuthTypesContext is like SetAuthTypes but bounds the request with ctx.
func (*Client) SetPassword ¶
Set user password. In FreeIPA when a password is first set or when a password is later reset it is marked as immediately expired and requires the owner to perform a password change. See here https://www.freeipa.org/page/New_Passwords_Expired for more details. This function exists to circumvent the "new passwords expired" feature of FreeIPA and allow an administrator to set a new password for a user without it being expired. This is acheived, for example, by first calling ResetPassword() then immediately calling this function. *WARNING* See https://www.freeipa.org/page/Self-Service_Password_Reset for security issues and possible weaknesses of this approach.
func (*Client) SetPasswordContext ¶ added in v0.2.0
func (c *Client) SetPasswordContext(ctx context.Context, username, oldPasswd, newPasswd, otpcode string) error
SetPasswordContext is like SetPassword but bounds the request with ctx.
func (*Client) SetSessionID ¶ added in v0.2.0
SetSessionID restores a session saved from SessionID (for example in a web session store) on any client. An empty string clears it.
func (*Client) UserAdd ¶
Add new user. If random is true a random password will be created for the user. Note this requires "User Administrators" Privilege in FreeIPA.
func (*Client) UserAddContext ¶ added in v0.2.0
UserAddContext is like UserAdd but bounds the request with ctx.
func (*Client) UserAddWithPassword ¶
Add new user and set password. Note this requires "User Administrators" Privilege in FreeIPA.
func (*Client) UserAddWithPasswordContext ¶ added in v0.2.0
func (c *Client) UserAddWithPasswordContext(ctx context.Context, user *User, password string) (*User, error)
UserAddWithPasswordContext is like UserAddWithPassword but bounds the request with ctx.
func (*Client) UserDelete ¶
Delete user. If preserve is false the user will be permanetly deleted, if true the users is moved to the Delete container. If stopOnError is false the operation will be in continuous mode otherwise it will stop on errors
func (*Client) UserDeleteContext ¶ added in v0.2.0
func (c *Client) UserDeleteContext(ctx context.Context, preserve, stopOnError bool, usernames ...string) error
UserDeleteContext is like UserDelete but bounds the request with ctx.
func (*Client) UserDisable ¶
Disable User Account
func (*Client) UserDisableContext ¶ added in v0.2.0
UserDisableContext is like UserDisable but bounds the request with ctx.
func (*Client) UserEnableContext ¶ added in v0.2.0
UserEnableContext is like UserEnable but bounds the request with ctx.
func (*Client) UserFindContext ¶ added in v0.2.0
UserFindContext is like UserFind but bounds the request with ctx.
func (*Client) UserMod ¶
Modify user. Currently only modifies a subset of user attributes: mail, givenname, sn, homedirectory, loginshell, displayname, ipasshpubkey, telephonenumber, and mobile
func (*Client) UserModContext ¶ added in v0.2.0
UserModContext is like UserMod but bounds the request with ctx.
type HTTPError ¶ added in v0.2.0
HTTPError is returned when the server answers a JSON-RPC call with a status other than 200. HTTP 401 (for example an expired session) also matches ErrUnauthorized with errors.Is.
type IpaError ¶
type IpaError struct {
Message string
Code int
Name string `json:"name"`
// Data is the raw JSON of the exception's keyword arguments, e.g.
// {"reason":"..."}. A string so IpaError stays comparable.
Data string `json:"data"`
}
FreeIPA error
func (*IpaError) UnmarshalJSON ¶ added in v0.2.0
UnmarshalJSON keeps Data as raw JSON text; Message and Code still match the "message" and "code" keys case-insensitively.
type Message ¶ added in v0.2.0
type Message struct {
Type string `json:"type"`
Name string `json:"name"`
Message string `json:"message"`
Code int `json:"code"`
Data json.RawMessage `json:"data"`
}
Message is a server warning attached to a FreeIPA result.
type OTPToken ¶
type OTPToken struct {
DN string `json:"dn"`
UUID string `json:"ipatokenuniqueid"`
Algorithm string `json:"ipatokenotpalgorithm"`
Digits int `json:"ipatokenotpdigits"`
Owner string `json:"ipatokenowner"`
TimeStep int `json:"ipatokentotptimestep"`
ClockOffest int `json:"ipatokentotpclockoffset"`
ManagedBy string `json:"managedby_user"`
Enabled bool `json:"-"`
Type string `json:"type"`
URI string `json:"uri"`
Description string `json:"description"`
Vendor string `json:"ipatokenvendor"`
Model string `json:"ipatokenmodel"`
Serial string `json:"ipatokenserial"`
NotBefore time.Time `json:"ipatokennotbefore"`
NotAfter time.Time `json:"ipatokennotafter"`
}
OTPToken encapsulates FreeIPA otptokens
var DefaultTOTPToken *OTPToken = &OTPToken{ Type: TokenTypeTOTP, Algorithm: AlgorithmSHA1, Digits: 6, TimeStep: 30, }
func (*OTPToken) DisplayName ¶
type Response ¶
type Response struct {
Error *IpaError `json:"error"`
ID int `json:"id"`
Principal string `json:"principal"`
Version string `json:"version"`
Result *Result `json:"result"`
}
Response returned from a FreeIPA JSON rpc call
type Result ¶
type Result struct {
Summary string `json:"summary"`
Value interface{} `json:"value"`
Data json.RawMessage `json:"result"`
Count int `json:"count"`
Truncated bool `json:"truncated"`
Messages []Message `json:"messages"`
Completed int `json:"completed"`
Failed json.RawMessage `json:"failed"`
// Raw is the whole FreeIPA result object, for shapes without a "result"
// key such as hbactest.
Raw json.RawMessage `json:"-"`
}
Result returned from a FreeIPA JSON rpc call
func (*Result) UnmarshalJSON ¶ added in v0.2.0
UnmarshalJSON decodes the result and keeps a copy of the raw object in Raw.
type SSHAuthorizedKey ¶
type SSHAuthorizedKey struct {
Comment string
Options []string
PublicKey ssh.PublicKey
Fingerprint string
}
SSH Public Key
func NewSSHAuthorizedKey ¶
func NewSSHAuthorizedKey(in string) (*SSHAuthorizedKey, error)
func (*SSHAuthorizedKey) MarshalJSON ¶
func (k *SSHAuthorizedKey) MarshalJSON() ([]byte, error)
func (*SSHAuthorizedKey) String ¶
func (k *SSHAuthorizedKey) String() string
type User ¶
type User struct {
UUID string `json:"ipauniqueid"`
DN string `json:"dn"`
First string `json:"givenname"`
Last string `json:"sn"`
DisplayName string `json:"displayname"`
Principal string `json:"krbprincipalname"`
Username string `json:"uid"`
Uid string `json:"uidnumber"`
Gid string `json:"gidnumber"`
Groups []string `json:"memberof_group"`
SSHAuthKeys []*SSHAuthorizedKey `json:"ipasshpubkey"`
AuthTypes []string `json:"ipauserauthtype"`
HasKeytab bool `json:"has_keytab"`
HasPassword bool `json:"has_password"`
Locked bool `json:"nsaccountlock"`
Preserved bool `json:"preserved"`
HomeDir string `json:"homedirectory"`
Email string `json:"mail"`
TelephoneNumber string `json:"telephonenumber"`
Mobile string `json:"mobile"`
Shell string `json:"loginshell"`
Category string `json:"userclass"`
SudoRules []string `json:"memberofindirect_sudorule"`
HbacRules []string `json:"memberofindirect_hbacrule"`
LastPasswdChange time.Time `json:"krblastpwdchange"`
PasswdExpire time.Time `json:"krbpasswordexpiration"`
PrincipalExpire time.Time `json:"krbprincipalexpiration"`
LastLoginSuccess time.Time `json:"krblastsuccessfulauth"`
LastLoginFail time.Time `json:"krblastfailedauth"`
RandomPassword string `json:"randompassword"`
}
User encapsulates user data returned from ipa user commands
func (*User) AddSSHAuthorizedKey ¶
func (u *User) AddSSHAuthorizedKey(key *SSHAuthorizedKey)
Add ssh authorized key
func (*User) FormatSSHAuthorizedKeys ¶
Format ssh authorized keys
func (*User) RemoveSSHAuthorizedKey ¶
Removes ssh authorized key