# Univention as SAML IDP for SSO

# Preamble

The EE server and client support the SAML protocol that allows you to configure an external service as IDP (identity provider) for SSO (single sign on). This guide here will explain how to configure Univention as SAML IDP for SSO. We assume that your webclient is running on https://example.com, the server is reachable with https://example.com/server (e.g. https://example.com/server/info/ shows you some nice json output). This is your first SAML provider that you want to configure (therefore we give him the ID "1").

TIP

This feature is only available in the Enterprise Edition.

# Univention

As a first step we have to configure Univention.

Go to Domain / SAML Identity Provider
Click "Add"
Fill out the required fields and activate the service provider
Switch to Extended Settings and fill out the LDAP mapping information
Go back to the Univention Portal and select Users / Groups
Select the group you want and add the Psono service provider under SAML settings

# Server (settings.yaml)

During the installation of the server you have created a settings.yaml that needs to be adjusted now.

Generate SP certificate

You will need a certificate for your service provider (SP) later. You can generate one easily with:
```
openssl req -new -newkey rsa:2048 -x509 -days 3650 -nodes -sha256 -out sp_x509cert.crt -keyout sp_private_key.key
```
This will generate a private key (sp_private_key.key) and the public certificate (sp_x509cert.crt).

Comment in the following section:

	SAML_CONFIGURATIONS:
	1:
		idp:
			entityId: "UNIVENTION_SSO_SAML_IDENTITY_PROVIDER_ISSUE"
			singleLogoutService:
				binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
				url: "UNIVENTION_SSO_SIGN_OUT_URL"
			singleSignOnService:
				binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
				url: "UNIVENTION_SSO_SIGN_IN_URL"
			x509cert: "UNIVENTION_SSO_X509_CERTIFICATE"
			groups_attribute: "groups"
			username_attribute: 'username'
			email_attribute: 'email'
			username_domain: 'example.com'
			required_group: []
			is_adfs: false
			honor_multifactors: true
			max_session_lifetime: 86400
		sp:
			NameIDFormat: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
			assertionConsumerService:
				binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
			attributeConsumingService:
				serviceName: "SP_SERVICE_NAME"
				serviceDescription: "Psono password manager"
				requestedAttributes:
					-
						attributeValue: []
						friendlyName: ""
						isRequired: false
						name: "attribute-that-has-to-be-requested-explicitely"
						nameFormat: ""
			privateKey: "SP_PRIVATE_CERTIFICATE"
			singleLogoutService:
				binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
			x509cert: "SP_X509CERT"
			autoprovision_psono_folder: false
			autoprovision_psono_group: false
		strict: true

Replace UNIVENTION_SSO_SAML_IDENTITY_PROVIDER_ISSUE with: https://univention.example.com/simplesamlphp/saml2/idp/metadata.php
Replace UNIVENTION_SSO_SIGN_IN_URL with the Sign-In URL from Univention: https://univention.example.com/simplesamlphp/saml2/idp/SSOService.php
Replace UNIVENTION_SSO_SIGN_OUT_URL with the Sign-Out URL from Univention: https://univention.example.com/simplesamlphp/saml2/idp/SingleLogoutService.php
Replace UNIVENTION_SSO_X509_CERTIFICATE with the "X.509 Certificate" from Univention: https://univention.example.com/simplesamlphp/saml2/idp/certificate (remove all line breaks)
Replace SP_SERVICE_NAME with the "metadata" URL of your service provider, e.g. https://example.com/server/saml/1/metadata/
Replace SP_PRIVATE_CERTIFICATE with the content of the previous generated "sp_private_key.key". (remove all line breaks)
Replace SP_X509CERT with the content of the previous generated "sp_x509cert.crt". (remove all line breaks)

Restart the server afterward

Adjust authentication methods

Make sure that SAML is part of the AUTHENTICATION_METHODS parameter in your settings.yaml e.g.
```
AUTHENTICATION_METHODS: ['SAML']
```
Restart the server afterward
(optional) Debug Mode

It is helpful in the later debugging to enable debug mode.
```
DEBUG: True
```
WARNING

Restart the server afterward and don't forget to remove it before going to production.

# Client (config.json)

Now you have to configure your client, so your users can use this configured IDP.

Basic

Update your config.json similar to the one shown below.
```
{
  ...
    "authentication_methods": ["SAML"],
    "saml_provider": [{
      "title": "SAML Login",
      "provider_id": 1,
      "button_name": "Login "
    }]
  ...
}
```
The variable authentication_methods restricts the allowed login methods. In the example above only SAML will be allowed and the normal login "hidden". The title and button_name can be adjusted however you like. The provider_id needs to match the one that you used on your server.
(optional) Automatic login

You may want to "automatically" click on the login button to initiate the login flow. You can accomplish this by modifying the config.json as shown below:
```
{
  ...
    "authentication_methods": ["SAML"],
    "auto_login": true,
  ...
}
```
WARNING

This will only work if you have just one provider configured with only one authentication method. Users won't be able to modify the server url nor choose to register or interact with the login form in any other way.

← SAML - Okta SAML Group Mapping →