Settings Reference¶
AUDIENCE¶
Default:
Type:
string
orlist
Required
Set this to the value of the aud
claim your ADFS server sends back in the JWT token.
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 |
microsoft:identityserver:your-RelyingPartyTrust-identifier |
BLOCK_GUEST_USERS¶
Default:
False
Type:
boolean
Whether guest users of your Azure AD is allowed to log into the site. This is validated by matching
the http://schemas.microsoft.com/identity/claims/tenantid
-key in the claims towards the configured tenant.
BOOLEAN_CLAIM_MAPPING¶
Default:
None
Type:
dictionary
A dictionary of claim/field mappings that is used to set boolean fields on the user account in Django.
The key represents user model field (e.g. first_name
)
and the value represents the claim short name (e.g. given_name
).
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
CA_BUNDLE¶
Default:
True
Type:
boolean
orstring
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
to use the default CA bundle of the requests
package.
/path/to/ca-bundle.pem
allows you to specify a path to a CA bundle file. If your ADFS server uses a certificate
signed by an enterprise root CA, you will need to specify the path to it’s certificate here.
False
disables the certificate check.
Have a look at the Requests documentation for more details.
Warning
Do not set this value to False
in a production setup. Because we load certain settings from the ADFS server,
this might lead to a security issue. DNS hijacking for example might cause an attacker to inject his own
access token signing certificate.
CLAIM_MAPPING¶
Default:
None
Type:
dictionary
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 the user model field (e.g. first_name
)
and the value represents the claim short name (e.g. given_name
).
example
AUTH_ADFS = {
"CLAIM_MAPPING": {"first_name": "given_name",
"last_name": "family_name",
"email": "email"},
}
The dictionary can also map extra details to the Django user account using an
Extension of the User model
Set a dictionary as value in the CLAIM_MAPPING setting with as key the name User model.
You will need to make sure the related field exists before the user authenticates.
This can be done by creating a receiver on the
post_save signal that
creates the related instance when the User
instance is created.
example
'CLAIM_MAPPING': {'first_name': 'given_name',
'last_name': 'family_name',
'email': 'upn',
'userprofile': {
'employee_id': 'employeeid'
}}
Note
You can find the short name for the claims you configure in the ADFS management console underneath ADFS ➜ Service ➜ Claim Descriptions
CLIENT_ID¶
Default:
Type:
dictionary
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.
CLIENT_SECRET¶
Default:
None
Type:
string
A Client secret is generated by ADFS server when executing the Add-AdfsClient
command with the
-GenerateClientSecret
parameter.
You can lookup this value by executing the powershell command Get-AdfsClient
on the ADFS server
and taking the ClientSecret
value.
CONFIG_RELOAD_INTERVAL¶
Default:
24
Unit: hours
Type:
integer
When starting Django, some settings are retrieved from the ADFS metadata file or the OpenID Connect configuration on the ADFS server. Based on this information, certain configuration for this module is calculated.
This setting determines the interval after which the configuration is reloaded. This allows to automatically follow the token signing certificate rollover on ADFS.
CREATE_NEW_USERS¶
Default:
True
Type:
boolean
Determines whether users are created automatically if they do not exist.
If set to False
, then you need to create your users before they can log in.
DISABLE_SSO¶
Default:
False
Type:
boolean
Setting this to True
will globally disable the seamless single sign-on capability of ADFS.
Forcing ADFS to prompt users for a username and password, instead of automatically logging them in
with their current user. This allows users to use a different account then the one they are logged
in with on their workstation.
You can also selectively enable this setting by using <a href="{% url 'django_auth_adfs:login-no-sso' %}">...</a>
in a template instead of the regular <a href="{% url 'django_auth_adfs:login' %}">...</a>
Attention
This does not work with ADFS 3.0 on windows 2012 because this setting requires OpenID Connect which is not supported on ADFS 3.0
JWT_LEEWAY¶
Default:
0
Type:
str
Allows you to set a leeway of the JWT token. See the official PyJWT docs for more information.
CUSTOM_FAILED_RESPONSE_VIEW¶
Default:
lambda
Type:
str
orcallable
Allows you to set a custom django function view to handle login failures. Can be a dot path to your Django function based view function or a callable.
Callable must have the following method signature accepting error_message
and status
arguments:
def failed_response(request, error_message, status):
# Return an error message
return render(request, 'myapp/login_failed.html', {
'error_message': error_message,
}, status=status)
GROUP_CLAIM¶
Alias of GROUPS_CLAIM
GROUPS_CLAIM¶
Default:
group
for ADFS orgroups
for Azure ADType:
string
Name of the claim in the JWT access 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.
Set this setting to None
to disable automatic group handling. The group memberships of the user
will not be touched.
Important
If not set to None
, a user’s group membership in Django will be reset to math this claim’s value.
If there’s no value in the access token, the user will be removed from all groups.
Note
You can find the short name for the claims you configure in the ADFS management console underneath ADFS ➜ Service ➜ Claim Descriptions
GROUP_TO_FLAG_MAPPING¶
Default:
None
Type:
dictionary
This settings allows you to set flags on a user based on his group membership in Active Directory.
For example, if a user is a member of the group Django Staff
, you can automatically set the is_staff
field of the user to True
.
The key represents the boolean user model field (e.g. is_staff
)
and the value, which can either be a single String or an array of Strings, represents the group(s) name (e.g. Django Staff
).
example
AUTH_ADFS = {
"GROUP_TO_FLAG_MAPPING": {"is_staff": ["Django Staff", "Other Django Staff"],
"is_superuser": "Django Admins"},
}
Note
The group doesn’t need to exist in Django for this to work. This will work as long as it’s in the groups claim in the access token.
GUEST_USERNAME_CLAIM¶
Default:
None
Type:
string
When these criteria are met:
A
guest_username_claim
is configuredToken claims do not have the configured
settings.USERNAME_CLAIM
in itThe
settings.BLOCK_GUEST_USERS
is set toFalse
The claims
tid
does not matchsettings.TENANT_ID
or claimsidp
does not matchiss
.
Then, the GUEST_USERNAME_CLAIM
can be used to populate a username, when the USERNAME_CLAIM
cannot be found in
the claims.
This can be useful when you want to use upn
as a username claim for your own users,
but some guest users (such as normal outlook users) don’t have that claim.
LOGIN_EXEMPT_URLS¶
Default:
None
Type:
list
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.
example
AUTH_ADFS = {
'LOGIN_EXEMPT_URLS': [
'^$',
'^api'
],
}
MIRROR_GROUPS¶
Default:
False
Type:
boolean
This parameter will create groups from ADFS in the Django database if they do not exist already.
True
will create groups.
False
will not create any extra groups.
Important
This parameter only has effect if GROUP_CLAIM is set to something other then None
.
RELYING_PARTY_ID¶
Default:
Type:
string
Required
Set this to the Relying party trust identifier
value of the Relying Party Trust
(2012) or Web application
(2016) you configured in ADFS.
You can lookup this value by executing the powershell command Get-AdfsRelyingPartyTrust
(2012) or
Get-AdfsWebApiApplication
(2016) on the ADFS server and taking the Identifier
value.
RESOURCE¶
Alias for RELYING_PARTY_ID
RETRIES¶
Default:
3
Type:
integer
The number of time a request to the ADFS server is retried. It allows, in combination with TIMEOUT to fine tune the behaviour of the connection to ADFS.
SCOPES¶
Default:
[]
Type:
list
Only used when you have v2 AzureAD config
SERVER¶
Default:
Type:
string
Required when your identity provider is an on premises ADFS server.
Only one of SERVER
or TENANT_ID
can be set.
The FQDN of the ADFS server you want users to authenticate against.
SETTINGS_CLASS¶
Default:
django_auth_adfs.config.Settings
Type:
string
By default, django-auth-adfs reads the configuration from the Django setting
AUTH_ADFS
. You can provide the configuration in a custom implementation
and point to it by using the SETTINGS_CLASS
setting:
# in myapp.adfs.config
class CustomSettings:
SERVER = 'bar'
AUDIENCE = 'foo'
...
# in settings.py
AUTH_ADFS = {
'SETTINGS_CLASS': 'myapp.adfs.config.CustomSettings',
# other settings are not needed
}
The value must be an importable dotted Python path, and the imported object must be callable with no arguments to initialize.
Use cases are storing configuration in database so an administrator can edit the configuration in an admin interface.
TENANT_ID¶
Default:
Type:
string
Required when your identity provider is an Azure AD instance.
Only one of TENANT_ID
or SERVER
can be set.
The FQDN of the ADFS server you want users to authenticate against.
TIMEOUT¶
Default:
5
Unit: seconds
Type:
integer
The timeout in seconds for every request made to the ADFS server. It’s passed on as the timeout
parameter
to the underlying calls to the requests
library.
It allows, in combination with RETRIES to fine tune the behaviour of the connection to ADFS.
USERNAME_CLAIM¶
Default:
winaccountname
for ADFS orupn
for Azure AD.Type:
string
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.
The value of the claim must be a unique value. No 2 users should ever have the same value.
Warning
You shouldn’t need to set this value for ADFS or Azure AD unless you use custom user models.
Because winaccountname
maps to the sAMAccountName
on Active Directory, which is guaranteed
to be unique. The same for Azure AD where upn
maps to the UserPrincipleName
, which is unique
on Azure AD.
Note
You can find the short name for the claims you configure in the ADFS management console underneath ADFS ➜ Service ➜ Claim Descriptions
VERSION¶
Default:
v1.0
Type:
string
Version of the Azure Active Directory endpoint version. By default it is set to v1.0
. At the time of writing this documentation, it can also be set to v2.0
. For new projects, v2.0
is recommended. v1.0
is kept as a default for backwards compatibility.
PROXIES¶
Default:
None
Type:
dict
An optional proxy for all communication with the server. Example: {'http': '10.0.0.1', 'https': '10.0.0.2'}
See the requests documentation for more information.