Stages Documentation

Differences

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

Link to this comparison view

Next revision		Previous revision
712:integration:saml [2025/09/15 14:55] – created - external edit 127.0.0.1712:integration:saml [2026/02/20 14:02] (current) – [Configure the SAML Identity Provider (IdP)] Suess, Bernhard
Line 48: Line 48:
  
         <service-provider         <service-provider
-                        providerId="<yourStagesURL>"+                        providerId="yourStagesURL"
                         keyAlias="samlkeyalias">                         keyAlias="samlkeyalias">
  
Line 67: Line 67:
  
 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'' 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''
 +
 +For SP metadata generated correctly the whole authentication section must be present in config.xml : [[https://doc.stagesasaservice.com/712/integration/saml#configure-the-saml-identity-provider-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. 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.
Line 83: Line 85:
   * EntityIdfromMetadata   * EntityIdfromMetadata
  
-  * SingleSignOnServiceLocationFromMetadata (should be HTTPS, please see [[:general:saml-note-samesite|]])+  * SingleSignOnServiceLocationFromMetadata (should be HTTPS, please see [[:general:saml-note-samesite]])
  
   * DisplayName (alternative: FirstName, LastName)   * DisplayName (alternative: FirstName, LastName)
Line 90: Line 92:
  
 for the following configuration: for the following configuration:
-<code> 
  
-<authentication> +<code -> 
-    ...+<authentication 
 +     enabled="true" 
 +     keystoreFile="/opt/stages/conf/saml-keystore.jks" 
 +     keystorePass="changeit"> 
 + 
 +    <service-provider 
 +         providerId="yourStagesURL" 
 +         keyAlias="samlkeyalias"> 
 + 
 +    </service-provider>
  
     <identity-provider     <identity-provider
-        providerId="<EntityIDfromMetadata>" +        providerId="EntityIDfromMetadata" 
-        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"         sendBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
Line 110: Line 120:
  
         <!-- either "fullname" or "firstname" and "lastname" need to be defined -->         <!-- either "fullname" or "firstname" and "lastname" need to be defined -->
-        <!--<identity-provider-attribute name="fullname" id="<DisplayName>" />--> +        <!--<identity-provider-attribute name="fullname" id="DisplayName" />--> 
-        <identity-provider-attribute name="firstname" id="<FirstName>" /> +        <identity-provider-attribute name="firstname" id="FirstName" /> 
-        <identity-provider-attribute name="lastname" id="<LastName>" />+        <identity-provider-attribute name="lastname" id="LastName" />
  
-        <identity-provider-attribute name="email" id="<EMailAddress>" />+        <identity-provider-attribute name="email" id="EMailAddress" />
  
         <!-- This matches if the SAML assertion contains a SAML attribute "Organization" with value "External" -->         <!-- This matches if the SAML assertion contains a SAML attribute "Organization" with value "External" -->
Line 146: Line 156:
         -->         -->
         <certificate use="signing">${saml.idp.signatureCertificate}         <certificate use="signing">${saml.idp.signatureCertificate}
-MIIDCTCC... 
  
-       <Insert the X509Certificate "signing" key from the metadata here> +       <!-- MIIDCTCC...Qwgf5bXby+ug==   -->
- +
-...Qwgf5bXby+ug==+
         </certificate>         </certificate>
  
Line 157: Line 164:
              encryption certifacte. The key data can also be copied from the              encryption certifacte. The key data can also be copied from the
              IdP metadata. If no encryption certificate is specified, no encrypted              IdP metadata. If no encryption certificate is specified, no encrypted
-             assertion can be accepted. --> +             assertion can be accepted. 
-        <certificate use="''encryption''"> +        --> 
-MIIDCTCC... +        <certificate use="encryption">${saml.idp.encryptionCertificate} 
- +                <!-- MIIDCTCC...Qwgf5bXby+ug==  --> 
-        <Insert the X509Certificate "encryption" key from the metadata here> +       </certificate>
- +
-...Qwgf5bXby+ug== </certificate> +
-        </certificate>+
     </identity-provider>     </identity-provider>
  
Line 180: Line 184:
     <identity-provider providerId="STAGES"/>     <identity-provider providerId="STAGES"/>
 </authentication> </authentication>
- 
 </code> </code>
  
-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 ===== ===== 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.+''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 =====
  
-JavaScript control flow statements (e.g. "if","switch") can be used to configure values for Stages attributes. All assertion attributes of the SAML response are accessible as variables and can be used in the JavaScript expression+''JavaScript control flow statements (e.g. "if","switch") can be used to configure values for Stages attributes. All assertion attributes of the SAML response are accessible as variables and can be used in the JavaScript expression  JavaScript expressions can be used with the following Stages attributes:    * defaultRolesUsername   * defaultLicenseType   * licensePoolIdent  **General JavaScript expression notation:**  <code> <Stages_attribute>="=<JavaScript_expression>"  </code>  **JavaScript notation of if-clauses:**  <code> if (condition1) 'returnValue1'; else if (condition2) 'returnValue2'; else if (condition3) 'returnValue3'; else 'returnValue4';  </code>  **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:  </code>  <code> <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>  Attribute equals value:  <code> <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>  **Names of license types for license assignment**  ^License name^License type^ |Modeler|QM| |Contributor|FloatingADev| |Participant|FloatingDev| |Project Manager|FloatingPM| |Viewer|AuthPsReader|  **Example configuration:** ''\\ '' ''\\ ''This example creates Stages users with the following conditions:    * The pattern matches the entry of the SAML attribute "id".   * Depending on the users' email address (domain-part), SAML attribute name "email" is used to assign different values for defaultRolesUsername, defaultLicenseType and licensePoolIdent  <code> <identity-provider-attribute-match      id="<saml_attribute_id>"      pattern="<matching_value>"      defaultRolesUsername="=         if (email.match(/.*@company1.com/)) 'User1';         else if (email.match(/.*@company2.com/)) 'User2';         else 'default';         "      defaultLicenseType="=         if (email.match(/.*@company1.com/)) 'QM';         else if (email.match(/.*@company2.com/)) 'PM';         else 'none';         "      licensePoolIdent="=           if (email.match(/.*@company2.com/)) 'company2';         else '';
  
-JavaScript expressions can be used with the following Stages attributes: 
- 
-  * defaultRolesUsername 
-  * defaultLicenseType 
-  * licensePoolIdent 
- 
-**General JavaScript expression notation:** 
- 
-<code> 
-<Stages_attribute>="=<JavaScript_expression>" 
- 
-</code> 
- 
-**JavaScript notation of if-clauses:** 
- 
-<code> 
-if (condition1) 'returnValue1'; 
-else if (condition2) 'returnValue2'; 
-else if (condition3) 'returnValue3'; 
-else 'returnValue4'; 
- 
-</code> 
- 
-**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: 
- 
-</code> 
- 
-<code> 
-<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> 
- 
-Attribute equals value: 
- 
-<code> 
-<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> 
- 
-**Names of license types for license assignment** 
- 
-^License name^License type^ 
-|Modeler|QM| 
-|Contributor|FloatingADev| 
-|Participant|FloatingDev| 
-|Project Manager|FloatingPM| 
-|Viewer|AuthPsReader| 
- 
-**Example configuration:** \\  \\ This example creates Stages users with the following conditions: 
- 
-  * The pattern matches the entry of the SAML attribute "id". 
-  * Depending on the users' email address (domain-part), SAML attribute name "email" is used to assign different values for defaultRolesUsername, defaultLicenseType and licensePoolIdent 
- 
-<code> 
-<identity-provider-attribute-match 
-     id="<saml_attribute_id>" 
-     pattern="<matching_value>" 
-     defaultRolesUsername="= 
-        if (email.match(/.*@company1.com/)) 'User1'; 
-        else if (email.match(/.*@company2.com/)) 'User2'; 
-        else 'default'; 
-        " 
-     defaultLicenseType="= 
-        if (email.match(/.*@company1.com/)) 'QM'; 
-        else if (email.match(/.*@company2.com/)) 'PM'; 
-        else 'none'; 
-        " 
-     licensePoolIdent="= 
-          if (email.match(/.*@company2.com/)) 'company2'; 
-        else ''; 
         "         "
      autocreateUser="true"      autocreateUser="true"
 +
 /> />
  
Line 283: Line 204:
  
 Please note that the values of multi value attributes are provided to the scripts as one value as a comma separated string. Please note that the values of multi value attributes are provided to the scripts as one value as a comma separated string.
- 
-=====   =====