SAML

You can integrate your active directory or other SAML compliant identity provider in your Nepenthes instance.

Prerequisites

In order to use integrate Nepenthes as a service provider (SP) using SAML, your identity providers (idP):

needs to be able to handle SAML 2.0 redirect Single-Sign On (SSO) flows, in some implementations also referred to as WebSSO
has a known or configurable set of attributes that map to the following required Nepenthes attributes. The way these attribute mappings will be defined is described later in this document.
- login: A stable attribute used to uniquely identify the user. This will most commonly map to an account ID, samAccountName or email (but please note that emails are often interchangeable, and this might result in logins changing in Nepenthes).
- email: The email attribute of the user being authenticated
- first name and last name of the user.
provides the public certificate or certificate fingerprint (SHA1) in use for communicating with the idP.

1: Configure the SAML integration

The configuration can be provided in one of two ways:

Environment variables (1.1)
Settings in the database (1.2)
for Nepenthes version 11 and older in config/configuration.yml file (1.3)

Whatever means are chosen, the plugin simply passes all options to omniauth-saml. See their configuration documentation for further details.

The options are mutually exclusive. If you decide to save settings in the database, they will override any ENV variables you might have set. (For Nepenthes version 11 and older: If settings are already provided via ENV variables, they will overwrite settings in a configuration.yml file.)

1.1 Environment variables

As with all the rest of the Nepenthes configuration settings, the SAML configuration can be provided via environment variables.

Example

shell

# Name of the provider, leave this at saml unless you use multiple providers
NEPENTHES_SAML_SAML_NAME="saml"

# The name that will be display in the login button
NEPENTHES_SAML_SAML_DISPLAY__NAME="<Name of the login button>"

# The callback within Nepenthes that your idP should redirect to
NEPENTHES_SAML_SAML_ASSERTION__CONSUMER__SERVICE__URL="https://<openproject.host>/auth/saml/callback"

# The SAML issuer string that Nepenthes will call your idP with
NEPENTHES_SAML_SAML_ISSUER="https://<openproject.host>"

# IF your SSL certificate on your SSO is not trusted on this machine, you need to add it here in ONE line
### one liner to generate certificate in ONE line
### awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' <yourcert.pem>
#idp_cert: "-----BEGIN CERTIFICATE-----\n ..... SSL CERTIFICATE HERE ...-----END CERTIFICATE-----\n"
# Otherwise, the certificate fingerprint must be added
# Either `NEPENTHES_SAML_SAML_IDP__CERT` or `NEPENTHES_SAML_SAML_IDP__CERT__FINGERPRINT` must be present!
NEPENTHES_SAML_SAML_IDP__CERT="-----BEGIN CERTIFICATE-----<cert one liner>-----END CERTIFICATE-----"
# If you  this environment variable through a shell, you will need to run it through C style quoting to preserve the newline
# Otherwise you will get an internal error with this log line "PEM_read_bio_X509: bad base64 decode"
# NEPENTHES_SAML_SAML_IDP__CERT=$'-----BEGIN CERTIFICATE-----<cert one liner>-----END CERTIFICATE-----'

NEPENTHES_SAML_SAML_IDP__CERT__FINGERPRINT="da:39:a3:ee:5e:6b:4b:0d:32:55:bf:ef:95:60:18:90:af:d8:07:09"
# Replace with your single sign on URL, the exact value depends on your idP implementation
NEPENTHES_SAML_SAML_IDP__SSO__TARGET__URL="https://<hostname of your idp>/application/saml/<slug>/sso/binding/post/"

# (Optional) Replace with your redirect flow single sign out URL that we should redirect to
NEPENTHES_SAML_SAML_IDP__SLO__TARGET__URL=""

# Which SAMLAttribute we should look for for the corresponding attributes of Nepenthes
# can be a string or URI/URN depending on our idP format
NEPENTHES_SAML_SAML_ATTRIBUTE__STATEMENTS_EMAIL="[mail]"
NEPENTHES_SAML_SAML_ATTRIBUTE__STATEMENTS_LOGIN="[mail]"
NEPENTHES_SAML_SAML_ATTRIBUTE__STATEMENTS_FIRST__NAME="[givenName]"
NEPENTHES_SAML_SAML_ATTRIBUTE__STATEMENTS_LAST__NAME="[sn]"
# You can also specify multiple attributes, the first found value will be used. Example:
# NEPENTHES_SAML_SAML_ATTRIBUTE__STATEMENTS_LOGIN="['mail', 'samAccountName', 'uid']"

