Installation and Setup¶
Install and Setup IIS¶
First, you may need to install IIS role.
This can be done though the Control Panel > Add and Remove Programs > Install Features (appwiz.cpl
) or via Server Manager.
- Those are the features you should select:
Application / CGI
Security / Windows Authentication
(suggested) Performance Features / Dynamic Content Compression
(suggested) Health and Diagnostics / Request Monitor
(suggested) Health and Diagnostics / Tracing
Next you will need to unlock some configuration section to later use the createwebconfig
management command.
- To unlock configuration sections:
Open IIS Manager > Configuration Editor
Select section
system.webServer/handlers
Click
Unlock section
on the right sidebar.Repeat for sections
system.webServer/security/authentication/anonymousAuthentication
andsystem.webServer/security/authentication/windowsAuthentication
.
Note
For more information visit the IIS Topic on Microsoft Docs: https://docs.microsoft.com/en-us/iis
Getting it¶
You can get django-windowsauth by using pip:
$ pip install django-windowsauth
If you want to install it from source, grab the git repository and run setup.py:
$ git clone https://github.com/danyi1212/django-windowsauth.git
$ python setup.py install
Installing¶
You will need to add the windows_auth
application to the INSTALLED_APPS setting in you Django project settings file.
INSTALLED_APPS = [
...
'windows_auth',
...
]
This will allow to execute the createwebconfig
command, add the new model LDAPUer and register it’s Django Admin page.
Next, you will need to run the migrate
management command to create the new SQL table of the new models.:
$ py manage.py migrate windows_auth
Note
This will perform migrations only for windows_auth app. If you have other migrations pending, you may want to omit the windows_auth argument to perform all available migrations.
Configure¶
In order to receive correctly the authenticated user from the IIS Windows Authentication, you will need to add a middleware called RemoteUserMiddleware
.
This middleware must be after AuthenticationMiddleware
, that is usually provided by default with Django’s startproject
template.
MIDDLEWARE = [
...
'django.contrib.auth.middleware.AuthenticationMiddleware',
'django.contrib.auth.middleware.RemoteUserMiddleware',
'windows_auth.middleware.UserSyncMiddleware',
...
]
To process the information passed from the IIS Windows Authentication and translate it into a Django User, you will need to specify the WindowsAuthBackend
authentication backend.
AUTHENTICATION_BACKENDS = [
'windows_auth.backends.WindowsAuthBackend',
'django.contrib.auth.backends.ModelBackend',
]
Note
Be aware, this configuration keeps the Django’s default ModelBackend in order to allow for fallback to Django Native Users.
It can be used to authenticate without IIS, when using the runserver
management command for example.
This is usually not advised to configure for Production setups, but only for Development.
See also
Django documentation about Authenticating using REMOTE_USER https://docs.djangoproject.com/en/3.1/howto/auth-remote-user/
Next you will need to configure the settings for your Domain to allow for LDAP integration with Active Directory.
WAUTH_DOMAINS = {
"EXAMPLE": { # this is your domain's NetBIOS Name, same as in "EXAMPLE\\username" login scheme
"SERVER": "example.local", # the FQDN of the DC server, usually is the FQDN of the domain itself
"SEARCH_BASE": "DC=example,DC=local", # the default Search Base to use when searching
"USERNAME": "EXAMPLE\\bind_account", # username of the account used to authenticate your Django project to Active Directory
"PASSWORD": "<super secret>", # password for the binding account
}
}
See also
About LDAP Search Base: https://docs.microsoft.com/en-us/windows/win32/ad/binding-to-a-search-start-point
(optionally) Configure file path and url path settings for your static
and media
files.
STATIC_URL = '/static/'
STATIC_ROOT = BASE_DIR / "static"
MEDIA_URL = '/media/'
MEDIA_ROOT = BASE_DIR / "media"
You may need to execute $ py manage.py collectstatic
management command after modifying the STATIC_ROOT
setting.
See also
Full how-to guide to Serve Static Files through IIS
Setup Logging¶
Throughout this whole module, logging is done to logger named wauth
.
You may handle and configure this logger through Django’s setting LOGGING
.
This can be done by adding the logger like so:
'wauth': {
'handlers': ['console', 'file', 'mail_admins'],
'level': 'INFO',
'propagate': False,
},
Additionally, you may want to configure logging for ldap3
. You can add this logger:
'ldap3': {
'handlers': ['console', 'ldap'],
'level': 'DEBUG',
'propagate': False,
}
And make sure to configure ldap3
log type, like this:
from ldap3.utils.log import set_library_log_detail_level, BASIC
set_library_log_detail_level(BASIC)
The lines above can be added in your Django settings file, just after the LOGGING
setting.
Remember to document about that in your code!
See also
More information of that on https://ldap3.readthedocs.io/en/latest/logging.html
For your convenience, those are the handles used in the examples above:
'handlers': {
'console': {
'class': 'logging.StreamHandler',
'level': 'WARNING',
},
'file': {
'level': 'INFO',
'class': 'logging.handlers.RotatingFileHandler',
'maxBytes': 2 ** 20 * 100, # 100MB
'backupCount': 10,
'filename': BASE_DIR / 'logs' / 'debug.log',
},
'ldap': {
'level': 'INFO',
'class': 'logging.handlers.RotatingFileHandler',
'maxBytes': 2 ** 20 * 100, # 100MB
'backupCount': 10,
'filename': BASE_DIR / 'logs' / 'ldap.log',
},
'mail_admins': {
'level': 'ERROR',
'class': 'django.utils.log.AdminEmailHandler',
'include_html': True,
},
},
Note
You will need to configure settings for sending emails to use the mail_admins
handler:
https://docs.djangoproject.com/en/3.1/topics/email/
Publish to IIS¶
First, we will need to create the web.config
files for the IIS Website configuration.
This can be done simply by running the management command::
$ py manage.py createwebconfig -s -m -w
Notice the -s
and -m
switches, those are to add configurations for Serving Static Files though IIS.
You may want to omit those switches if you are not planning to serve static files though IIS.
The -w
parameter configures IIS’s Windows Authentication
and disables Anonymous Authentication
in the web.config
file.
You may want to change those settings manually to avoid unlocking those configuration sections.
See also
Reference for createwebconfig
at Management Commands
Next you will need to create a new IIS Website for your Django Project.
Open IIS Manager
Right-click over sites
Click Add website…
Give a name for your site (should use the same as for your Django project)
Specify Physical path for the root of your Django project folder (where the
manage.py
is)Provide binding information as needed (can be changed later)
Congratulation, now you should be able to browse to your new website!
Next are some things to setup and verify before publishing to production…