Skip to content

Commit 641b384

Browse files
mostafamostafa
committed
[docs] Reformat README
[docs] Add CONTRIBUTING.md [docs] Add RELEASE-LOG.md
1 parent 286f76f commit 641b384

File tree

3 files changed

+109
-74
lines changed

3 files changed

+109
-74
lines changed

‎CONTRIBUTING.md

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Contributing guide
2+
3+
Thank you for investing your time in contributing to our project! Any contribution you make will be reflected on [authors](AUTHORS.md) ✨.
4+
5+
<!-- Add code of conduct here -->
6+
7+
## New Contributor Guide
8+
9+
To get an overview of the project, read the [README](README.md). Here are some resources to help you get started with open source contributions:
10+
11+
- [Security Assertion Markup Language](https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language)
12+
- [SAML 2.0](https://en.wikipedia.org/wiki/SAML_2.0)
13+
- [SAML metadata](https://en.wikipedia.org/wiki/SAML_metadata)
14+
15+
This library is tested against these SAML SSO identity providers. You can probably open development accounts on these platforms to test your Django with SAML SSO.
16+
17+
- Okta
18+
- Azure Active Directory
19+
- PingOne
20+
- Auth0 (doesn't support custom attributes)
21+
22+
For debugging your setup, you can use SAML-tracer add-on on [Firefox](https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/) or extension on [Chrome](https://chrome.google.com/webstore/detail/saml-tracer/mpdajninpobndbfcldcmbpnnbhibjmch?hl=en), which will help you capture SAML SSO traffic and shows you what is passed around in the HTTP messages.
23+
24+
Read the [tests](django_saml2_auth/tests) to learn more about settings and how each function or endpoint works. And when you open a PR, please add tests and documentation. You can also add your name to the list of [authors](AUTHORS.md). When the PR is ready, mention for the review.
25+
26+
## How to Contribute
27+
28+
1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
29+
2. Fork [the repository](http://github.com/loadimpact/django-saml2-auth) on GitHub to start making your changes to the **master** branch (or branch off of it).
30+
3. Write a test which shows that the bug was fixed or that the feature works as expected.
31+
4. Send a pull request and bug the maintainer ([@mostafa](https://github.com/mostafa)) until it gets merged and published. :) Make sure to add yourself to [authors](AUTHORS.md).
32+
33+
## When you raise an issue or open a PR
34+
35+
Please note this library is mission-critical and supports almost all django versions since 2.2.x. We need to be extremely careful when merging any changes.
36+
37+
The support for new versions of django are welcome and I'll make best effort to make it latest django compatible.

‎README.md

+31-74
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,45 @@
1-
# Django SAML2 Authentication Made Easy
1+
# Django SAML2 Authentication
22

3-
- Original Author
4-
Fang Li
3+
This plugin provides a simple way to integrate SAML2 Authentication into your Django-powered app. SAML SSO is a standard, so practically any SAML2 based SSO identity provider is supported.
54

6-
- Maintainer
7-
Mostafa Moradian
5+
This plugin supports both identity provider and service provider-initiated SSO:
86

9-
- Version support matrix
7+
- For IdP-initiated SSO, the user should sign in to their identity provider platform, e.g., Okta, and click on the application that authorizes and redirects the user to the service provider, that is your platform.
8+
- For SP-initiated SSO, the user should first exist on your platform, either by signing in via the first method (IdP-initiated SSO) or any other custom solution. It can be configured to be redirected to the correct application on the identity provider platform.
9+
10+
For IdP-initiated SSO, the user will be created if it doesn't exist. Still, for SP-initiated SSO, the user should exist in your platform for the code to detect and redirect them to the correct application on the identity provider platform.
11+
12+
- [Django SAML2 Authentication](#django-saml2-authentication)
13+
- [Project Information](#project-information)
14+
- [Donate](#donate)
15+
- [Installation](#installation)
16+
- [How to use?](#how-to-use)
17+
- [Module Settings](#module-settings)
18+
- [JWT Signing Algorithm and Settings](#jwt-signing-algorithm-and-settings)
19+
- [Custom token triggers](#custom-token-triggers)
20+
- [Customize Error Messages](#customize-error-messages)
21+
- [For Okta Users](#for-okta-users)
22+
23+
## Project Information
24+
25+
- Original Author: Fang Li ([@fangli](https://github.com/fangli))
26+
- Maintainer: Mostafa Moradian ([@mostafa](https://github.com/mostafa))
27+
- Version support matrix:
1028
| **Python** | **Django** | **django-saml2-auth** |
1129
| --------------------------- | ---------- | --------------------- |
1230
| 3.7.x, 3.8.x, 3.9.x, 3.10.x | 2.2.x | >=3.4.0 |
1331
| 3.7.x, 3.8.x, 3.9.x, 3.10.x | 3.2.x | >=3.4.0 |
1432
| 3.8.x, 3.9.x, 3.10.x | 4.0.x | >=3.4.0 |
1533

16-
This project aims to provide a simple way to integrate SAML2 Authentication into your Django-powered app. Try it now, and get rid of the complicated configuration of SAML.
17-
18-
Any SAML2 based SSO (Single Sign-On) identity provider (IdP) with dynamic metadata configuration is supported by this Django plugin, for example Okta. The library also supports service provider-initiated SSO.
34+
- Release log is available [here](RELEASE-LOG.md).
1935

20-
## When you raise an issue or PR
21-
22-
Please note this library is mission-critical and supports almost all django versions since 2.2.x. We need to be extremely careful when merging any changes.
23-
24-
The support for new versions of django are welcome and I'll make best effort to make it latest django compatible.
36+
- For contribution, read [contributing guide](CONTRIBUTING.md).
2537

2638
## Donate
2739

28-
Please give us a shiny ![star](https://img.shields.io/github/stars/grafana/django-saml2-auth.svg?style=social&label=Star&maxAge=86400)\! and help spread the word.
40+
Please give us a shiny ![star](https://img.shields.io/github/stars/grafana/django-saml2-auth.svg?style=social&label=Star&maxAge=86400) and help spread the word.
2941

30-
## Install
42+
## Installation
3143

3244
You can install this plugin via `pip`. Make sure you update `pip` to be able to install from git:
3345

@@ -56,15 +68,6 @@ or from source:
5668

5769
[Windows binaries](https://www.zlatkovic.com/projects/libxml/index.html) are also available.
5870

59-
## What does this plugin do?
60-
61-
This plugin can act as a SAML authentication system for Django that supports IdP and SP-initiated SSO.
62-
63-
- For IdP-initiated SSO, the user should log in to their IdP platform (e.g. Okta), and click on the application that authorizes and redirects the user to the SP (your platform).
64-
- For SP-initiated SSO, the user should first exist on your platform (either log in using method 1 or else) and then it can be configured to be redirected to the correct application on the IdP platform.
65-
66-
For IdP-initiated SSO, the user will be created if it doesn't exist, but for SP-initiated SSO, the user should exist in your platform for the code to detect and redirect them to the correct application on the IdP platform.
67-
6871
## How to use?
6972

7073
1. Once you have the library installed or in your `requirements.txt`, import the views module in your root `urls.py`:
@@ -161,7 +164,8 @@ For IdP-initiated SSO, the user will be created if it doesn't exist, but for SP-
161164

162165
5. In your SAML2 SSO identity provider, set the Single-sign-on URL and Audience URI (SP Entity ID) to <http://your-domain/saml2_auth/acs/>
163166

164-
### Explanation
167+
## Module Settings
168+
165169
| **Field name** | **Description** | **Data type(s)** | **Default value(s)** | **Example** |
166170
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
167171
| **METADATA\_AUTO\_CONF\_URL** | Auto SAML2 metadata configuration URL | `str` | `None` | `https://ORG.okta.com/app/APP-ID/sso/saml/metadata` |
@@ -262,7 +266,7 @@ def get_custom_token_query(refresh):
262266

263267
```
264268

265-
## Customize
269+
## Customize Error Messages
266270

267271
The default permission `denied`, `error` and user `welcome` page can be overridden.
268272

@@ -293,50 +297,3 @@ I created this plugin originally for Okta. The `METADATA_AUTO_CONF_URL` needed i
293297
The `Identity Provider metadata` link is the `METADATA_AUTO_CONF_URL`.
294298

295299
More information can be found in the [Okta Developer Documentation](https://developer.okta.com/docs/guides/saml-application-setup/overview/).
296-
297-
## How to Contribute
298-
299-
1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
300-
2. Fork [the repository](http://github.com/loadimpact/django-saml2-auth) on GitHub to start making your changes to the **master** branch (or branch off of it).
301-
3. Write a test which shows that the bug was fixed or that the feature works as expected.
302-
4. Send a pull request and bug the maintainer until it gets merged and published. :) Make sure to add yourself to [AUTHORS](https://github.com/grafana/django-saml2-auth/blob/master/AUTHORS.md).
303-
304-
## Release Log
305-
306-
3.4.0: Add support for Django 3.2 and 4.0 and remove support for older Python and Django versions
307-
308-
3.3.0: Add support for PKI in JWT
309-
310-
3.2.0: Update dependencies (#22)
311-
312-
3.1.0: Make `token` field optional in the attribute statement by introducing `REQUIRE_TOKEN` settings (default: `True`)
313-
314-
3.0.1: Minor fixes
315-
316-
3.0.0: Extensive refactoring of the library (check the commit logs) - incompatible with previous versions
317-
318-
2.3.0: Merge of PRs plus bugfixes and (manual) testing
319-
320-
2.2.1: Fixed is\_safe\_url parameters issue for django 2.1
321-
322-
2.2.0: ADFS SAML compatibility and fixed some issue for Django2.0
323-
324-
2.1.2: Merged \#35
325-
326-
2.1.1: Added ASSERTION\_URL in settings.
327-
328-
2.1.0: Add DEFAULT\_NEXT\_URL. Issue \#19.
329-
330-
2.0.4: Fixed compatibility with Windows.
331-
332-
2.0.3: Fixed a vulnerabilities in the login flow, thanks qwrrty.
333-
334-
2.0.1: Add support for Django 1.10
335-
336-
1.1.4: Fixed urllib bug
337-
338-
1.1.2: Added support for Python 2.7/3.x
339-
340-
1.1.0: Added support for Django 1.6/1.7/1.8/1.9
341-
342-
1.0.4: Fixed English grammar mistakes

‎RELEASE-LOG.md

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Release log
2+
3+
3.5.0: Add support for three new hook functions for JWT (#35)
4+
5+
3.4.0: Add support for Django 3.2 and 4.0 and remove support for older Python and Django versions
6+
7+
3.3.0: Add support for PKI in JWT
8+
9+
3.2.0: Update dependencies (#22)
10+
11+
3.1.0: Make `token` field optional in the attribute statement by introducing `REQUIRE_TOKEN` settings (default: `True`)
12+
13+
3.0.1: Minor fixes
14+
15+
3.0.0: Extensive refactoring of the library (check the commit logs) - incompatible with previous versions
16+
17+
2.3.0: Merge of PRs plus bugfixes and (manual) testing
18+
19+
2.2.1: Fixed is\_safe\_url parameters issue for django 2.1
20+
21+
2.2.0: ADFS SAML compatibility and fixed some issue for Django2.0
22+
23+
2.1.2: Merged \#35
24+
25+
2.1.1: Added ASSERTION\_URL in settings.
26+
27+
2.1.0: Add DEFAULT\_NEXT\_URL. Issue \#19.
28+
29+
2.0.4: Fixed compatibility with Windows.
30+
31+
2.0.3: Fixed a vulnerabilities in the login flow, thanks qwrrty.
32+
33+
2.0.1: Add support for Django 1.10
34+
35+
1.1.4: Fixed urllib bug
36+
37+
1.1.2: Added support for Python 2.7/3.x
38+
39+
1.1.0: Added support for Django 1.6/1.7/1.8/1.9
40+
41+
1.0.4: Fixed English grammar mistakes

0 commit comments

Comments
 (0)