Please note that every underscore (_) in the original configuration key has to be replaced by a duplicate underscore (__) in the environment variable as the single underscore denotes namespaces. For more information, follow our guide on environment variables.

1.2 Settings in database

The SAML settings can also be changed at runtime in the database through the Nepenthes settings. As opposed to other settings there is no user interface for this. That means it's best to set them using the console.

shell

# package based installation:
> sudo openproject run console

# docker-based installation:
> docker exec -it openproject bundle exec rails console

# docker-compose-based installation:
> docker-compose run --rm web bundle exec rails console

Once on the console you can set the same values as named in the ENV environment file, however they need to be nested within a 'providers' key as follows. For example:

ruby

Setting.plugin_openproject_auth_saml = Hash(Setting.plugin_openproject_auth_saml).deep_merge({
  "providers" => {
    "saml" => {
      "name" => "saml",
      "display_name" => "My SSO",
      "assertion_consumer_service_url" => "https://<YOUR OPENPROJECT HOSTNAME>/auth/saml/callback",
      # The SAML issuer string that Nepenthes will call your idP with
      "issuer" => "https://<YOUR OPENPROJECT HOSTNAME>",
      ### one liner to generate certificate in ONE line
      ### awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' <yourcert.pem>
      "idp_cert" => "-----BEGIN CERTIFICATE-----\nMI................IEr\n-----END CERTIFICATE-----\n",
      # Otherwise, the certificate fingerprint must be added
 	  # Either `idp_cert` or `idp_cert_fingerprint` must be present!
	  "idp_cert_fingerprint" => "E7:91:B2:E1:...",

      # Replace with your SAML 2.0 redirect flow single sign on URL
      # For example: "https://sso.example.com/saml/singleSignOn"
      "idp_sso_target_url" => "<YOUR SSO URL>",
      # Replace with your redirect flow single sign out URL
      # or comment out
      # For example: "https://sso.example.com/saml/proxySingleLogout"
      "idp_slo_target_url" => "<YOUR SSO logout URL>",

      # Attribute map in SAML
      "attribute_statements" => {
        # What attribute in SAML maps to email (default: mail)
        "email" => ['mail'],
        # What attribute in SAML maps to the user login (default: uid)
        "login" => ['uid'],
        # What attribute in SAML maps to the first name (default: givenName)
        "first_name" => ['givenName'],
        # What attribute in SAML maps to the last name (default: sn)
        "last_name" => ['sn']
      }
    }
  }
})

1.3 config/configuration.yml file

NOTE: ONLY for Nepenthes version 11 and older

In your Nepenthes packaged installation, you can modify the /opt/openproject/config/configuration.yml file. Edit the file in your favorite editor

shell

vim /opt/openproject/config/configuration.yml

This will contains the complete Nepenthes configuration and can be extended to also contain metadata settings and connection details for your SSO identity provider.

The following is an exemplary file with a set of common settings:

yaml

