Overview

This document will demontrate how to install and configure RCDevs Identity Provider (IDP) for SAML and OpenID Connect (OIDC) Service Provider (SP) integrations. Authentication on the IDP is done through the OpenOTP authentication server. The RCDevs IDP is a web application installed on all WebADM servers part of the same cluster. The IDP portal can be published through WebADM Publishing Proxy (WAProxy) or your reverse proxy to be publicly accessible.
OpenID/SAML application logs are accessible from the Databases menu of WebADM > WebADM Server Log file or WebADM Shared event log.
Note: To be able to use OpenID/SAML, any LDAP users' accounts must be a activated in WebADM.
You can embed the OpenID & SAML Provider Webapp on your website in an HTML iFrame or Object.

#Example
<object data="https://<webadm_addr>/webapps/openid?inline=1" />

For this setup, you need to have a WebADM and OpenOTP server already installed and configured.

Package installation

Installation with Redhat Repository

On a RPM based systems, you can use RCDevs repository.
Clear the dnf cache and install the OpenID & SAML provider (openid) package:

dnf clean all
dnf install openid -y

RCDevs Identity Provider package is now installed.

Installation with Debian Repository

On a Debian-like system, you can use RCDevs repository.
Clear apt cache and install the OpenID & SAML provider (openid) package:

apt update
apt install openid

RCDevs Identity Provider package is now installed.

Installation with the Self-Installer

Download the RCDevs Identity Provider self-installer package from the RCDevs website and copy the downloaded archive to your server(s). To install the OpenID & SAML provider, log in to your WebADM server through SSH and run the following commands to uncompress and install it:

gunzip openid-1.6.x.sh.gz
bash openid-1.6.x.sh

Once the openid package is installed, you can login on WebADM Administrator Portal as super_admins to configure it.

OpenID & SAML Identity Provider configuration

Log in to the WebADM Administrator Portal, click on the Applications tab, and navigate to the Single Sign-On category. The OpenID & SAML Provider should appear there with a status of Not Registered.

openid

Click on the REGISTER button to create the corresponding LDAP object which will contain the web application configuration.

Next, navigate back to the WebADM Administrator Portal, click the Applications tab, and select Single Sign-On from the Categories.

Click the CONFIGURE button next to OpenID & SAML Provider to configure the web application and its services.

openid

Web Application Settings and Common Features

You are now in the global configuration of your OpenID & SAML Provider.

openid

The first section of settings is common across all web applications. Configure the settings you would like to apply.

Scroll down, and you are now entering in the Common Features section. The Common Features section includes common settings for OpenID and SAML Providers.

openid

  • The Issuer URL or EntityID is a unique identifier that is used to identify a specific entity in the SAML authentication and authorization protocol. A SAML entity ID is typically a URL or URI that is assigned to the entity, and it is used to identify the entity in SAML messages and metadata. That setting will refer to Issuer value for OpenID. In that documentation, I configured my Issuer URL with the public DNS name targeting my WebADM infrastructure. In most of the case, the IDP URL will be a public URL which can be easily proxied with WebADM Publishing Proxy or with another reverse proxy solution. Be careful that the latter must allow the big URI query strings that are sometimes necessary in SAML, so e.g. users of AWS WAF should change SizeRestrictions_QUERYSTRING to Allow or Count.

  • The Name Identifier setting is the unique identifier of the user. It should be non-volatile and opaque. It should not contain personal information or information that is changeable over time, such as the user's name or email address. The accepted Name Identifier may vary according to the Service Provider you are integrating and for that reason it can make more sens to configure it per Service Provider through Client Policies.

  • The SSO Session Time define the time for a user session remains valid on the IDP.

  • The Allow Management setting provides the possibility to your end-users to enable/disable the SAML/OpenID usage for their account and configure their SSO Session timeout. It is recommanded to disabled that setting by default.

  • The Returned Groups Filter is a regular expression which can be configured in order to filter groups returned in the SAML or OpenID responses based on the RegEx match.

  • The Server Certificate and Server Private Key settings are mandatory and will be used for request signing purposes. Click Edit and Generate buttons, then a certificate with Rsignd internal PKI is issued.

openid

