Skip to main content

Active Directory Login

Xylok's AD Login provides seamless single sign on (SSO) for Xylok on intranet environments that use Windows Server 2012 R2, 2016, or Microsoft Azure AD. Xylok leverages the django_auth_adfs package to enable this, so most of the configuration details will be available from its documentation, found at https://django-auth-adfs.readthedocs.io/en/latest/config_guides.html.

Configuration​

First, identify what AD service you will be using for authentication: an organization-manager Windows Server or Microsoft Azure AD. There are corresponding sections below.

Second, edit /etc/xylok.conf and include the configuration variables from the correct section of this article.

Finally, apply and test the configuration as discussed in the Applying and Testing section of this article.

The Django Auth ADFS documentation may help!

If you need more guidance on the configuration variables below, the Django Auth ADFS documentation generally has additional information.

Common settings​

Whether using ADFS or Azure AD, the following settings are applicable:

  • AD_SIGN_IN=True: This will tell Xylok to use Active Directory authentication instead of the normal form sign in method. If not using this feature, either set this to False or remove the variable entirely.
  • XYLOK_HOST: The host name URL used to access Xylok. For deployments where the Xylok host has a domain name, for example, this value might be https://xylok.local.
  • AD_CLIENT_ID: For ADFS, this is value configured on the ADFS server as ClientId when executing the Add-AdfsClient command. For Azure, it is listed as the Application (client) ID in Azure.
  • AD_GROUPS_CLAIM: Maps AD groups to Xylok groups. For ADFS, default to "group" and for Azure defaults to "groups". See https://django-auth-adfs.readthedocs.io/en/latest/settings_ref.html#groups-claim.
  • AD_GROUP_TO_FLAG_MAPPING_IS_STAFF: If given, should be a comma-separated list (without spaces!) of AD group short names. If a user is in any of the given groups, they will be flagged as a staff user in Xylok, allowing them to access the Django Admin pages (although not necessarily change anything). See https://django-auth-adfs.readthedocs.io/en/latest/settings_ref.html#group-to-flag-mapping
  • AD_GROUP_TO_FLAG_MAPPING_IS_SUPERUSER: If given, should be a comma-separated list (without spaces!) of AD short names. If a user is in any of the given groups, they will be flagged as a superuser in Xylok, allowing them to access the Django Admin pages and implicitly have all permissions. See https://django-auth-adfs.readthedocs.io/en/latest/settings_ref.html#group-to-flag-mapping
General behavior of mapping AD groups to Xylok groups
  1. By default, Azure sends Object IDs for the groups, rather than the actual group names. As a result, the Xylok groups will need to be named after the Object ID to map correctly.
  2. If a user belongs to a group in ADFS/Azure that does not exist in Xylok, a new group with that name will be created automatically in Xylok and that user will be added to it.
  3. If a user belongs to a group in ADFS/Azure that does exist in Xylok, the user will be added to that group in Xylok and their permissions will be set by that group's (Xylok) permissions.
  4. If a user does not belong to a group in ADFS/Azure that does OR does not exist in Xylok, the user will not be added to that group in Xylok.

Windows Server 2012 R2 & Windows Server 2016​

ADFS-specific settings include:

  • AD_SERVER: The fully qualified domain name (FQDN) of the ADFS server users will authenticate against.
  • AD_AUDIENCE: Set this to the value of the aud claim your ADFS server sends back in the JWT token. If this is a URL, it will be the same as the RELYING_PARTY_ID .
  • AD_RELYING_PARTY_ID: Set this to the Relying party trust identifier value of the Relying Party Trust (2012) or Web application (2016) configured in ADFS.
  • AD_CHECK_CA: If True, Xylok will attempt to validate the AD server's identity using a PEM file stored at /opt/xylok/ad-certs/ad-cert.pem. This directory will need to be created and a PEM file corresponding to your AD server must be placed at the specified path. If False (or not specified), no validation will be performed.

Microsoft Azure AD​

Azure AD-specific settings include:

  • AD_CLIENT_SECRET: Used by Xylok to prove its identity when requesting a token from Azure.
  • AD_TENANT_ID: Found under Tenant Information in the Azure AD Overview window.

Applying and Testing​

After all of the required variables are added to /etc/xylok.conf, the configuration should be reloaded by running:

sudo systemctl restart xylok

In the web browser, go to https://<XYLOK_HOST>/oauth2/login. If SSO is configured correctly, you should be redirected to your organization's sign on page. If you had previously bookmarked the built-in Xylok authentication page, update your bookmarks accordingly. The default Login link in the Xylok sidebar should automatically point to the new login page.

Troubleshooting​

If you are having trouble connecting, debug information can be found using the following process:

  1. Set DEBUG=True in /etc/Xylok.conf.
  2. Reload the configuration by running sudo systemctl restart xylok.
  3. In a terminal, run /opt/xylok/xylok logs -f web, this will follow the logs in the web container.
  4. Log out of Xylok, then log back in using the Active Directory login, and check the logs in the terminal. There should be debug information you can use in there.
  5. Specifically, it may be helpful to extract the access token and decode it using a base64 json decoder. This will provide a full picture of all the information ADFS or Azure is providing to Xylok.

Check Django Auth ADFS documentation for more in-depth information on configuration, and as always, feel free to email us at [email protected].