default:
  # <-- other configuration -->
  saml:
    # First SAML provider
    mysaml1:  
      # Name of the provider, leave this at saml unless you use multiple providers
      name: "saml"
      # The name that will be display in the login button
      display_name: "My SSO"
      # Use the default SAML icon
      icon: "auth_provider-saml.png"

      # The callback within Nepenthes that your idP should redirect to
      assertion_consumer_service_url: "https://<YOUR OPENPROJECT HOSTNAME>/auth/saml/callback"
      # The SAML issuer string that Nepenthes will call your idP with
      issuer: "https://<YOUR OPENPROJECT HOSTNAME>"

      # IF your SSL certificate on your SSO is not trusted on this machine, you need to add it here in ONE line
      ### one liner to generate certificate in ONE line
      ### awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' <yourcert.pem>
      #idp_cert: "-----BEGIN CERTIFICATE-----\n ..... SSL CERTIFICATE HERE ...-----END CERTIFICATE-----\n"
      # Otherwise, the certificate fingerprint must be added
      # Either `idp_cert` or `idp_cert_fingerprint` must be present!
      idp_cert_fingerprint: "E7:91:B2:E1:..."

      # Replace with your SAML 2.0 redirect flow single sign on URL
      # For example: "https://sso.example.com/saml/singleSignOn"
      idp_sso_target_url: "<YOUR SSO URL>"
      # Replace with your redirect flow single sign out URL
      # or comment out
      # For example: "https://sso.example.com/saml/proxySingleLogout"
      idp_slo_target_url: "<YOUR SSO logout URL>"

      # Attribute map in SAML
      attribute_statements:
        # What attribute in SAML maps to email (default: mail)
        email: ['mail']
        # What attribute in SAML maps to the user login (default: uid)
        login: ['uid']
        # What attribute in SAML maps to the first name (default: givenName)
        first_name: ['givenName']
        # What attribute in SAML maps to the last name (default: sn)
        last_name: ['sn']
      
    # OPTIONAL: Additional SAML provider(s)
    #mysaml2:
    #  name: "saml2"
    #  display_name: "Additional SSO"
    #  (...)
    #mysaml3:
    #  (...)

Be sure to choose the correct indentation and base key. The items below the saml key should be indented two spaces more than saml already is. And saml can will need to be placed in the default or production group so it will already be indented. You will get an YAML parsing error otherwise when trying to start Nepenthes.

2. Configuration details

In this section, we detail some of the required and optional configuration options for SAML.

2.1 Mandatory: Response signature verification

SAML responses by identity providers are required to be signed. You can configure this by either specifying the response's certificate fingerprint in idp_cert_fingerprint , or by passing the entire PEM-encoded certificate string in idp_cert (beware of newlines and formatting the cert, c.f. the idP certificate options in omniauth-saml)

2.2 Mandatory: Attribute mapping

Use the key attribute_statements to provide mappings for attributes returned by the SAML identity provider's response to Nepenthes internal attributes.

You may provide attribute names or namespace URIs as follows: email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'].

The Nepenthes username is taken by default from the email attribute if no explicit login attribute is present.

a) Attribute mapping example for database

ruby

Setting.plugin_openproject_auth_saml = Hash(Setting.plugin_openproject_auth_saml).deep_merge({
  "providers" => {
    "saml" => {
       # ... other attributes, see above.
       # Attribute map in SAML
      "attribute_statements" => {
        # What attribute in SAML maps to email (default: mail)
        "email" => ['mail'],
        # another example for combined attributes in an array:
        "login" => ['username', 'samAccountName', 'uid'],
        # What attribute in SAML maps to the first name (default: givenName)
        "first_name" => ['givenName'],
        # What attribute in SAML maps to the last name (default: sn)
        "last_name" => ['sn']
      }
    }
  }
})

b) Attribute mapping example for configuration.yml

NOTE: ONLY for Nepenthes version 11 and older

yaml

default:
  # <-- other configuration -->
    mysaml1:
      # <-- other configuration -->
      # Attribute map in SAML
      attribute_statements:
        # Use the `mail` attribute for 
        email: ['mail']
        # Use the mail address as login
        login: ['mail']
        # What attribute in SAML maps to the first name (default: givenName)
        first_name: ['givenName']
        # What attribute in SAML maps to the last name (default: sn)
        last_name: ['sn']

2.3 Optional: Set the attribute format

By default, the attributes above will be requested with the format urn:oasis:names:tc:SAML:2.0:attrname-format:basic. That means the response should contain attribute names 'mail', etc. as configured above.

If you have URN or OID attribute identifiers, you can modify the request as follows:

NOTE: Example is ONLY for Nepenthes version 11 and older and needs to be redesigned for ENV configuration

yaml

