Stages Documentation

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
75:integration:saml [2023/02/21 19:29] – [Validated IdP Vendors] emr75:integration:saml [2024/02/15 00:00] (current) – external edit 127.0.0.1
Line 9: Line 9:
 ===== Restrictions ===== ===== Restrictions =====
  
-Stages currently supports single sign on (SSO) ** only with one **  SAML server. +Stages currently supports single sign on (SSO) ** only with one ** SAML server.
 ===== Generate a signing key ===== ===== Generate a signing key =====
  
-If you already have a SSL server certificate for Stages, you can use that certificate to sign the SAML requests. If you use encrypted SAML assertions - a separate certificate is required. If you do not have a certificate or you want to use a separate certificate, use the follwing command:<code>+If you already have a SSL server certificate for Stages, you can use that certificate to sign the SAML requests. If you use encrypted SAML assertions - a separate certificate is required. If you do not have a certificate or you want to use a separate certificate, use the follwing command: 
 +<code>
  
 keytool -genkeypair -alias "samlkeyalias" -keyalg RSA -keysize 2048 -validity 1095 -keystore "conf/saml-keystore.jks" keytool -genkeypair -alias "samlkeyalias" -keyalg RSA -keysize 2048 -validity 1095 -keystore "conf/saml-keystore.jks"
Line 19: Line 19:
 </code> </code>
  
-Enter your Stages URL when asked for the First and Last Name. The rest of the parameters can be set arbitrarily.+Enter your Stages Domain Name when asked for the First and Last Name. The rest of the parameters can be set arbitrarily.
  
 You can choose an arbitrary key name (e.g. ''samlkeyalias'') and location for the keystore (e.g. ''conf/saml-keystore.jks''), they just need to be the same as you configure below. You can choose an arbitrary key name (e.g. ''samlkeyalias'') and location for the keystore (e.g. ''conf/saml-keystore.jks''), they just need to be the same as you configure below.
Line 28: Line 28:
 <authentication <authentication
      enabled="true"      enabled="true"
-     keystore="/opt/stages/conf/saml-keystore.jks"+     keystoreFile="/opt/stages/conf/saml-keystore.jks"
      keystorePass="changeit">      keystorePass="changeit">
    ...    ...
Line 36: Line 36:
  
 To globally enable SAML, set the ''enabled ''attribute to true. The keystore location and password need to match the keystore from above or your SSL server certificate location. To globally enable SAML, set the ''enabled ''attribute to true. The keystore location and password need to match the keystore from above or your SSL server certificate location.
 +
 +
 ===== Configure the SAML Service Provider (SP) ===== ===== Configure the SAML Service Provider (SP) =====
  
Line 64: Line 66:
 ===== Generate the SAML SP metadata ===== ===== Generate the SAML SP metadata =====
  