Now that we have the IdP certificate, click on Apply, and the Server Certificate and Private Key will be auto-filled in the configuration.

openid
openid

You can also issue a certificate with another Enterprise CA if desired. Note that when the IdP certificate expires, you may need to update the configuration with the newly issued IdP certificate on the integrated service providers.

The Common Features section is now configured. Save your configuration by clicking Apply.

SAML Service Configuration

We are now entering in the SAML dedicated configuration.

openid

  • The Enable SAML Usage setting enable the SAML configuration in order to implement SP through SAML.

  • The UserID Mapping setting is the attribut value used in the SAML response to return the user ID.

  • The Domain Mapping setting is the attribut value used in the SAML response to return the domain value. By default, the WebADM domain name is returned based on the domain used to authenticate the user.

  • The Email Mapping setting is the attribut value used in the SAML response to return the users' email value(s).

  • The Group Mapping setting is the attribut value used in the SAML response to return the user group memberships.

  • The Return attributes setting is the attribut value used in the SAML response to return a list of desired attributs. You can also manipulate values returned. For example here, I returned in SAML response mobile, displayname sn attributs retrieved from the LDAP account and in userprincipalname I put the user email value.

  • The Holder of Key setting is used to include the user certificate and use 'holder-of-key' assertion confirmation method. If not enabled or the user does not have a certificate, the method defaults to 'bearer'.

  • The Sign Entire SAML Response setting is used to intirely sign the SAML response. This can be an option on some service provider. By default, the IdP signs the XML assersion and the subject.

  • The Consumer URL Protection is a security setting used to refuse SAML requests containing AssertionConsumerServiceURL which do not match the Issuer URL hostname present in the same request.

  • The Consumer URL Exception setting can be used when the AssertionConsumerServiceURL present in the SAML request do not match the SP issuer URL.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:AuthnRequest AssertionConsumerServiceURL="https://system.netsuite.com/saml2/acs"
                     Destination="https://sso.rcdevsdocs.com/openid/index.php"
                     ForceAuthn="false"
                     ID="_184481c4dc4698ff64574278aa43d60"
                     IsPassive="false"
                     IssueInstant="2023-11-09T14:26:25.059Z"
                     ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                     Version="2.0"
                     xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol">
  <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">http://www.netsuite.com/sp</saml2:Issuer>
  <saml2p:NameIDPolicy AllowCreate="true"
                       Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
                       SPNameQualifier="http://www.netsuite.com/sp" />

</saml2p:AuthnRequest>

In that example, the AssertionConsumerServiceURL (system.netsuite.com) do not match the Issuer (netsuite.com).
I can then configure a Consumer URL Exceptions like this:

openid

By default, the AssertionConsumerServiceURL is taken from the SAML request and is used by the IDP after the user authentication to redirect the user to the service provider. The AssertionConsumerServiceURL can be rewrite by client policy if needed. If multiple AssertionConsumerServiceURL are available on your service provider, then you can also use the Consumer URL Exception and configure a regex that will match all URLs.

Another usecase when the Issuer value is not an URL, you can define an exception based on the whole AssertionConsumerServiceURL available in the SAML request or define a regex matching mutliple AssertionConsumerServiceURL.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:AuthnRequest AssertionConsumerServiceURL="https://cognito.amazon.com/saml2/idpresponse"
                     Destination="https://sso.rcdevsdocs.com/openid/index.php"
                     ID="_5696fc7f-392d-4eee-b870-4ab41dd6aa17"
                     IssueInstant="2024-04-17T13:54:09.966Z"
                     Version="2.0"
                     xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol">
  <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity"
                xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">urn:amazon:cognito:sp:eu-west-3_OMrbaByvF</saml2:Issuer>
</saml2p:AuthnRequest>

I can define as https://cognito.amazon.com/saml2/idpresponse in the Consumer URL Exception setting or a RegEx like /.*amazon.*/.

  • The Content Security Headers setting can be used to enforce content security header protection for POST redirections.

You can now save your SAML configuration. The SAML metadata URL is accessible through WebADM servers and through WAProxy servers if the Web Application is published through WAPRoxy:

<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://sso.rcdevsdocs.com">
<IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<KeyDescriptor use="signing">
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<X509Data>
<X509Certificate>MIIGfzCCBGegAwIBAgIRAM9/TyvDiZAahDgzYkWGRdIwDQYJKoZIhvcNAQELBQAwUjEXMBUGA1UEAwwOUkNEZXZzIERvY3MgQ0ExCzAJBgNVBAsMAkNBMR0wGwYDVQQKDBRSQ0RldnMgRG9jdW1lbnRhdGlvbjELMAkGA1UEBhMCTFUwHhcNMjQwNzE1MTM0OTA3WhcNMzQwNzEzMTM0OTA3WjBgMRswGQYDVQQDDBJXZWJBRE0gQ2VydGlmaWNhdGUxDzANBgNVBA0MBlNFUlZFUjEXMBUGA1UECgwOUkNEZXZzIFN1cHBvcnQxFzAVBgNVBGEMDlZBVExVLTAwMDAwMDAwMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA1w3PR1Q+78jdD12g4Di3ljcthoZwvpQuwmuOm/+fBthQjrHR1UIY3HDkulCOYpBRiNNj6ED49eyF9jIeO/zVO5QXnzX4gmasZPd06ZYAD8pkDc7fnnxZD4aSHDKQcF1xwUnHESUCPzWR1Wy3t6ifwl85uRuC+QlskMv4t82LqeMQeSBdeBqNpADm9Hmg8AO5BK4Oz/NNooB46P5RYDEerY1D/qOfLkuzEDr2C2Z1rGvtG7+7EpaS+b9Ipnz/fT71QACPxJym98YWEp/1Fb/clC6QLKQuQ+AzheTVZyyeOhOYFxsoGEu+wDFAERXWWAr5sPnayDJiZdXbH+712ri35y9oFWOxZC1diATOS/MRc05bAzgAbyiQe1PrhDfwRiL4YF0EtLvuZJGBH031DZS3THdYSeONDhsImbNYFYLPpzRqb5iXssN+KBPAdCfYJ2IMfjAV4li0s1WSC40iZ5MAkwovE0HD++DVO2HHBJ9hYl6aqa35lGm/QSjkUYvw2xX3kvc3utPQcqUkYDWzF7tLIMpTzO6FtD1pR/FR6DKkqmx9NhLMdIi9eNGK4MG+MgKwCXhE1I6aJxVoRCbAihb0wgnR+Y38P4bJUYzvDCC4upE3DLc+ct5VJ/rtCo9UDyVQGsLDD9cDoywdr6feM/Pou+LpccVNAHul1FJ9CPKxyVECAwEAAaOCAUAwggE8MAsGA1UdDwQEAwIF4DATBgNVHSUEDDAKBggrBgEFBQcDATCBygYIKwYBBQUHAQEEgb0wgbowJgYIKwYBBQUHMAGGGmh0dHA6Ly8xOTIuMTY4LjQuMTYwL29jc3AvMCYGCCsGAQUFBzABhhpodHRwOi8vMTkyLjE2OC40LjE2MS9vY3NwLzAzBggrBgEFBQcwAoYnaHR0cDovLzE5Mi4xNjguNC4xNjAvY2FjZXJ0Lz9mb3JtYXQ9ZGVyMDMGCCsGAQUFBzAChidodHRwOi8vMTkyLjE2OC40LjE2MS9jYWNlcnQvP2Zvcm1hdD1kZXIwSwYDVR0fBEQwQjAfoB2gG4YZaHR0cDovLzE5Mi4xNjguNC4xNjAvY3JsLzAfoB2gG4YZaHR0cDovLzE5Mi4xNjguNC4xNjEvY3JsLzANBgkqhkiG9w0BAQsFAAOCAgEACy/zl7IPSaOn2wEZ66xQNxm9FW408jMrQS2Y6hFvfzRMNhbOh+ZwNFSgCijUJ4ASZVQeZIiYN8f/quH80Y7AJE3kcTpXvJE2LozDbUMsXe0GpkNuzDojbp3K2ZcgUitL0q/rDHPBXXExl1AEhPgpwN1I7ZyHPfZpU92XxcsoSrUi8AMmzoVwlna30RMkkCDDBsf+an1uxdrdwMQLeQddOFddAUI80NWvh0drnv1epkT34K+RpvEAU514a3suErDMIqp+h7BqTdPrdiRkIhTutgSsPquhGIDzv+WvGBzFGWPAfudQHE5jMn3lPgN3r75HrdNfMkVEv0jclpp3VhiUnwQzNQn2UzVe7LQh8ixjEg1kwtIQ8UuwX6LOZ7a51WuKkRfS1iw1yDCM1UmGNuoMGqI6bxwFbBZ1C3brgJKjXBciEpXrSpcJ+ulhDYYUrCmGnpg6xyJ6veWfT2tVExLcffv4edT0KCJuKsyTztLFtT9A9ihyV/lPBsVUtIipe2CaCXupP84812s0cgo6XkcAr99pvtPNLZg9aBLuVt7GmyJSQeLJ6z+QWlkKnsEh7HlSrV2RC/wsTYlTeTRZFmiNa1RGx4UsNyTf9Igp+EG4Nh/UBhGO1Jkn1dIRZyb/qgcF/DWCSdbwFIKxuaKA12KFJMFS4aMV1e0QLDhLfpZ1/10=</X509Certificate>
<!--  Cert Fingerprint (SHA1): 32774463a2e892150f46852b3fdcac7f5be924dc  -->
<!--  Cert Fingerprint (SHA256): e0bd10584f5c3a554e279b9241619e8fdf9c3bfbe95c90da939f0342546e52ac  -->
<!--  Cert Fingerprint (MD5): 639ed5b4241047c8382f897fc459a714  -->
</X509Data>
</KeyInfo>
</KeyDescriptor>
<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://webadm1.rcdevsdocs.com/webapps/openid/index.php"/>
<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://webadm1.rcdevsdocs.com/webapps/openid/index.php"/>
<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://webadm1.rcdevsdocs.com/webapps/openid/index.php"/>
<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://webadm1.rcdevsdocs.com/webapps/openid/index.php"/>
</IDPSSODescriptor>
</EntityDescriptor>