default:
  # <-- other configuration -->
    mysaml1:
      # <-- other configuration -->
      # Modify the request attribute sent in the request
      # These oids are exemplary, but will often be identical,
      # please check with your identity provider for the correct oids
      request_attributes:
        - name: 'urn:oid:0.9.2342.19200300.100.1.3'
          friendly_name: 'Mail address'
          name_format: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
        - name: 'urn:oid:2.5.4.42'
          friendly_name: 'First name'
          name_format: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
        - name: 'urn:oid:2.5.4.4'
          friendly_name: 'Last name'
          name_format: urn:oasis:names:tc:SAML:2.0:attrname-format:uri

      # Attribute map in SAML
      attribute_statements:
        email: ['urn:oid:0.9.2342.19200300.100.1.3']
        login: ['urn:oid:0.9.2342.19200300.100.1.3']
        first_name: ['urn:oid:2.5.4.42']
        last_name: ['urn:oid:2.5.4.4']

2.4 Optional: Request signature and Assertion Encryption

Your identity provider may optionally encrypt the assertion response, however note that with the required use of TLS transport security, in many cases this is not necessary. You may wish to use Assertion Encryption if TLS is terminated before the Nepenthes application server (e.g., on the load balancer level).

To configure assertion encryption, you need to provide the certificate to send in the request and private key to decrypt the response:

NOTE: Example is ONLY for Nepenthes version 11 and older and needs to be redesigned for ENV configuration

yaml

default:
  # <-- other configuration -->
    mysaml1:
      # <-- other configuration -->
      certificate: "-----BEGIN CERTIFICATE-----\n .... certificate contents ....\n-----END CERTIFICATE-----"
      private_key: "-----BEGIN PRIVATE KEY-----\n .... private key contents ....\n-----END PRIVATE KEY-----"

Request signing means that the service provider (Nepenthes in this case) uses the certificate specified to sign the request to the identity provider. They reuse the same certificate and private_key settings as for assertion encryption. It is recommended to use an RSA key pair, the key must be provided without password.

To enable request signing, enable the following flag:

NOTE: Example is ONLY for Nepenthes version 11 and older and needs to be redesigned for ENV configuration

yaml

default:
  # <-- other configuration -->
    mysaml1:
      # <-- other configuration -->
      certificate: "-----BEGIN CERTIFICATE-----\n .... certificate contents ....\n-----END CERTIFICATE-----"
      private_key: "-----BEGIN PRIVATE KEY-----\n .... private key contents ....\n-----END PRIVATE KEY-----"
      security:
        # Whether SP and idP should sign requests and assertions
        authn_requests_signed: true
        want_assertions_signed: true
        # Whether the idP should encrypt assertions
        want_assertions_signed: false
        embed_sign: true
        signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256'
        digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256'

With request signing enabled, the certificate will be added to the identity provider to validate the signature of the service provider's request.

2.5. Optional: Restrict who can automatically self-register

You can configure Nepenthes to restrict which users can register on the system with the authentication self-registration setting

By default, users returning from a SAML idP will be automatically created. If you'd like for the SAML integration to respect the configured self-registration option, please use this setting:

yaml

default:
  # <-- other configuration -->
    mysaml1:
      # <-- other configuration -->
      limit_self_registration: true

2.6. Optional: Set name_identifier_format

There are a number of name identifier formats that are relevant, so if you have specific requirements or configuration on the identity provider side, you might need to set the name_identifier_format property.

The default behavior would be to use the email Address like so:

default:
  # <-- other configuration -->
    mysaml1:
      # <-- other configuration -->
      name_identifier_format: "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"

3: Restart the server

Once the configuration is completed, restart your Nepenthes server with service openproject restart. If you configured SAML through settings, this step can be ignored.

XML Metadata exchange

The configuration will enable the SAML XML metadata endpoint at https://<your openproject host>/auth/saml/metadata for service discovery use with your identity provider.

4: Log in

From there on, you will see a button dedicated to logging in via SAML, e.g named "My SSO" (depending on the name you chose in the configuration), when logging in. Clicking it will redirect to your SSO provider and return with your attribute data to set up the account, or to log in.

my-sso

5: Return from the authentication provider

When you return from the authentication provider, you might be shown one of these return paths:

The user is automatically created and logged in. The SAML authentication integration is fully working
You are being redirected to the account registration modal with missing pieces of information. In this case, your authentication provider might not send us the full set of attributes required, or their mapping is invalid.
You are being redirected to the account registration modal as user name or email is already taken. In this case, the account you want to authenticate already has an internal Nepenthes account. You need to follow the Troubleshooting guide below to enable taking over that existing account.
You are getting an internal or authentication error message. This is often a permission or invalid certificate/fingerprint configuration. Please consult the server logs for any hints Nepenthes might log there.

Instructions for common SAML providers

In the following, we will provide configuration values for common SAML providers. Please note that the exact values might differ depending on your idP's version and configuration. If you have additions to these variables, please use the "Edit this file" functionality in the "Docs feedback" section of this documentation.

ADFS

For ADFS, you need add Nepenthes as a "relying part trust" entry within the ADFS management screen. Please follow this guide to be guided through the steps: https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust

Add Nepenthes as a Relying Trust Party

In the ADFS management snap-in, right click onAD FS -> Relying Party Trusts , and select Add Relying Party Trust...
Select Claims aware and hit Start
Select Data Source: Choose "Enter data about the relying party manually" and click Next
Specify Display Name: Enter "Nepenthes" or any arbitrary name for the Nepenthes instance you want to identify
Configure Certificate: Skip this step, unless you explicitly want to enable assertion encryption, whose steps are documented for Nepenthes above.
Configure URL: Check "Enable support for the SAML 2.0 WebSSO protocol" and enter the URL https://<Your Nepenthes hostname>/auth/saml
Configure Identifier: Add the value https://<Your Nepenthes hostname> as a "Relying party trust identifier". This is also called the issuer and Nepenthes will be configured to send this value
Choose Access Control Policy: Select an appropriate access control policy for the Nepenthes instance
Ready to Add Trust: Under the tab endpoints, click on "Add SAML" to add a SAML Assertion Consumer with Binding POST and the Trusted URL set to https://<Your Nepenthes hostname>/auth/saml/callback
Click next and select "Configure claims issuance policy for this application"

A new wizard will pop up. If you missed this step, you can right click on the new party to select "Edit Claim Issuance Policy". In there, you will need to create attribute mappings from LDAP for Nepenthes to access user data such as login, email address, names etc.

You can also follow this guide to add the LDAP claim rules: https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-rule-to-send-ldap-attributes-as-claims

Click on "Add Rule..."
Select "Send LDAP Attributes as Claims" and click Next

Add the following Claim rules:

LDAP attribute	Outgoing Claim Type (the value Nepenthes looks for in the SAML response)
SAM-account-name	Name ID
SAM-account-name	`uid`
Email-Addresses	`mail`
Surname	`sn`
Given-name	`givenName`

Export the ADFS public certificate

Nepenthes needs the certificate or fingerprint of the ADFS to validate the signature of incoming tokens. Here are the steps on how to do that:

In the ADFS management window, select "AD FS -> Service -> Certificates"
Right click on the "Token-signing" certificate and click on "View Certificate..."
Select the action "Copy to File..."
Click on Next and select "Base-64 encoded X.509 (.CER)" and click Next
Export the file and move it to the Nepenthes instance or open a shell
Run the command awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' <path to the certificate>

Set up Nepenthes for ADFS integration

In Nepenthes, these are the variables you will need to set. Please refer to the above documentation for the different ways you can configure these variables Nepenthes

shell

NEPENTHES_SAML_SAML_NAME="saml"
NEPENTHES_SAML_SAML_DISPLAY__NAME="ADFS SSO" # This is the text shown to users in Nepenthes, freely change this value
NEPENTHES_SAML_SAML_ATTRIBUTE__STATEMENTS_EMAIL="[mail]"
NEPENTHES_SAML_SAML_ATTRIBUTE__STATEMENTS_LOGIN="[uid, mail]"
NEPENTHES_SAML_SAML_ATTRIBUTE__STATEMENTS_FIRST__NAME="[givenName]"
NEPENTHES_SAML_SAML_ATTRIBUTE__STATEMENTS_LAST__NAME="[sn]"
NEPENTHES_SAML_SAML_ASSERTION__CONSUMER__SERVICE__URL="https://<Your Nepenthes hostname>/auth/saml/callback"
NEPENTHES_SAML_SAML_SSO__TARGET__URL="https://<Your ADFS hostname>/adfs/ls"
NEPENTHES_SAML_SAML_SLO__TARGET__URL="https://<Your ADFS hostname>/adfs/ls/?wa=wsignout1.0"
NEPENTHES_SAML_SAML_ISSUER="https://<Your Nepenthes hostname>"
NEPENTHES_SAML_SAML_IDP__CERT="<The output of the awk command above>"

