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, CC Agent, Recording server and Configmgt.

  1. On the XiVO CC, add the following variables to the /etc/docker/compose/custom.env file to configure the xucserver (CCmanager, UC Assistant and CC Agent) and the Recording server:

    LDAP_URL=ldap://ldap.company.com:389
LDAP_MANAGER_DN=uid=company,ou=people,dc=company,dc=com
LDAP_MANAGER_PASSWORD=xxxxxxxxxx
LDAP_SEARCH_BASE=ou=people,dc=company,dc=com
LDAP_USER_SEARCH_FILTER=uid=%s
DISABLE_XIVO_AUTH=true

  2. On the XiVO PBX, add the same variables to the /etc/docker/xivo/custom.env file to configure Configmgt.

  3. Apply the configuration:

    • on the XiVO CC: xivocc-dcomp up -d

    • on the XiVO PBX: xivo-dcomp up -d

Where

  • LDAP_URL 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). LDAP authentication is enabled only when this variable is set - see also Note for LDAPs

  • LDAP_MANAGER_DN is the LDAP user name of a user with read rights on the whole LDAP (at least the part which contains the users)

  • LDAP_MANAGER_PASSWORD is the password for this user

  • LDAP_SEARCH_BASE is the LDAP OU where to look for users

  • LDAP_USER_SEARCH_FILTER optional is the LDAP filter to search for user by a given login. If unset, the default value is uid=%s

  • DISABLE_XIVO_AUTH optional set to true prevents falling back on the XiVO authentication - see Disabling XiVO based authentication. If unset, the default value is false

Note

If the users log in with username@domain (e.g. with LDAP_USER_SEARCH_FILTER=mail=%s) while their XiVO login is username, the user is first searched with username@domain and, if not found, with the part before the first @.

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'))]

  1. 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),

  2. Copy CUSTOMER_LDAP_CERT file to the xucserver host,

  3. Then copy the CUSTOMER_LDAP_CERT file inside the xucserver container:

    docker cp PATH/TO/CUSTOMER_LDAP_CERT xivocc_xuc_1:/tmp/

  4. 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]:

  5. 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/

  6. 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

  7. 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 of https://cas-server.example.org/cas and set CAS_LOGOUT_ENABLE to true 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

Note

The token validated by the Xuc server is the OIDC id_token.

The Xuc server validates the id_token by decoding and verifying it as a signed JWT (JSON Web Token): it checks the signature against the OIDC server signing keys (JWKS) and validates the claims (iss, aud, exp, etc.).

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 expects 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 token

  • The syntax expects a single element

OIDC_CLIENT_ID

  • It’s the client id configured in the OIDC server

  • It challenges the client id claim of the JWT token (azp, client_id, appid or cid, whichever is present). This claim is optional: a token without any client id claim is accepted

  • It also challenges the aud field in the JWT token if OIDC_AUDIENCE is not configured

  • The 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 token

  • If unset, only OIDC_SERVER_URL will challenge this token field, else, both will be used together

  • The 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 client id claim of the JWT token (azp, client_id, appid or cid)

  • If unset, only OIDC_CLIENT_ID will challenge this token field, else, both will be used together

  • The 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 token

  • If unset, it will be set to the OIDC_CLIENT_ID env variable value by default

  • If your OIDC provider sets aud to a value other than the client id, set this variable to that expected audience value

  • The 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 field

  • The syntax expects a single element

OIDC_SIGNATURE_ALGORITHMS optional

  • It’s the list of accepted token signature algorithms (RSA family)

  • The token signature is verified against the OIDC server signing keys (JWKS), and its alg header must be one of these values

  • If unset, the default value is RS256,RS384,RS512

  • The syntax accepts a single element, or a list of elements separated by comma

OIDC_CLOCK_SKEW_LEEWAY optional

  • It’s the tolerance, in seconds, applied when checking the token exp and nbf fields, to absorb clock drift between the OIDC server and the XiVOCC server

  • If unset, the default value is 30

  • The syntax expects a number of seconds

OIDC_JWKS_CACHE_TTL optional

  • It’s the duration, in seconds, during which the OIDC server signing keys (JWKS) are cached, to avoid fetching them on every authentication

  • A value of 0 or less disables the cache

  • If unset, the default value is 3600

  • The syntax expects a number of seconds

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 expects a simple boolean

OIDC_USE_IMPLICIT_FLOW optional

  • It defines which OAuth 2.0 / OIDC flow the login pages use to obtain the token from the OIDC server

  • If unset, the default value is false, meaning the authorization code flow (with PKCE) is used

  • Set it to true to use the legacy implicit flow

  • The syntax expects a simple boolean

Warning

The implicit flow is deprecated and will be removed in a future version. New deployments should use the default authorization code flow.

OIDC_SCOPE optional

  • It’s the list of scopes requested from the OIDC server during authentication

  • If unset, the default depends on the active flow: openid profile offline_access email for the authorization code flow, openid profile email for the implicit flow

  • The syntax expects a space-separated list of scopes (e.g. openid profile offline_access email)

Recording Server

The Recording Server web interface supports OIDC authentication too. It relies on the same ENABLE_OIDC, OIDC_SERVER_URL and OIDC_CLIENT_ID variables, and validates the id_token the same way as described above, so a realm already configured for the other XiVOCC applications needs no additional variable.

The following points are specific to the Recording Server.

Authorization code flow only

The Recording Server is a public client: it always uses the authorization code flow with PKCE and never sends a client secret. There is no OIDC_CLIENT_SECRET to configure, and OIDC_USE_IMPLICIT_FLOW has no effect on it.

In the OIDC server, the client used by the Recording Server must therefore be declared as a public client, and the Recording Server login URL must be listed both in its valid redirect URIs and in its valid post logout redirect URIs:

https://<xivocc_host>/recording/login

The Recording Server uses its own login page as the OIDC callback URL, so this URL comes in addition to the ones already declared for the other XiVOCC applications. If it is missing from the valid redirect URIs, the OIDC server rejects the authorization request (Keycloak answers Invalid parameter: redirect_uri) and signing in to the Recording Server is not possible. If it is missing from the valid post logout redirect URIs, Keycloak 18 and later refuse the logout redirection.

Login and logout behaviour

  • When OIDC is enabled, opening the Recording Server redirects the user to the OIDC server automatically: the login form is not displayed, and a transient message informs the user that the sign-in is in progress.

  • Whether the XiVO login and password remain usable as a fallback depends on where the authentication fails:

    • When the failure is detected before leaving the Recording Server, for instance when the OIDC server cannot be reached or when OIDC_SERVER_URL does not point to a valid OIDC configuration, an error is displayed and the login form is shown again, so the XiVO login and password can still be used.

    • When the browser has already been redirected to the OIDC server, for instance when the Recording Server login URL is not declared in the valid redirect URIs, the error is displayed by the OIDC server itself. The Recording Server login form is then not reachable, as opening its login URL again simply triggers the redirection once more.

  • Logging out of the Recording Server also logs the user out of the SSO session, by redirecting to the end_session_endpoint advertised by the OIDC server.

Note

Unlike the other XiVOCC applications, the Recording Server does not read OIDC_LOGOUT_ENABLE: its logout always propagates to the SSO session.

Access rights still apply

Authenticating through the SSO does not grant access to the recordings by itself: the user must also hold recording access rights. These rights are checked again every time the recording list is displayed, so revoking them logs the user out even if the SSO session is still valid.

OIDC_SCOPE optional

  • On the Recording Server, if unset, the default value is openid profile