oVirt LDAP authentication and authorization extension
=====================================================
Generic LDAP implementation for oVirt engine.
QUICK START
-----------
USING INSTALLER
Install ovirt-engine-extension-aaa-ldap-setup and execute:
# ovirt-engine-extension-aaa-ldap-setup
The setup will guide you throughout the process of most common use cases.
USING CONFIGURATION FILES
Examples are available at the following directory:
/usr/share/ovirt-engine-extension-aaa-ldap*/examples
Content is relative to /etc/ovirt-engine directory.
1. Per your setup, copy recursive examples/ad/. (Active Directory) or
examples/simple/. to /etc/ovirt-engine, optionally modify the profile1
within the file names and profile1 within the content to a value
that suites your environment.
2. Customize the vars.* variables within files to meet your setup.
3. Test drive your configuration
oVirt 3.6/4.x
-------------
Test drive can be done as standalone process.
a. Test login:
Execute:
# ovirt-engine-extensions-tool aaa login-user \
--profile=@PROFILE@ --user-name=@USER@
Replace:
- @PROFILE@ with authn ovirt.engine.aaa.authn.profile.name.
- @USER@ with user you want to test.
Inspect output for initialization errors.
Inspect PrincipalRecord and GroupRecord within the output and verify it
matches expectations.
b. Test search:
Search by executing:
# ovirt-engine-extensions-tool aaa search --extension-name=@AUTHZ@ \
--entity=@ENTITY@ --entity-name=@NAME@
Optionally add the following to enable group resolution:
--authz-flag=resolve-groups --authz-flag=resolve-groups-recursive
Replace:
- @AUTHZ@ with authz extension name.
- @ENTITY@ with either 'principal' or 'group'.
- @NAME@ with requested name to search.
Inspect output for initialization errors.
Inspect PrincipalRecord and GroupRecord within the output and verify it
matches expectations.
c. Restart ovirt-engine, verify no startup errors.
oVirt 3.5
---------
a. Restart ovirt-engine, verify no startup errors.
b. Within ovirt-engine try to search for users, add a user and assign
SuperUser system roles.
c. Try to login using the newly added user.
4. Complete customization of profile, such as enabling startTLS.
IMPLEMENTATION NOTES
--------------------
Implementation uses UnboundID LDAP SDK for Java. Many of the terms and
configuration options derived from the SDK terms. More information can
be found at UnboundID site[1].
Refer to README.unboundid-ldapsdk for known issues and limitations.
[1] https://www.ldap.com/unboundid-ldap-sdk-for-java
EXTENSION CONFIGURATION
-----------------------
AUTHZ
Configure authorization extension.
/etc/ovirt-engine/extensions.d/@[email protected]
ovirt.engine.extension.name = @AUTHZ_NAME@
ovirt.engine.extension.bindings.method = jbossmodule
ovirt.engine.extension.binding.jbossmodule.module = org.ovirt.engine-extensions.aaa.ldap
ovirt.engine.extension.binding.jbossmodule.class = org.ovirt.engineextensions.aaa.ldap.AuthzExtension
ovirt.engine.extension.provides = org.ovirt.engine.api.extensions.aaa.Authz
config.profile.file.1 = @PROFILE_CONFIGURATION@
@AUTHZ_NAME@
Extension instance name.
@PROFILE@
Profile name, visible to user.
@PROFILE_CONFIGURATION@
Profile configuration file, may be relative to extension configuration.
AUTHN
Configure authentication extension.
/etc/ovirt-engine/extensions.d/@[email protected]
ovirt.engine.extension.name = @AUTHN_NAME@
ovirt.engine.extension.bindings.method = jbossmodule
ovirt.engine.extension.binding.jbossmodule.module = org.ovirt.engine-extensions.aaa.ldap
ovirt.engine.extension.binding.jbossmodule.class = org.ovirt.engineextensions.aaa.ldap.AuthnExtension
ovirt.engine.extension.provides = org.ovirt.engine.api.extensions.aaa.Authn
ovirt.engine.aaa.authn.profile.name = @PROFILE@
ovirt.engine.aaa.authn.authz.plugin = @AUTHZ_NAME@
config.profile.file.1 = @PROFILE_CONFIGURATION@
@AUTHN_NAME@
Extension instance name.
@AUTHZ_NAME@
Authz extension instance name.
@PROFILE@
Profile name, visible to user.
@PROFILE_CONFIGURATION@
Profile configuration file, may be relative to extension configuration.
REMOVING CONFIGURED PROFILE
---------------------------
Following steps describe how to remove a configured LDAP profile (profile name
'profile1' is assumed in commands, please adapt to profile name that should be
removed):
1. Remove profile configuration files
rm /etc/ovirt-engine/extensions.d/profile1-authn.properties
rm /etc/ovirt-engine/extensions.d/profile1-authz.properties
rm /etc/ovirt-engine/aaa/profile1.properties
2. Restart ovirt-engine
systemctl restart ovirt-engine
Note:
The above steps will remove profile configuration, so users from this
profile will no longer be able to login into engine. But those users still
have permissions defined in engine, so if you want to remove those
permissions you need to do following:
1. Login into webadmin and switch to Users tab
2. Remove all users from the provider you have removed above (they should
have their Authorization provider set to 'profile1-authz'
PROFILE CONFIGURATION EXAMPLES
------------------------------
OPENLDAP/389DS/IPA/...
Using simple bind transport using startTLS:
# select one
include = <openldap.properties>
#include = <389ds.properties>
#include = <rhds.properties>
#include = <ipa.properties>
#include = <iplanet.properties>
#include = <rfc2307-generic.properties>
#include = <rfc2307-389ds.properties>
#include = <rfc2307-rhds.properties>
#include = <rfc2307-openldap.properties>
#include = <rfc2307-edir.properties>
vars.server = ldap1.company.com
vars.user = uid=search,cn=users,cn=accounts,dc=company,dc=com
vars.password = 123456
pool.default.serverset.single.server = ${global:vars.server}
pool.default.auth.simple.bindDN = ${global:vars.user}
pool.default.auth.simple.password = ${global:vars.password}
pool.default.ssl.startTLS = true
pool.default.ssl.truststore.file = ${local:_basedir}/${global:vars.server}.jks
pool.default.ssl.truststore.password = changeit
Round robin configuration:
pool.default.serverset.type = round-robin
pool.default.serverset.round-robin.1.server = ${global:vars.server1}
pool.default.serverset.round-robin.2.server = ${global:vars.server2}
In case sasl mechanism is used, such as gssapi, set the following within
extension configuration:
# Except of active directory
config.globals.bindFormat.simple_bindFormat = realm
More supported configuration at README.profile.
ACTIVE DIRECTORY
Active Directory 2003 R2 and above is supported.
Using simple bind transport using startTLS. Unfortunately, SASL does not
provide bind failure reasons.
User name is the userPrincipalName field of the user, the suffix is usually the
domain name.
Connect to Domain Controller DNS Server directly, use SRV record to
resolve hosts.
include = <ad.properties>
vars.forest = company.com
vars.user = search@${global:vars.forest}
vars.password = 123456
vars.dns = dns://dc1.${global:vars.forest} dns://dc2.${global:vars.forest}
pool.default.serverset.type = srvrecord
pool.default.serverset.srvrecord.domain = ${global:vars.forest}
pool.default.auth.simple.bindDN = ${global:vars.user}
pool.default.auth.simple.password = ${global:vars.password}
pool.default.serverset.srvrecord.jndi-properties.java.naming.provider.url = ${global:vars.dns}
pool.default.socketfactory.resolver.uRL = ${global:vars.dns}
pool.default.ssl.startTLS = true
pool.default.ssl.truststore.file = ${local:_basedir}/${global:vars.forest}.jks
pool.default.ssl.truststore.password = changeit
More supported configuration at README.profile.
Single Sign-On for Virtual Machines
-----------------------------------
If you are going to use Single Sign-On for Virtual Machines, your authz name
has to match your real domain name.
If you are going to use ovirt-engine-extension-aaa-ldap-setup, you will be
asked to support Single Sign-On for Virtual Machines or not. So generated
configuration files will be created upon answer to that question.
If you are going to create your configuration files manually, please beware
that by default authz name is specified with '-authz' suffix in all examples,
so please make sure to correct it in your final configuration file.
Once rhbz#1133137 is resolved, this behaviour would not be longer needed.
X.509 CERTIFICATE TRUST STORE
-----------------------------
When using TLS/SSL to communicate with LDAP server an X.509 certificate
trust store should be provided if the certificate of the LDAP server is
not signed by well known certification authority.
The trust store can be anything Java supports, by default it is
JKS (Java Key Store) format.
Use the following command to create a JKS myrootca.jks trust store using
password 'changeit' and import the certificate myrootca.pem into
alias myrootca:
$ keytool -importcert -noprompt -trustcacerts -alias myrootca \
-file myrootca.pem -keystore myrootca.jks -storepass changeit
The root certificate should be obtained from the LDAP server, exact
method is vendor specific.
OpenLDAP
Open /etc/openldap/slapd.conf
Seek TLSCACertificateFile or TLSCACertificatePath.
Locate certificate file.
FreeIPA
/etc/ipa/ca.crt
Active Directory
Windows: > certutil -ca.cert myrootca.der
Linux: $ openssl -in myrootca.der -inform DER -out myrootca.pem
Most LDAP servers will provide root certificate within TLS/SSL negotiation.
Use the following sequence to extract:
$ openssl s_client -connect @HOST@:636 -showcerts < /dev/null
Copy/paste the last certificate into myrootca.pem
Copy/paste the first certificate into end.pem
Check if it is a root certificate:
$ openssl verify -CAfile myrootca.pem end.pem
APACHE SSO CONFIGURATION
------------------------
Authorization extension can be used in an environment in which apache
preforms the authentication, common example is kerberos. Use the
ovirt-engine-extension-aaa-misc and configure the http authentication
extension to acquire principal name out of the request.
APACHE CONFIGURATION
The following example enforces kerberos authentication, and delegate
principal name via HTTP headers. The actual kerberos configuration is
out of scope for this document.
oVirt 3.x
---------
# mod_auth_kerb module has to be enabled and loaded
<LocationMatch ^(/ovirt-engine/(webadmin|userportal|api)|/api)>
RewriteEngine on
RewriteCond %{LA-U:REMOTE_USER} ^(.*)$
RewriteRule ^(.*)$ - [L,NS,P,E=REMOTE_USER:%1]
RequestHeader set X-Remote-User %{REMOTE_USER}s
AuthType Kerberos
AuthName "Kerberos Login"
# Modify to match installation
Krb5Keytab /etc/krb5.keytab
# Modify to match installation
KrbAuthRealms REALM.COM
KrbMethodK5Password off
Require valid-user
</LocationMatch>
oVirt 4.x
---------
# mod_auth_gssapi and mod_session modules have to be enabled and loaded
<LocationMatch ^/ovirt-engine/sso/(interactive-login-negotiate|oauth/token-http-auth)|^/ovirt-engine/api>
<If "req('Authorization') !~ /^(Bearer|Basic)/i">
RewriteEngine on
RewriteCond %{LA-U:REMOTE_USER} ^(.*)$
RewriteRule ^(.*)$ - [L,NS,P,E=REMOTE_USER:%1]
RequestHeader set X-Remote-User %{REMOTE_USER}s
AuthType GSSAPI
AuthName "Kerberos Login"
GssapiCredStore keytab:/etc/httpd/http.keytab
GssapiUseSessions On
Session On
SessionCookieName ovirt_gssapi_session path=/private;httponly;secure;
Require valid-user
ErrorDocument 401 "<html><meta http-equiv=\"refresh\" content=\"0; url=/ovirt-engine/sso/login-unauthorized\"/><body><a href=\"/ovirt-engine/sso/login-unauthorized\">Here</a></body></html>"
</If>
</LocationMatch>
WARNING!!!
In case SSO is enforced on partial URI list (example only api), The
X-Remote-User must be reseted for the remaining URIs, to avoid security
bypass.
AUTHN EXTENSION
The following configuration read the X-Remote-User header and sets it as
principal name.
/etc/ovirt-engine/extensions.d/http-authn.properties
ovirt.engine.extension.name = http-authn
ovirt.engine.extension.bindings.method = jbossmodule
ovirt.engine.extension.binding.jbossmodule.module = org.ovirt.engine-extensions.aaa.misc
ovirt.engine.extension.binding.jbossmodule.class = org.ovirt.engineextensions.aaa.misc.http.AuthnExtension
ovirt.engine.extension.provides = org.ovirt.engine.api.extensions.aaa.Authn
ovirt.engine.aaa.authn.profile.name = http
ovirt.engine.aaa.authn.authz.plugin = ldap-authz
ovirt.engine.aaa.authn.mapping.plugin = http-mapping
config.artifact.name = HEADER
config.artifact.arg = X-Remote-User
MAPPING
/etc/ovirt-engine/extensions.d/http-mapping.properties
ovirt.engine.extension.enabled = true
ovirt.engine.extension.name = http-mapping
ovirt.engine.extension.bindings.method = jbossmodule
ovirt.engine.extension.binding.jbossmodule.module = org.ovirt.engine-extensions.aaa.misc
ovirt.engine.extension.binding.jbossmodule.class = org.ovirt.engineextensions.aaa.misc.mapping.MappingExtension
ovirt.engine.extension.provides = org.ovirt.engine.api.extensions.aaa.Mapping
config.mapAuthRecord.type = regex
config.mapAuthRecord.regex.mustMatch = true
config.mapAuthRecord.regex.pattern = ^(?<user>.*?)((\\\\(?<at>@)(?<suffix>.*?)@.*)|(?<realm>@.*))$
# START-PLATFORM-DEPENDED
# Active directory:
config.mapAuthRecord.regex.replacement = ${user}${at}${suffix}${realm}
# Other
config.mapAuthRecord.regex.replacement = ${user}${at}${suffix}
# END-PLATFORM-DEPENDED
PROBLEM DETERMINATION
---------------------
USEFUL LDAP COMMANDS
Notations:
* @HOST@ - LDAP HOST
* @USERDN@ - Bind user DN, empty for anonymous.
* @USERPW@ - Bind user password.
* @BASEDN@ - Base DN
Find base DN
$ ldapsearch -H ldap://@HOST@ -x -D '@USERDN@' -w '@USERPW@' -b '' -s BASE defaultNamingContext namingContexts
Fetch entire rootDSE
$ ldapsearch -H ldap://@HOST@ -x -D '@USERDN@' -w '@USERPW@' -b '' -s BASE '*' +
Dump entire directory
$ ldapsearch -E pr=1024/noprompt -o ldif-wrap=no -H ldap://@HOST@ -x -D '@USERDN@' -w '@USERPW@' -b '@BASEDN@' '*' +
Test startTLS (preferred)
$ LDAPTLS_REQCERT=never ldapsearch -ZZ -H ldap://@HOST@ -x -D '@USERDN@' -w '@USERPW@' -b '@BASEDN@'
Test LDAP over SSL/TLS
LDAPTLS_REQCERT=never ldapsearch -H ldaps://@HOST@ -x -D '@USERDN@' -w '@USERPW@' -b '@BASEDN@'
Test LDAP over SSL/TLS using GSSAPI
$ LDAPTLS_REQCERT=never ldapsearch -H ldaps://@HOST@ -Y GSSAPI -b '@BASEDN@'
To test using a specific CA certificate, replace LDAPTLS_REQCERT=never
with LDAPTLS_CACERT=ca.cer.
USEFUL DNS COMMANDS
Resolve forest LDAP SRV record
$ dig _ldap._tcp.@FOREST@ SRV
Resolve global catalog SRV record from specific dns server
$ dig @dc1.@FOREST@ _ldap._tcp.gc._msdcs.@FOREST@ SRV
ENGINE LOG
A logger by the name of org.ovirt.engineextensions.aaa.ldap can be set to
INFO, DEBUG, FINE, FINER or ALL to receive verbose output.
To modify logger level to ALL while ovirt-engine is running use the following
command, replace admin@internal with any user with SuperUser role:
$ "${JBOSS_HOME}/bin/jboss-cli.sh" \
--connect \
--timeout=30000 \
--controller=localhost:8706 \
--user=admin@internal \
--commands="
if (outcome != success) of /subsystem=logging/logger=org.ovirt.engineextensions.aaa.ldap:read-attribute(name=level),
/subsystem=logging/logger=org.ovirt.engineextensions.aaa.ldap:add,
end-if,
/subsystem=logging/logger=org.ovirt.engineextensions.aaa.ldap:write-attribute(name=level,value=ALL)
"
ADVANCED EXTENSION CONFIGURATION
--------------------------------
config.profile.searchdir.@SORT@ = DIRECTORY
Additional profile configuration search directories.
xxx is alphabetic sorted.
config.profile.file.@SORT@ = FILE
Profile configurations to read.
xxx is alphabetic sorted.
config.globals.@SORT@.@VAR@ = VALUE
Sequence variables to set before initialization.
config.authn.credentials-change.message = TEXT
A message to display if password is expired.
config.authn.credentials-change.url = URL
A URL to display if password is expired.
attrmap.map-principal-record.name = ID [map-principal-record]
Attribute map to map between principal record and native attributes.
attrmap.map-group-record.name = ID [map-group-record]
Attribute map to map between group record and native attributes.
config.authz.query.max_filter_size = INT [50]
A default maximum filter size in elements. Usually, should be set by
configuration.
config.authz.sequence.namespace.attribute.namespace = ID [namespace]
Attribute name of namespace within the namespace query.
config.authn.sequence.authn.name = ID [authn]
config.authz.sequence.credentials-change.name = ID [credentials-change]
config.authz.sequence.namespace.name = ID [namespace]
config.authz.sequence.query-groups.name = ID [query-groups]
config.authz.sequence.query-principals.name = ID [query-principals]
config.authz.sequence.resolve-groups.name = ID [resolve-groups]
config.authz.sequence.resolve-principal.name = ID [resolve-principal]