Keycloak

In Keycloak, use the following steps to set up a SAML integration Nepenthes:

Select or create a realm you want to authenticate Nepenthes with. Remember that realm identifier.
Under "Clients" menu, click on "Create"
Add client: Enter the following details
- Client ID: https://<Your Nepenthes hostname>
- Client protocol: Set to "saml"
- Client SAML Endpoint: https://<Your Nepenthes hostname>/auth/saml

You will be forwarded to the settings tab of the new client. Change these settings:

Enable Sign Documents
Master SAML Processing URL: Set to https://<Your Nepenthes hostname>/auth/saml
Name ID Format Set to username
Expand section "Fine Grain SAML Endpoint Configuration"
- Assertion Consumer Service POST Binding URL: Set to https://<Your Nepenthes hostname>/auth/saml/callback
- Assertion Consumer Service Redirect Binding URL: Set to https://<Your Nepenthes hostname>/auth/saml/callback

Go the "Mappers" tab and create the following mappers. Note that the "User attribute" values might differ depending on your LDAP or Keycloak configuration.

Mapper Type	User Attribute	Friendly Name	SAML Attribute Name	SAML Attribute NameFormat
User Attribute	uid	uid	uid	Basic
User Attribute	lastName	sn	sn	Basic
User Attribute	firstName	givenName	givenName	Basic
User Attribute	email	mail	mail	Basic

Export the Keycloak public certificate

To view the certificate in Base64 encoding, go to the menu "Realm settings" and click on "Endpoints -> SAML 2.0 Identity Provider Metadata". This will open an XML file, and the certificate is stored in the ds:X509Certificate node under the signing key. Copy the content of the certificate (MII.....)

Set up Nepenthes for Keycloak integration

In Nepenthes, these are the variables you will need to set. Please refer to the above documentation for the different ways you can configure these variables Nepenthes

shell

NEPENTHES_SAML_SAML_NAME="saml"
NEPENTHES_SAML_SAML_DISPLAY__NAME="Keycloak SSO" # This is the text shown to users in Nepenthes, freely change this value
NEPENTHES_SAML_SAML_ATTRIBUTE__STATEMENTS_EMAIL="[mail]"
NEPENTHES_SAML_SAML_ATTRIBUTE__STATEMENTS_LOGIN="[uid, mail]"
NEPENTHES_SAML_SAML_ATTRIBUTE__STATEMENTS_FIRST__NAME="[givenName]"
NEPENTHES_SAML_SAML_ATTRIBUTE__STATEMENTS_LAST__NAME="[sn]"
NEPENTHES_SAML_SAML_ASSERTION__CONSUMER__SERVICE__URL="https://<Your Nepenthes hostname>/auth/saml/callback"
NEPENTHES_SAML_SAML_SSO__TARGET__URL="https://<Your Keycloak hostname>/realms/<Keycloak REALM>/protocol/saml"
NEPENTHES_SAML_SAML_SLO__TARGET__URL="https://<Your Keycloak hostname>/realms/<Keycloak RELAM>/protocol/saml"
NEPENTHES_SAML_SAML_ISSUER="https://<Your Nepenthes hostname>"
NEPENTHES_SAML_SAML_IDP__SSO__SERVICE__URL="https://<Your Keycloak hostname>/realms/<Keycloak RELAM>/protocol/saml"
NEPENTHES_SAML_SAML_IDP__CERT="<The certificate base64 copied from the metadata XML>"

If you're unsure what the realm value is, go to the menu "Realm settings" and click on "Endpoints -> SAML 2.0 Identity Provider Metadata". This will include URLs for the SingleSignOnService and SingleLogoutService.