-After configuring the SAML SP, you can download the SAML SP metadata directly by navigating to the URL ''[[http://<yourstages|http://<yourstages]]>/stages/rest/saml/metadata''+After configuring the SAML SP and logged on as root, you can download the SAML SP metadata directly by navigating to the URL ''[[http://<yourstages|https://<yourstages]]>/stages/rest/saml/metadata''
  
 The resulting XML file can be sent to the SAML IdP administrators and contains all information necessary to set up the trust relationship on the IdP side. After the SAML IdP has been configured with the SP metadata, users will be able to authenticate successfully with Stages through the SAML IdP. The resulting XML file can be sent to the SAML IdP administrators and contains all information necessary to set up the trust relationship on the IdP side. After the SAML IdP has been configured with the SP metadata, users will be able to authenticate successfully with Stages through the SAML IdP.
  
 =====   ===== =====   =====
 +
  
 ===== Configure the SAML Identity Provider (IdP) ===== ===== Configure the SAML Identity Provider (IdP) =====
Line 86: Line 89:
   * EMailAddress   * EMailAddress
  
-for the following configuration:<code>+for the following configuration: 
 +<code>
  
 <authentication> <authentication>
Line 95: Line 99:
         providerUrl="<SingleSignOnServiceLocationFromMetadata>"         providerUrl="<SingleSignOnServiceLocationFromMetadata>"
         nameIdPolicyFormat="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"         nameIdPolicyFormat="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
 +        sendBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
         userFullnameTemplate="%firstname% %lastname%">         userFullnameTemplate="%firstname% %lastname%">
  
Line 179: Line 184:
  
 After you configured the service provider and identity provider in ''config.xml'', update the configuration via "''stages update''" and restart the Stages service. After you configured the service provider and identity provider in ''config.xml'', update the configuration via "''stages update''" and restart the Stages service.
 +
 +
 +===== Changing the license pool and license type for existing users =====
 +
 +By default, existing users are not modified by the SAML authentication process when the SAML configuration was changed after the user had been created. However, you can set the ''forceLicensePoolReassignment''  attribute on an ''identity-provider-attribute-match''  to ''true''  if you want changes of the ''licensePoolIdent''  or ''defaultLicenseType''  attributes to be applied to existing users.
  
 ===== Configuring Stages attributes in default-matcher section with JavaScript ===== ===== Configuring Stages attributes in default-matcher section with JavaScript =====
Line 207: Line 217:
 </code> </code>
  
-**JavaScript notation of value conditions:** \\  \\+**JavaScript notation of value conditions:** 
 + 
 +SAML Attributes that are defined via identity_provider_attribute elements can be used in these scripts. E.g. 
 + 
 +<code> 
 +<identity-provider-attribute name="email" id="<EMailAddress>" /> 
 + 
 +</code> 
 + 
 +<code>
 Attribute contains value: Attribute contains value:
 +
 +</code>
  
 <code> <code>
-<saml_attribute>.match(/.*value/)+<saml_attribute_id>.match(/.*value/)         // <= 7.9.10.0, <= 7.10.1.0 
 +<saml_attribute_name>.match(/.*value/)       //> 7.9.10.0,> 7.10.1.0
  
 </code> </code>
Line 218: Line 240:
  
 <code> <code>
-<saml_attribute>=="value+<saml_attribute_id>=="value                 // <= 7.9.10.0, <= 7.10.1.0 
 +<saml_attribute_name>=="value               //> 7.9.10.0,> 7.10.1.0
  
 </code> </code>
  
-**Example configuration:** \\  \\ +**Example configuration:** \\  \\ This example creates Stages users with the following conditions:
-This example creates Stages users with the following conditions:+
  
   * The pattern matches the entry of the SAML attribute "id".   * The pattern matches the entry of the SAML attribute "id".
-  * Depending on the users' email address (domain-part), SAML attribute "mail" is used to assign different values for defaultRolesUsername, defaultLicenseType and licensePoolIdent+  * Depending on the users' email address (domain-part), SAML attribute name "email" is used to assign different values for defaultRolesUsername, defaultLicenseType and licensePoolIdent
  
 <code> <code>
 <identity-provider-attribute-match <identity-provider-attribute-match
-     id="<saml_attribute>"+     id="<saml_attribute_id>"
      pattern="<matching_value>"      pattern="<matching_value>"
      defaultRolesUsername="=      defaultRolesUsername="=
-        if (mail.match(/.*@company1.com/)) 'User1'; +        if (email.match(/.*@company1.com/)) 'User1'; 
-        else if (mail.match(/.*@company2.com/)) 'User2';+        else if (email.match(/.*@company2.com/)) 'User2';
         else 'default';         else 'default';
         "         "
      defaultLicenseType="=      defaultLicenseType="=
-        if (mail.match(/.*@company1.com/)) 'QM'; +        if (email.match(/.*@company1.com/)) 'QM'; 
-        else if (mail.match(/.*@company2.com/)) 'PM';+        else if (email.match(/.*@company2.com/)) 'PM';
         else 'none';         else 'none';
         "         "
      licensePoolIdent="=      licensePoolIdent="=
-          if (mail.match(/.*@company2.com/)) 'company2';+          if (email.match(/.*@company2.com/)) 'company2';
         else '';         else '';
         "         "
Line 250: Line 272:
  
 </code> </code>
 +
 +Please note that the values of multi value attributes are provided to the scripts as one value as a comma separated string.
  
 =====   ===== =====   =====
 +
  
 ===== Configure the SAML Request Type ===== ===== Configure the SAML Request Type =====
Line 270: Line 295:
 Stages SAML has successfully been deployed with the following IdP servers: Stages SAML has successfully been deployed with the following IdP servers:
  
 +  * Azure AD IdP
 +  * Okta
 +  * JumpCloud
   * Cisco Central Web Authentication (CWA)   * Cisco Central Web Authentication (CWA)
   * Oracle Access Manager (OAM)   * Oracle Access Manager (OAM)
   * Shibboleth IdP   * Shibboleth IdP
   * Active Directory Federation Services (ADFS)   * Active Directory Federation Services (ADFS)
-  * Azure AD IdP 
-  * Okta 
-  * JumpCloud 
  
 Please let us know if you were able to make Stages SAML work with your server and it is not on this list yet. Please let us know if you were able to make Stages SAML work with your server and it is not on this list yet.