django a uth a dfsdocumentation Release 0.2.0 Joris Beckers Sep 14, 2017
Contents 1 Features 3 2 Contents 5 2.1 Installation................................................ 5 2.1.1 Requirements.......................................... 5 2.1.2 Package installation....................................... 5 2.1.3 Setting up django........................................ 6 2.2 Settings.................................................. 7 2.2.1 AUDIENCE........................................... 7 2.2.2 AUTHORIZE_PATH...................................... 7 2.2.3 CA_BUNDLE......................................... 8 2.2.4 BOOLEAN_CLAIM_MAPPING............................... 8 2.2.5 CLAIM_MAPPING...................................... 8 2.2.6 CLIENT_ID........................................... 9 2.2.7 CERT_MAX_AGE....................................... 9 2.2.8 GROUP_CLAIM........................................ 9 2.2.9 LOGIN_EXEMPT_URLS................................... 9 2.2.10 LOGIN_REDIRECT_URL................................... 10 2.2.11 ISSUER............................................. 10 2.2.12 REDIR_URI.......................................... 10 2.2.13 RESOURCE.......................................... 10 2.2.14 SIGNING_CERT........................................ 11 2.2.15 SERVER............................................ 11 2.2.16 TOKEN_PATH......................................... 11 2.2.17 USERNAME_CLAIM..................................... 11 2.3 ADFS Configuration Guide....................................... 11 2.3.1 Step 1 - Configuring a Relying Party Trust........................... 12 2.3.2 Step 2 - Configuring Claims.................................. 18 2.3.3 Step 3 - Add an ADFS client.................................. 20 2.3.4 Step 4 - Determine configuration settings........................... 20 2.4 Extras................................................... 21 2.4.1 Middleware........................................... 21 2.4.2 Context processor........................................ 22 2.5 Troubleshooting............................................. 22 2.6 ADFS OAuth2 flow........................................... 23 2.7 Contributing............................................... 23 i
ii 2.7.1 Get Started!........................................... 24 2.7.2 Types of Contributions..................................... 24 2.8 Changelog................................................ 24 2.8.1 0.2.0-2017-09-14....................................... 24 2.8.2 0.1.2-2017-03-11....................................... 25 2.8.3 0.1.1-2016-12-13....................................... 25 2.8.4 0.1.0-2016-12-11....................................... 25 2.8.5 0.0.5-2016-12-10....................................... 25 2.8.6 0.0.4-2016-03-14....................................... 25 2.8.7 0.0.3-2016-02-21....................................... 25 2.8.8 0.0.2-2016-02-11....................................... 26 2.8.9 0.0.1-2016-02-09....................................... 26
A Django authentication backend for Microsoft ADFS 3.0 Free software: BSD License Homepage: https://github.com/jobec/django-auth-adfs Documentation: http://django-auth-adfs.readthedocs.org/ Contents 1
2 Contents
CHAPTER 1 Features Integrates Django with Active Directory through Microsoft ADFS 3.0 by using OAuth2. Provides seamless single sign on (SSO) for your Django project on intranet environments. Auto creates users and adds them to Django groups based on info in JWT claims received from ADFS. 3
4 Chapter 1. Features
CHAPTER 2 Contents Installation Requirements This package has been tested on the following Python versions: 2.7 3.4 3.5 3.6 And with the following Django versions: 1.8 1.9 1.10 1.11 You will also need the following: A properly configured Microsoft Windows server with the ADFS 3.0 role installed. A root CA bundle containing the root CA that signed the webserver certificate of your ADFS server. Package installation Python package: pip install django-auth-adfs 5
Setting up django In your project s settings.py AUTHENTICATION_BACKENDS = ( 'django_auth_adfs.backend.adfsbackend', ) INSTALLED_APPS = ( # Needed for the ADFS redirect URI to function 'django_auth_adfs', # checkout config.py for more settings AUTH_ADFS = { "SERVER": "adfs.yourcompany.com", "CLIENT_ID": "your-configured-client-id", "RESOURCE": "your-adfs-rpt-name", # Make sure to read the documentation about the AUDIENCE setting # when you configured the identifier as a URL! "AUDIENCE": "microsoft:identityserver:your-relyingpartytrust-identifier", "ISSUER": "http://adfs.yourcompany.com/adfs/services/trust", "CA_BUNDLE": "/path/to/ca-bundle.pem", "CLAIM_MAPPING": {"first_name": "given_name", "last_name": "family_name", "email": "email"}, "BOOLEAN_CLAIM_MAPPING": {"is_staff": "user_is_staff", "is_superuser": "user_is_superuser"}, "REDIR_URI": "https://www.yourcompany.com/oauth2/login", } ######################## # OPTIONAL SETTINGS ######################## TEMPLATES = [ { 'OPTIONS': { 'context_processors': [ # Only needed if you want to use the variable ADFS_AUTH_URL in your templates 'django_auth_adfs.context_processors.adfs_url', ], }, }, ] MIDDLEWARE = ( # With this you can force a user to login without using # the @login_required decorator for every view function # # You can specify URLs for which login is not forced by # specifying them in LOGIN_EXEMPT_URLS in setting.py. 6 Chapter 2. Contents
) # The values in LOGIN_EXEMPT_URLS are interpreted as regular expressions. 'django_auth_adfs.middleware.loginrequiredmiddleware', # Or, when using django <1.10 MIDDLEWARE_CLASSES = ( 'django_auth_adfs.middleware.loginrequiredmiddleware', ) In your project s urls.py urlpatterns = [ # Needed for the redirect URL to function url(r'^oauth2/', include('django_auth_adfs.urls')), # If you're using Django 1.8, this code should be used instead url(r'^oauth2/', include('django_auth_adfs.urls', namespace='django_auth_adfs')), ] The URL you have to configure as the redirect URL in ADFS depends on the url pattern you configure. In the example above you have to make the redirect url in ADFS point to https://yoursite.com/oauth2/login Settings AUDIENCE Default: None Set this to the value of the aud claim your ADFS server sends back in the JWT token. If you leave this set to None this claim will not be verified. You can lookup this value by executing the powershell command Get-AdfsRelyingPartyTrust on the ADFS server and taking the Identifier value. But beware, it doesn t match exactly if it s not a URL. Examples Relying Party Trust identifier your-relyingpartytrust-identifier https://adfs.yourcompany.com/adfs/services/trust aud claim value microsoft:identityserver:your-relyingpartytrust-identifier https://adfs.yourcompany.com/adfs/services/trust AUTHORIZE_PATH Default: /adfs/oauth2/authorize The path to the authorize page off your ADFS server. Users have to visit this page to receive an authorization code. This value is appended to the server FQDN and used to build the full authorization URL. This URL is available as the variable ADFS_AUTH_URL inside templates when using the django-auth-adfs context processor adfs_url. The default value matches the default for ADFS 3.0. 2.2. Settings 7
CA_BUNDLE Default: True The value of this setting is passed to the call to the Requests package when fetching the access token from ADFS. It allows you to control the webserver certificate verification of the ADFS server. True makes it use the default CA bundle of your system. False disables the certificate check. /path/to/ca-bundle.pem allows you to specify a path to a CA bundle file. Have a look at the Requests documentation for more details. BOOLEAN_CLAIM_MAPPING Default: None A dictionary of claim/field mappings that is used to set boolean fields of the user account in Django. The key represents user model field (e.g. given_name). first_name) and the value represents the claim short name (e.g. If the value is any of y, yes, t, true, on, 1, the field will be set to True. All other values, or the absence of the claim, will result in a value of False example AUTH_ADFS = { "BOOLEAN_CLAIM_MAPPING": {"is_staff": "user_is_staff", "is_superuser": "user_is_superuser"}, } Note: You can find the short name for the claims you configure in the ADFS management console underneath ADFS Service Claim Descriptions CLAIM_MAPPING Default: None A dictionary of claim/field mappings that will be used to populate the user account in Django. The user s details will be set according to this setting upon each login. The key represents user model field (e.g. given_name). example AUTH_ADFS = { "CLAIM_MAPPING": {"first_name": "given_name", "last_name": "family_name", "email": "email"}, } first_name) and the value represents the claim short name (e.g. 8 Chapter 2. Contents
Note: You can find the short name for the claims you configure in the ADFS management console underneath ADFS Service Claim Descriptions CLIENT_ID Required Set this to the value you configured on your ADFS server as ClientId when executing the Add-AdfsClient command. You can lookup this value by executing the powershell command Get-AdfsClient on the ADFS server and taking the ClientId value. CERT_MAX_AGE Default: 24 The number of hours the ADFS token signing certificate is cached. This timer gets started the first time someone logs in using a ADFS JWT token because only then the backend class is loaded for the first time. Note: This setting is related with the SIGNING_CERT setting. GROUP_CLAIM Default group Name of the claim sent in the JWT token from ADFS that contains the groups the user is member of. If an entry in this claim matches a group configured in Django, the user will join it automatically. If the returned claim is empty, or the setting is set to None, users are not joined to any group. Important: User s group membership in Django will be reset to math this claim s value. If there s no value, the user will end up being member of no groups. Note: You can find the short name for the claims you configure in the ADFS management console underneath ADFS Service Claim Descriptions LOGIN_EXEMPT_URLS Default: None When you activate the LoginRequiredMiddleware middleware, by default every page will redirect an unauthenticated user to the page configured in the Django setting LOGIN_URL. If you have pages that should not trigger this redirect, add them to this setting as a list value. Every item it the list is interpreted as a regular expression. 2.2. Settings 9
LOGIN_REDIRECT_URL Default: None The URL users are redirected to when their authentication is successful. Because we redirect users to and from the ADFS server, we can t pass along a parameters telling us what page the user tried accessing before he got redirected. Thet s why we redirect to a fixed page. If you leave this set to None, the Django setting named LOGIN_REDIRECT_URL will be used instead. ISSUER Default: None Set this to the value of the iss claim your ADFS server sends back in the JWT token. Usually this is something like http://adfs.yourcompany.com/adfs/services/trust. If you leave this set to None this claim will not be verified. You can lookup this value by executing the powershell command Get-AdfsProperties on the ADFS server and taking the Identifier value. Important: The issuer isn t necessarily the same as the URL of your ADFS server. It usually starts with HTTP instead of HTTPS REDIR_URI Required Sets the redirect uri configured for your client id in ADFS. Because we need this value in a context without access to a Django request object, it needs to be explicitly configured. You can lookup this value by executing the powershell command Get-AdfsClient on the ADFS server and taking the RedirectUri value (without the {} brackets). Important: Make sure both this setting and the setting on your ADFS server matches with the url pattern configured in your urls.py file. See the install documentation for more details. RESOURCE Required Set this to the Relying party trust identifier value of the Relying Party Trust you configured in ADFS. You can lookup this value by executing the powershell command Get-AdfsRelyingPartyTrust on the ADFS server and taking the Identifier value. 10 Chapter 2. Contents
SIGNING_CERT Default: True Can be one of the following values: True for autoloading the certificate from the FederationMetadata.xml file on the ADFS server. The base64 PEM representation of the Token Signing Certificate configured in your ADFS server. The path to a certificate file in base64 PEM format. The default value allows you to automatically load new certificates when they get changed on the ADFS server. For more details see the AutoCertificateRollover setting of your ADFS server. Note: This setting is related with the CERT_MAX_AGE setting. SERVER Required Default: None The FQDN of the ADFS server you want users to authenticate against. TOKEN_PATH Default: /adfs/oauth2/token This is the path to the token page of your ADFS server. The authentication backend will try to fetch the access token by submitting the authorization code to this page. USERNAME_CLAIM Default: winaccountname Name of the claim sent in the JWT token from ADFS that contains the username. If the user doesn t exist yet, this field will be used as it s username. Note: You can find the short name for the claims you configure in the ADFS management console underneath ADFS Service Claim Descriptions ADFS Configuration Guide Getting this module to work is sometimes not so straight forward. If your not familiar with JWT tokens or ADFS itself, it might take some tries to get all settings right. This guide tries to given a very basic overview of how to configure ADFS and how to determine the settings for django-auth-adfs. Installing and configuring the basics of ADFS is not in scope. ADFS server: https://adfs.example.com Web server: http://webserver.example.com 2.3. ADFS Configuration Guide 11
Step 1 - Configuring a Relying Party Trust From the AD FS Management screen, go to AD FS Trust Relationships Relying Party Trusts and click Add Relying Party Trust Click Start 12 Chapter 2. Contents
Select Enter data about the relying party manually and click Next Enter a display name for the relying party and click Next. 2.3. ADFS Configuration Guide 13
Select AD FS profile and click Next Leave everything empty click Next 14 Chapter 2. Contents
We don t need WS-Federation or SAML support so leave everything empty again and click Next Enter a relying party trust identifier and click add. The identifier can be anything but beware, there s a difference between entering a URL and something else. For more details see the example section of the AUDIENCE setting. Note: This is the value for the AUDIENCE and the RESOURCE settings. 2.3. ADFS Configuration Guide 15
Select I do not want to configure and click Next. Select Permit all users to access the relying party and click Next. 16 Chapter 2. Contents
Keep everything default and click Next. Select Open the Edit Claim Rules dialog and click Close 2.3. ADFS Configuration Guide 17
Step 2 - Configuring Claims If you selected Open the Edit Claim Rules dialog while adding a relying party, this screen will open automatically. Else you can open it by right clicking the relying party in the list and select Edit Claim Rules On the Issuance Transform Rules tab, click the Add Rule button Select Send LDAP Attributes as Claims and click Next 18 Chapter 2. Contents
Give the rule a name and select Active Directory as the attribute store. Then configure the below claims. LDAP Attribute Outgoing Claim Type E-Mail-Addresses E-Mail Address Given-Name Given Name Surname Surname Token-Groups - Unqualified Names Group SAM-Account-Name Windows Account Name Click OK to save the settings Note: The Outgoing Claim Type is what will be visible in the JWT Access Token. The first 3 claims will go into the CLAIM_MAPPING setting. The 4th is the GROUP_CLAIM setting. The 5th is the USERNAME_CLAIM setting. You cannot just copy the name from this screen. The name of the claim as visible in the JWT token is the short name which you can lookup in the AD FS Management screen underneath AD FS Service Claim Descriptions 2.3. ADFS Configuration Guide 19
You should now see the rule added. Click OK to save the settings. Step 3 - Add an ADFS client While the previous steps could be done via the GUI, the next step needs to be performed via PowerShell. Pick a value for the following fields. Name Name ClientId RedirectUri Example value Django Website OAuth2 Client django_website.adfs.client_id http://webserver.example.com/oauth2/login Now execute the following command from a powershell console. PS C:\Users\Administrator> Add-ADFSClient -Name "Django Website OAuth2 Client" - ClientId "django_website.adfs.client_id" -RedirectUri "http://webserver.example.com/ oauth2/login" The ClientId value will be the CLIENT_ID setting and the RedirectUri value will be the REDIR_URI setting. Step 4 - Determine configuration settings Once everything is configured, you can use the below PowerShell commands to determine the value for the settings of this package. The ## ## pieces were added to indicate with what setting the value corresponds with. PS C:\Users\Administrator> Get-AdfsClient -Name "Django Website OAuth2 Client" Select RedirectUri,ClientId Format-List ## REDIR_URI ## RedirectUri : {http://webserver.example.com/oauth2/login} ## CLIENT_ID ## ClientId : django_website.adfs.client_id PS C:\Users\Administrator> Get-AdfsProperties select Hostname,Identifier Format- List ## SERVER ## HostName : adfs.example.com ## ISSUER ## Identifier : http://adfs.example.com/adfs/services/trust PS C:\Users\Administrator> Get-AdfsRelyingPartyTrust -Name "Django Website" Select Identifier,IssuanceTransformRules Format-List ## RESOURCE ## ## AUDIENCE ## Identifier : {django_website.adfs.identifier} ## CLAIM_MAPPING ## ## GROUP_CLAIM ## ## USERNAME_CLAIM ## IssuanceTransformRules : @RuleTemplate = "LdapClaims" @RuleName = "LDAP attribute claims" c:[type == "http://schemas.microsoft.com/ws/2008/06/identity/ claims/windowsaccountname", 20 Chapter 2. Contents
Issuer == "AD AUTHORITY"] => issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/ emailaddress", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/ givenname", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/ surname", "http://schemas.xmlsoap.org/claims/group", "http://schemas.microsoft.com/ws/2008/06/identity/claims/ windowsaccountname"), query = ";mail,givenname,sn,tokengroups,samaccountname;{0}", param = c.value); If you followed this guide, you should end up with a configuration like this. AUTH_ADFS = { "SERVER": "adfs.example.com", "CLIENT_ID": "django_website.adfs.client_id", "RESOURCE": "django_website.adfs.identifier", "AUDIENCE": "microsoft:identityserver:django_website.adfs.identifier", "ISSUER": "http://adfs.example.com/adfs/services/trust", "CA_BUNDLE": False, "CLAIM_MAPPING": {"first_name": "given_name", "last_name": "family_name", "email": "email"}, "USERNAME_CLAIM": "winaccountname", "GROUP_CLAIM": "group" "REDIR_URI": "http://webserver.example.com/oauth2/login", } Extras Middleware django-auth-adfs ships with a middleware class named LoginRequiredMiddleware. You can use it to force an unauthenticated user to be redirected to the page defined in the LOGIN_PAGE setting in settings.py without having to add code to every view. By default it s disabled for the page defined in the LOGIN_URL setting and the redirect page for ADFS. But by setting the LOGIN_EXEMPT_URLS setting, you can exclude other pages from authentication. Have a look at the configuration documentation for more information. To enable the middleware, add it to MIDLEWARE in settings.py (or MIDDLEWARE_CLASSES if using Django <1.10. make sure to add it after any other session or authentication middleware to be sure all other methods of identifying the user are tried first. In your settings.py file, add the following: MIDDLEWARE = ( 'django_auth_adfs.middleware.loginrequiredmiddleware', ) AUTH_ADFS = { 2.4. Extras 21
} "LOGIN_EXEMPT_URLS": ["api/", "public/"], Context processor This context processor allows you to use the login URL of your ADFS server as a variable inside your templates. This can be used for example to provide a login link. First, in your settings.py file, add the following: TEMPLATES = [ { 'OPTIONS': { 'context_processors': [ # Only needed if you want to use the variable ADFS_AUTH_URL in your templates 'django_auth_adfs.context_processors.adfs_url', ], }, }, ] Then, inside a template you can point to this variable like so: <a href="{{ ADFS_AUTH_URL }}">Click here to log in</a> Troubleshooting If you run into any problems, you can set the logging level in Django to DEBUG. You can do this by adding the configuration below to your settings.py You can see this logging in your console, or in you webserver log if you re using something like Apache with mod_wsgi. More details about logging in Django can be found in the official Django documentation LOGGING = { 'version': 1, 'disable_existing_loggers': False, 'formatters': { 'verbose': { 'format': '%(levelname)s %(asctime)s %(name)s %(message)s' }, }, 'handlers': { 'console': { 'class': 'logging.streamhandler', 'formatter': 'verbose' 22 Chapter 2. Contents
} }, }, 'loggers': { 'django_auth_adfs': { 'handlers': ['console'], 'level': 'DEBUG', }, }, ADFS OAuth2 flow This page briefly explains the way OAuth2 authentication with ADFS works. +-----------+ +--------+ (7) ---(5)--------> Django <-(6)---------- ADFS (3) +--- -------+ +---- ---+ ^ ^ ^ (1)(2) (4) v + ------ ---+ ----(2)-----------+ Browser <--(4)-------------+ +-----------+ 1. An unauthenticated user requests a protected page. 2. User gets redirected to ADFS. 3. ADFS authenticates the user. 4. ADFS redirected the user to a specific page and includes a authorization code in the query parameters 5. With the code Django requests an access token from ADFS 6. ADFS sends back an access token in JWT format including claims 7. Django validates the token and creates the user if it doesn t exists yet More details and a great explanation about what URL s are used in the process can be found here: http://blog.scottlogic. com/2015/03/09/oauth2-authentication-with-adfs-3.0.html Contributing Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. 2.6. ADFS OAuth2 flow 23
Get Started! Types of Contributions You can contribute in many ways: Report Bugs Report bugs in the issue section of the repository on GitHub. If you are reporting a bug, please include: Detailed steps to reproduce the bug. Any details about your local setup that might be helpful in troubleshooting. Fix Bugs Look through the issues for bugs. Anything tagged with bug is open to whoever wants to implement it. Implement Features Look through the issues for features. Anything tagged with feature is open to whoever wants to implement it. Write Documentation We could always use more documentation, whether as part of the docs or in docstrings in the code. Submit Feedback The best way to send feedback is to file an issue on GitHub. If you are proposing a feature: Explain in detail how it would work. Keep the scope as narrow as possible, to make it easier to implement. Changelog 0.2.0-2017-09-14 Fixed a bug were authentication failed when the last ADFS signing key was not the one that signed the JWT token. Django 1.11 support and tests. Proper handling the absence of code query parameter after ADFS redirect. Added ADFS configuration guide to docs. Allow boolean user model fields to be set based on claims. The namespace argument for include() is not needed anymore on Django >=1.9. 24 Chapter 2. Contents
Fixed some Django 2.0 deprecation warnings, improving future django support. 0.1.2-2017-03-11 Support for django 1.10 new style middleware using the MIDDLEWARE setting. 0.1.1-2016-12-13 Numerous typos fixed in code and documentation. Proper handling of class variables to allow inheriting from the class AdfsBackend. 0.1.0-2016-12-11 By default, the ADFS signing certificate is loaded from the FederationMetadata.xml file every 24 hours. Allowing to automatically follow certificate updates when the ADFS settings for AutoCertificateRollover is set to True (the default). Group assignment optimisation. Users are not removed and added to all groups anymore. Instead only the groups that need to be removed or added are handled. Backwards incompatible changes The redundant ADFS_ prefix was removed from the configuration variables. The REQUIRE_LOGIN_EXEMPT_URLS variable was renamed to LOGIN_EXEMPT_URLS 0.0.5-2016-12-10 User update code in authentication backend split into separate functions. 0.0.4-2016-03-14 Made the absence of the group claim non-fatal to allow users without a group. 0.0.3-2016-02-21 ADFS_REDIR_URI is now a required setting Now supports Python 2.7, 3.4 and 3.5 Now supports Django 1.7, 1.8 and 1.9 Added debug logging to aid in troubleshooting Added unit tests Lot s of code cleanup 2.8. Changelog 25
0.0.2-2016-02-11 Fixed a possible issue with the cryptography package when used with apache + mod_wsgi. Added a optional context processor to make the ADFS authentication URL available as a template variable (ADFS_AUTH_URL). Added a optional middleware class to be able force an anonymous user to authenticate. 0.0.1-2016-02-09 Initial release 26 Chapter 2. Contents