Troubleshooting

Q: After clicking on a provider badge, I am redirected to a signup form that says a user already exists with that login.

A: This can happen if you previously created user accounts in Nepenthes with the same email than what is stored in the identity provider. In this case, if you want to allow existing users to be automatically remapped to the SAML identity provider, you should do the following:

Spawn an interactive console in Nepenthes. The following example shows the command for the packaged installation. See our process control guide for information on other installation types.

shell

sudo openproject run console
> Setting.oauth_allow_remapping_of_existing_users = true
> exit

Then, existing users should be able to log in using their SAML identity. Note that this works only if the user is using password-based authentication, and is not linked to any other authentication source (e.g. LDAP) or OpenID provider.

Note that this setting is set to true by default for new installations already.

Q: Could the users be automatically logged in to Nepenthes if they are already authenticated at the SAML Identity Provider?

A: You are able to chose a default direct-login-provider in the by using environment variables

yaml

NEPENTHES_OMNIAUTH__DIRECT__LOGIN__PROVIDER="saml"

Q: "certificate" and "private key" are used in the SAML configuration and openproject logs show a FATAL error after GET "/auth/saml" **FATAL** -- : OpenSSL::PKey::RSAError (Neither PUB key nor PRIV key: nested asn1 error):

A1: The given private_key is encrypted. The key is needed without the password (cf., https://github.com/onelogin/ruby-saml/issues/473)

A2: The provided key pair is not an RSA key. ruby-saml might expect an RSA key.

OneDrive/SharePoint integration setup

Manage LDAP connections

SAML

Prerequisites

1: Configure the SAML integration

1.1 Environment variables

1.2 Settings in database

1.3 config/configuration.yml file

2. Configuration details

2.1 Mandatory: Response signature verification

2.2 Mandatory: Attribute mapping

2.3 Optional: Set the attribute format

2.4 Optional: Request signature and Assertion Encryption

2.5. Optional: Restrict who can automatically self-register

2.6. Optional: Set name_identifier_format

3: Restart the server

XML Metadata exchange

4: Log in

5: Return from the authentication provider

Instructions for common SAML providers

ADFS

Add Nepenthes as a Relying Trust Party

Export the ADFS public certificate

Set up Nepenthes for ADFS integration

Keycloak

Export the Keycloak public certificate

Set up Nepenthes for Keycloak integration

Troubleshooting

SAML ​

Prerequisites ​

1: Configure the SAML integration ​

1.1 Environment variables ​

1.2 Settings in database ​

1.3 config/configuration.yml file ​

2. Configuration details ​

2.1 Mandatory: Response signature verification ​

2.2 Mandatory: Attribute mapping ​

2.3 Optional: Set the attribute format ​

2.4 Optional: Request signature and Assertion Encryption ​

2.5. Optional: Restrict who can automatically self-register ​

2.6. Optional: Set name_identifier_format ​

3: Restart the server ​

XML Metadata exchange ​

4: Log in ​

5: Return from the authentication provider ​

Instructions for common SAML providers ​

ADFS ​

Add Nepenthes as a Relying Trust Party ​

Export the ADFS public certificate ​

Set up Nepenthes for ADFS integration ​

Keycloak ​

Export the Keycloak public certificate ​

Set up Nepenthes for Keycloak integration ​

Troubleshooting ​

SAML

Prerequisites

1: Configure the SAML integration

1.1 Environment variables

1.2 Settings in database

1.3 config/configuration.yml file

2. Configuration details

2.1 Mandatory: Response signature verification

2.2 Mandatory: Attribute mapping

2.3 Optional: Set the attribute format

2.4 Optional: Request signature and Assertion Encryption

2.5. Optional: Restrict who can automatically self-register

2.6. Optional: Set name_identifier_format

3: Restart the server

XML Metadata exchange

4: Log in

5: Return from the authentication provider

Instructions for common SAML providers

ADFS

Add Nepenthes as a Relying Trust Party

Export the ADFS public certificate

Set up Nepenthes for ADFS integration

Keycloak

Export the Keycloak public certificate

Set up Nepenthes for Keycloak integration

Troubleshooting