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 user
- 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). 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 users
- userSearchFilter 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 this xuc.conf configuration by adding a volume and an environment variable to specify the alternate config file location
```
xuc:
  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 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

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)
For Microsoft Entra Id configuration see => https://learn.microsoft.com/en-us/entra/fundamentals/whatis
The OIDC authentication was only validated against OIDC Server Keycloak in version 10.0.2.

Warning

Opaque access tokens are not supported.

The authentication validates the access 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.). An opaque access token (a random, non-JWT string) cannot be decoded this way and is rejected with an InvalidToken error.

You must configure the identity provider to issue JWT access tokens for the XiVOCC client, otherwise authentication will fail.

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 token
The syntax expect 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 expect 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 expect 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 expect 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 expect a simple boolean