README.md

OWASP Single Sign-On

OWASP SSO is a javascript application that allows a secure-by-default self-hosted SSO experience, including phishing-proof two-factor authentication, using state-of-the-art security mechanisms.

For a detailed introduction, full list of features and architecture overview please visit the official project page: https://owasp.org/www-project-sso/

From Sources

1. Install node.js
2. Run git clone https://github.com/OWASP/SSO_Project.git (or clone your own fork of the repository)

Set up backend

1. Go into the cloned folder with cd SSO_Project
2. Go into the backend folder with cd js-backend folder
3. Run npm install to set it up the first time
4. Edit the .env file and set all mandatory environment variables, especially your MariaDB database and SMTP server. You can use your email account like Gmail for testing.
5. If you are on an operating system without the bash shell, you need to install it and add it to the PATH. For Windows, install Git and add the bash.exe to your PATH environment variable. You will need to restart the command line in such case
6. Generate certificates by running bash scripts/setup.bash "OWASP SSO". For Windows, use \ instead of / and you can put another name instead of OWASP SSO for branding
7. Run npm run serve to run the backend - it is now available at https://localhost:3000
8. Visit the page once to accept the certificate warning in your browser

Set up frontend

1. Open a new console and go into the cloned folder with SSO_Project
2. Go into the frontend folder with cd vue-ui folder
3. Run npm install to set it up the first time
4. Run npm run serve to start a development server
5. Open https://localhost:8080 in your browser to use the application

Docker Container

Backend

Frontend

You can start a development environment via npm run docker:dev and a production-ready environment via npm run docker:prod. To clean up all containers, run npm run docker:cleanup.

The production environment requires to set the environment variables for all external services.

Customization

Most changes to the application can be done by modifying the .env files or providing environment variables to the components, as existing environment variables are not overwritten.

In js-backend/websites.json you can configure your own websites for SSO. Below you find a sample configuration.

{
	"default": { // Default behavior of the website, if no SSO flow is used
		name: "OWASP SSO", // Name of default page, internal identifier
		"branding": { // Allows branding the login page
			"backgroundColor": "#f7f9fb", // Page background color
			"fontColor": "#888", // Color of the text below the login box
			"legalName": "OWASP Foundation", // Legal name displayed below the login box
			"privacyPolicy": "https://owasp.org/www-policy/operational/privacy", // Link to privacy policy, mandatory
			"imprint": "https://owasp.org/contact/", // Link to legal imprint, optional
			"logo": "https://owasp.org/assets/images/logo.png" // Link to logo
		},
		"terms": "https://owasp.org/www-policy/operational/general-disclaimer", // Link to terms & conditions, Optional
		// If you want to use multi-language terms, you can fill terms with an object like this: {"en": "english-link", "de": "german-link"}
		"syslog": { // Configure a syslog server that will receive audit logs in CEF format, optional
			"target": "default-siem", // IP or hostname
			"protocol": "tcp" // Protocol
			// Check out all parameters at https://cyamato.github.io/SyslogPro/module-SyslogPro-Syslog.html
		}
	},
	"1": { // ID of the website
		"jwt": "hello-world", // JWT secret for authentication flow
		"signedRequestsOnly": false, // If set to true, only signed login requests are allowed
		"name": "E Corp", // Short name of the company
		"redirect": "https://postman-echo.com/post", // URL to redirect to
		"samlAllowedConsumers": [ // List of allowed AssertionConsumerServiceURL values
			"https://postman-echo.com/post?saml"
		],
		"branding": { // Allows branding the login page
			"backgroundColor": "#fff", // Page background color
			"fontColor": "#254799", // Color of the text below the login box
			"legalName": "E Corp", // Legal name displayed below the login box
			"privacyPolicy": "https://www.nbcuniversal.com/privacy", // Link to privacy policy, mandatory
			"imprint": "https://www.e-corp-usa.com/about.html", // Link to legal imprint, optional
			"logo": "https://www.e-corp-usa.com/images/e-corp-logo-blue.png" // Link to logo
		},
		"certificates": [{ // Allow external certificate authorities, optional
			"authorities": ["e-corp.ca.pem"], // List of CA files in js-backend/keys/ca folder to be used for this webhook
			"webhook": { // Webhook settings. If not set, matching with a custom CA passes authentication
				"url": "https://postman-echo.com/post", // URL for the server to contact for verification
				"successContains": "94:0B:DE:AD:BB:80:10:BD:17:C1:48:B4:5A:B2:66:3C:B5:75:DE:7B:89:37:65:D3:60:FF:B0:09:26:27:B2:91", // If the webhook return contains this text, pass the check
				"successRegex": "/test/" // If the webhook return matches this regex, pass the check
			}
		}]
	}
}

Login flow

The OWASP SSO supports two login flows.

SAML flow

Simply redirect the user using SAML GET/POST parameters to https://example.com/#/in/saml. You need to provide a destination parameter. This host will be matched against the host of websites redirect parameter. If one is found, this branding will be used and the user will be on checkout redirected to the URL you specified in the destination parameter.

JWT flow

The JWT flow is intended to allow both a simple integration and advanced use cases.

For an unauthenticated JWT login request, the user can simply be redirected to https://example.com/#/in/1, where 1 is a placeholder for the website ID. This is the easiest way to integrate OWASP SSO into a custom application.

For an authenticated JWT login request, you need to create a JWT token using the shared JWT secret. The token has the following requirements:

1. Maximum validity of five minutes
2. Audience needs to match the hostname of the deployed SSO page
3. Issuer needs to match the configured pages shortname

If you specify an email address as Subject, the user will be automatically logged in (missing the second factor) with this address. If no user with this email address exists, it will be registered.

The authenticated user flow is intended for cases where you want to manage users internally and only delegate for MFA requests to OWASP SSO.

In both cases, the user will be redirected to the configured redirect URL with a short-lived JWT token.

Demo

A demo will be provided in the future.

This is a deployment-test and sneak-peek instance only! You are not supposed to use this instance for your own hacking endeavours! No guaranteed uptime! Guaranteed stern looks if you break it!

Node.js version compatibility

OWASP SSO officially supports the node.js in line with the official node.js LTS schedule. Docker images and packaged distributions are offered accordingly.

Troubleshooting

If you need support to set up the application or customize it for you needs, please post your specific problem and question in the subreddit where community members can best try to help you.

🛑 Please avoid opening GitHub issues for support requests or questions!

Contributing

We are always happy to get new contributors on board! Please check CONTRIBUTING.md to learn how to contribute to our codebase or the translation into different languages!

References

Did you write a blog post, magazine article or do a podcast about or mentioning OWASP Single Sign-On? Or maybe you held or joined a conference talk or meetup session, a hacking workshop or public training where this project was mentioned?

Add it to our ever-growing list of REFERENCES.md by forking and opening a Pull Request!

Donations

The OWASP Foundation gratefully accepts donations via Stripe. Projects such as Single Sign-On can then request reimbursement for expenses from the Foundation. If you'd like to express your support of the SSO project, please make sure to tick the "Publicly list me as a supporter of OWASP SSO" checkbox on the donation form. You can find our more about donations and how they are used here.

Contributors

The OWASP SSO core project team are:

• @JamesCullum

For a list of all contributors to the OWASP SSO please visit our Contributor list.

All special mentions are included in the application at /#/about.

Licensing

This program is free software: You can redistribute it and/or modify it under the terms of the GPL License.