Next Active Directory Integration

Next Active Directory Integration allows WordPress to authenticate, authorize, create and update users against Microsoft Active Directory. Next ADI ist a complete rewrite of its predecessor Active Directory Integration. You can easily import users from your Active Directory into your WordPress instance and keep both synchronized through Next Active Directory Integration's features.

If you like this plug-in we'd like to encourage you to purchase a support plan from https://active-directory-wp.com/ to support the ongoing development of this plug-in.

Important requirement changes

NADI requires PHP 8.1 or later. The reason is that security support for PHP version prior 8.1 have been dropped by the maintainers as you can see in the official PHP documentation. For security reasons and in order to use NADI in 2024 we hereby politely encourage you to migrate your environments to at least PHP 8.1.

Thank you all for your support and understanding.

Getting Started

You can download the ready-to-use version from the WordPress.org Plugin Directory or from the SVN repository hosted by WordPress.org.

If you are developer, you can also clone this Git repository inside the wp-content/plugins directory of your WordPress environment.

After the cloning you have to update the dependencies with help of Composer (execute composer install inside the cloned repository folder). To install composer follow the instructions on https://getcomposer.org/download/.

Development

Contributing

Pull requests and changes must be made against the develop or a dedicated feature or bugfix branch. Name the branches either bugfix/${GITHUB_ISSUE_NUMBER} or feature/${GITHUB_ISSUE_NUMBER}.
Any changes must be added in the UNRELEASED section of the readme.txt for documentation purposes.

Commit messages

We are using conventional commits since mid 2022.
Git commits should be signed-off (git commit -s -m "...").

Use the following commit message format:

fix: some fix for an existing GitHub issue (#123)
chore: some dependency update

Release process

When releasing a new version, the changes from develop must be merged to main. The main version must be tagged accordingly (${MAJOR}.${MINOR}.${BUGFIX}) where ${MAJOR} is 3. After tagging, the tag has to be pushed. A new 3.x-tag is automatically tested, gets then pushed to wordpress.org and will be automatically released.

To create a new release, do the following:

git checkout main && git merge develop
Switch the = UNRELEASED = header in readme.txt's changelog section to ${VERSION}.
Create and push the new tag

git add readme.txt
git commit -s -m "release: 3.${MINOR}.${BUGFIX}"
git tag -s -a 3.${MINOR}.${BUGFIX} -m "release: 3.${MINOR}.${BUGFIX}"
git push origin 3.${MINOR}.${BUGFIX}

git checkout develop && git merge main
Prepend the = UNRELEASED = header in the readme.txt changelog section
Push development branch

git add readme.txt
git commit -s -m "release: preparation for next release"
git push origin develop

Pre-release

For pre-releases, a new tag must be created which is not [2-3].[\d+].[\d+]:

git tag -s -a v4-rc1 -m "pre-release: v3-rc1"
git push origin v4-rc1

Referencing issues

Due to the development history of NADI, we have a combination of old Jira issues and newer GitHub issues. References to the old Jira issues stay as they are. For newer GitHub issues we are using the following format:

Documentation

For documentation purposes (e.g. references in readme.txt, @issue annotation in unit tests or a badge inside the official documentation), we use #${GITHUB_ISSUE_NUMBER}, e.g. #555.

Tests

Test methods are prefixed with GH_{GITHUB_ISSUE_NUMBER}_, e.g. GH_555_ for easier filtering. Each test method must have (as described before) the annotation @issue #${GITHUB_ISSUE_NUMBER} assigned.

Testing

Tests are made with PHPUnit 9.5 Get PHPUnit 9.5 with

# get PHPUnit
wget https://phar.phpunit.de/phpunit-9.5.phar

Running unit tests

cd active-directory-integration2
# run unit tests with default PHPUnit configuration
php ./vendor/bin/phpunit --testsuite "unit" --configuration phpunit.xml

Running integration tests

cd active-directory-integration2
# running integration test against a local install Active Directory instance
# executing the ITs with PHP binary is required for of passing environment variables to the test
php -d AD_ENDPOINT=127.0.0.1 -d AD_PORT=389 -d AD_USERNAME=username@domain.com -d AD_PASSWORD=Password -d AD_USE_TLS='' -d AD_SUFFIX=@domain.com -d AD_BASE_DN='DC=domain,DC=com' path/to/phpunit.phar --testsuite "integration" --no-coverage

Running all tests

cd active-directory-integration2
# running integration test against a local install Active Directory instance
# executing the ITs with PHP binary is required for of passing environment variables to the test
php -d AD_ENDPOINT=127.0.0.1 -d AD_PORT=389 -d AD_USERNAME=username@domain.com -d AD_PASSWORD=Password -d AD_USE_TLS='' -d AD_SUFFIX=@domain.com -d AD_BASE_DN='DC=domain,DC=com' path/to/phpunit.phar --no-coverage

Running all tests in PhpStorm

Run > Edit Configurations > Defaults > PHPUnit

Test Runner options: --test-suffix Test.php,IT.php
Interpreter options: -d AD_ENDPOINT=127.0.0.1 -d AD_PORT=389 -d AD_USERNAME=Administrator -d AD_PASSWORD=Pa$$w0rd -d AD_USE_TLS='' -d AD_SUFFIX=@test.ad -d AD_BASE_DN='DC=test,DC=ad'

Update translation

After changing the next_ad_int-de_DE.po you have to build the next_ad_int-de_DE.mo and next_ad_int-de_DE_formal.mo file.

# Execute this command inside the plugin root folder (with the index.php)
ant compile-all-languages
# or execute this:
ant -Dmsgfmt=/path/to/gettext/msgfmt compile-all-languages

Make sure that you have GNU gettext with msgfmt installed.

It is also possible to generate the next_ad_int-de_DE.mo with Poedit (or some other .po tool). You can create a copy from the next_ad_int-de_DE.mo file and name it next_ad_int-de_DE_formal.mo.

Continuous Integration

We are using GitHub Action for the CI/CD process. You can find everything related to CI/CD inside .github/workflows.

The branches

main
and develop

will be automatically tested.

NeosIT/active-directory-integration2