Auth Delegation
Authentication delegation allows the user to be authenticated through an external source, but it does not eliminate the login step for the user. When using authentication delegation, the user’s credentials are verified via an external system, ensuring a secure login process. However, the user is still required to initiate the login action.
Login Timeout Configuration
When configuring external service as authentication provider, you may have trouble to login if the external system is slow. To overcome this issue, you can increase the default timeout (5000 milliseconds default) by setting the LOGIN_TIMEOUT_MS parameter in the custom.env
of your xivocc installation. This value is the delay in milliseconds before aborting a login attempt.
LOGIN_TIMEOUT_MS=7000
LDAP Authentication
Configure LDAP authent for CCmanager, UC Assistant and CC Agent
Create a a configuration file named
xuc.conf
to add ldap configuration:mkdir -p /etc/docker/xuc/ touch /etc/docker/xuc/xuc.conf
Edit file
/etc/docker/xuc/xuc.conf
with the following content:include "application.conf" authentication { ldap { managerDN = "uid=company,ou=people,dc=company,dc=com" managerPassword = "xxxxxxxxxx" url = "ldap://ldap.company.com:389" searchBase = "ou=people,dc=company,dc=com" userSearchFilter = "uid=%s" } }
Where
managerDN
is the LDAP user name of a user with read rights on the whole LDAP (at least the part which contains the users)managerPassword
is the password for this userurl
is the URL to access the customer LDAP: [ldap|ldaps]://LDAP_HOST:LDAP_PORT (N.B. you MUST specify the port. Usually 389 for ldap and 636 for ldaps). Example:to use LDAP
ldap://10.32.5.6:389
to use LDAP s:
ldaps://ldap.corp.com:636
- see also Note for LDAPs
searchBase
is the LDAP OU where to look for usersuserSearchFilter
is the LDAP filter to search for user by a given login (i.e. the filter to search by login)
Then customize the
docker-xivocc.yml
file to use thisxuc.conf
configuration by adding a volume and an environment variable to specify the alternate config file locationxuc: image: ... environment: - ... - CONFIG_FILE=/conf/xuc.conf volumes: - /etc/docker/xuc:/conf
Finally recreate the container:
xivocc-dcomp stop xuc xivocc-dcomp rm xuc xivocc-dcomp up -d xuc
Note for LDAPs
As said above to connect to LDAP with a TLS/SSL connection you just need to put ldaps
in the url of the ldap authentication configuration.
Then it should work out of the box if the LDAP server uses a certificate signed by a known Certificate Authority of the xucserver JDK.
If the certificate used by the customer LDAP server is not signed by a known Certificate Authority then you need to do the following:
Note
You’re probably in this case if you get the following error in the xucserver log when someone is trying to log in:
play.api.UnexpectedException: Unexpected exception[
AuthenticationDriverException: Unexpected authentication problem in LdapDriver module,
error: An error occurred while attempting to connect to server ldap.test.avencall.com:636:IOException(
LDAPException(resultCode=91 (connect error), errorMessage='An error occurred while attempting to establish a connection to server ldap.test.avencall.com/10.32.0.1:636:
SSLHandshakeException(PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException:
unable to find valid certification path to requested target), ldapSDKVersion=6.0.0, revision=524c20f3bbcc0d83fb56b9e136a2fd3a7f60437d'))]
The customer needs to give you the fullchain certificate file used by the LDAP server (in the following we will refer to it as
CUSTOMER_LDAP_CERT
),Copy
CUSTOMER_LDAP_CERT
file to the xucserver host,Then copy the
CUSTOMER_LDAP_CERT
file inside the xucserver container:docker cp PATH/TO/CUSTOMER_LDAP_CERT xivocc_xuc_1:/tmp/
Generate a Java Keystore file from this certificate:
xivocc-dcomp exec xuc keytool -import -file /tmp/CUSTOMER_LDAP_CERT -alias ldapcert -keystore /tmp/ldapCertTrustStore
when prompt:
chose a password for the Java Keystore you’re creating (you will need it afterwards and we will refer to it in the following as
LDAP_CERT_KSTORE_PWD
)and answer yes to the question Trust this certificate? [no]:
Then on the xucserver host, create a folder to hold this truststore and copy the trusttore generated inside:
mkdir /etc/docker/xuc-custom-truststore docker cp xivocc_xuc_1:/tmp/ldapCertTrustStore /etc/docker/xuc-custom-truststore/
Then customize the
docker-xivocc.yml
file to use this custom keystore by adding a volume and JDK option to specify the custom keystore location:Warning
Take care to:
replace LDAP_CERT_KSTORE_PWD by the password you chose at step 4
keep the correct Xms and Xmx values as configured on your system
xuc: image: ... environment: - JAVA_OPTS=-Xms512m -Xmx2048m -Djavax.net.ssl.trustStore=/customSslTrustStore/ldapCertTrustStore -Djavax.net.ssl.trustStorePassword=LDAP_CERT_KSTORE_PWD - CONFIG_FILE=/conf/xuc.conf volumes: - /etc/docker/xuc:/conf - /etc/docker/xuc-custom-truststore:/customSslTrustStore
Finally recreate the container:
xivocc-dcomp stop xuc xivocc-dcomp rm xuc xivocc-dcomp up -d xuc
CAS Authentication
To enable CAS authentication and sign delegation feature, you need to have an existing CAS infrastructure. You need to be able to create a service for the XiVOCC environment.
Warning
The CAS authentication server must be accessible from the user and the server hosting the XiVOCC containers.
CAS Server users’ username must match the XiVO username to allow login on the XiVOCC applications.
The CAS server must support at least CAS Protocol version 2.0.
The CAS authentication was only validated against CAS Server *``Apereo Central Authentication Service` in version
5.1.8
XiVOCC Configuration
Edit the docker compose file
/etc/docker/compose/docker-xivocc.yml
to add the following configuration in the xuc section (use your CAS server URL instead ofhttps://cas-server.example.org/cas
and setCAS_LOGOUT_ENABLE
totrue
if you want to logout from CAS when logging out from the application):xucmgt: # ... environment: - CAS_SERVER_URL=https://cas-server.example.org/cas - ... # ... xuc: # ... environment: - CAS_SERVER_URL=https://cas-server.example.org/cas - CAS_LOGOUT_ENABLE=false - ... # ...
Recreate and start the XiVOCC environment:
xivocc-dcomp up -d
OpenID Connect (OIDC) Authentication
To enable OIDC authentication and sign delegation feature, you need to have an existing OpenID Connect 1.0 infrastructure. You need to be able to create a realm and a client for the XiVOCC environment.
Warning
The OIDC authentication server must be accessible from the user and the server hosting the XiVOCC containers.
OIDC Server users’ username must match the XiVO username to allow login on the XiVOCC applications.
We use Client Authentication with Keycloak (for more details see => https://openid.net/specs/openid-connect-core-1_0-15.html#ClientAuthentication)
The OIDC authentication was only validated against OIDC Server
Keycloak
in version10.0.2
.
XiVOCC Configuration
Available env variables
Here are the needed env variables to have the OIDC working :
- ENABLE_OIDC
It defines if the OIDC authentication is enabled
If unset, the default value is false
The syntax expect a simple boolean
- OIDC_SERVER_URL
It’s the address where the UC Assistant redirect the user to be authenticated
It challenges the
iss
field in the JWT tokenThe syntax expect a single element
- OIDC_CLIENT_ID
It’s the client id configured in the OIDC server
It challenges the
azp
field in the JWT tokenIt also challenges the
aud
field in the JWT token ifOIDC_AUDIENCE
is not configuredThe syntax accepts a single element
Configuring XiVOCC
Edit the docker compose variables file
/etc/docker/compose/custom.env
and add these keys :
ENABLE_OIDC=true OIDC_CLIENT_ID=myClientId OIDC_SERVER_URL=https://oidc-server.example.org/auth/realms/myrealm
Recreate and start the XiVOCC environment:
xivocc-dcomp up -d
Optional env variables
Here are the additional variables for an advanced configuration :
- OIDC_ADDITIONAL_SERVERS_URL optional
It’s an additional list of accepted token issuers that is allowed to provide token for authentication
Useful if you want to login to the Xuc server with a token issued from a different OIDC server than OIDC_SERVER_URL
It challenges the
iss
field in the JWT tokenIf unset, only
OIDC_SERVER_URL
will challenge this token field, else, both will be used togetherThe syntax accepts a single element, or a list of elements separated by comma
- OIDC_ADDITIONAL_CLIENT_IDS optional
It’s an additional list of accepted client id
Useful if you want to login to the Xuc server with a token issued from a different OIDC server than OIDC_SERVER_URL
It challenges the
azp
field in the JWT tokenIf unset, only
OIDC_CLIENT_ID
will challenge this token field, else, both will be used togetherThe syntax accepts a single element, or a list of elements separated by comma
- OIDC_AUDIENCE optional
It’s the list of accepted audiences
It challenges the
aud
field in the JWT tokenIf unset, it will be set to the
OIDC_CLIENT_ID
env variable value by defaultThe syntax accepts a single element, or a list of elements separated by comma
- OIDC_USERNAME_FIELD optional
It’s the field customizer for the XiVO username mapping
It will decide the name of the field that will be considered as the XiVO username in the JWT token
If unset, the XiVO username will be expected in the
preferred_username
token fieldThe syntax expect a single element
- OIDC_LOGOUT_ENABLE optional
It defines if logging out of the XiVO application will also log the user out of the SSO
If unset, the default value is
false
The syntax expect a simple boolean