The SAML clients (Service Providers) need to know about the SAML IdP endpoints. Most clients will accept the autoconfiguration with an XML-based metadata URL. You can provide the previous URLs according to your scenario.

Many SAML SP will require your IDP endpoint to be run with a trusted SSL certificate.

OpenID Configuration

The configuration of the OpenID service is very simple. Version 1.2.x includes support for OpenID-Connect and OAuth2.

To use your identity provider in OpenID-Connect mode, the client configuration must include the scope openid in the IdP requests. The supported OpenID-Connect scopes are: basic, email, phone, profile, and groups.

To use your identity provider in OAuth2 mode, the client must include the scope profile in the IdP requests.

If your client application needs the user’s email address, you can additionally request the openid email scope.

The allowed scopes must be enabled in the global configuration or per client policy in order to be returned to the service providers that request them.

openid

The OpenID metadata URL is accessible through WebADM servers and through WAProxy servers if the Web Application is published through WAPRoxy:

Which is returning the following in my scenario:

{
    "issuer": "https://sso.rcdevsdocs.com",
    "authorization_endpoint": "https://sso.rcdevsdocs.com/openid/index.php",
    "token_endpoint": "https://sso.rcdevsdocs.com/openid/index.php",
    "userinfo_endpoint": "https://sso.rcdevsdocs.com/openid/index.php",
    "jwks_uri": "https://sso.rcdevsdocs.com/openid/certs.php",
    "subject_types_supported": [
        "public",
        "pairwise"
    ],
    "response_types_supported": [
        "code",
        "token",
        "id_token"
    ],
    "response_modes_supported": [
        "query",
        "fragment",
        "form_post"
    ],
    "id_token_signing_alg_values_supported": [
        "RS256"
    ],
    "scope_supported": [
        "basic",
        "openid",
        "email",
        "phone",
        "profile",
        "groups"
    ],
    "claims_supported": [
        "sub",
        "email",
        "email_verified",
        "phone_number",
        "phone_number_verified",
        "preferred_username",
        "preferred_language",
        "given_name",
        "family_name",
        "name",
        "groups",
        "mfa-policy"
    ]
}

The global configuration of your Identity Provider is complete. Browse the next documentation in the Single Sign-On section to explore examples of Service Provider integrations.