Stages Documentation

Differences

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

Link to this comparison view

Next revision		Previous revision
262:integration:oidc [2026/10/28 10:45] – created Policnik, Florian262:integration:oidc [2026/10/28 12:19] (current) – Policnik, Florian
Line 1: Line 1:
 ====== Configure OpenID Connect (OIDC) Authentication ====== ====== Configure OpenID Connect (OIDC) Authentication ======
  
-This feature is beta.+This feature is in the beta stage.
  
 OpenID Connect (OIDC) is an identity layer built on OAuth 2.0. Stages acts as an OIDC relying party (RP), also called a client, and delegates user authentication to an OpenID Provider (OP), also called an identity provider (IdP). OpenID Connect (OIDC) is an identity layer built on OAuth 2.0. Stages acts as an OIDC relying party (RP), also called a client, and delegates user authentication to an OpenID Provider (OP), also called an identity provider (IdP).
  
 Stages uses the provider's discovery document and a client registration to establish the OIDC login flow. Stages uses the provider's discovery document and a client registration to establish the OIDC login flow.
- 
  
 ===== Register Stages with the identity provider ===== ===== Register Stages with the identity provider =====
Line 12: Line 11:
 Create an OIDC client/application in your identity provider. Ask your identity or access management team for the values required to configure it in Stages. Create an OIDC client/application in your identity provider. Ask your identity or access management team for the values required to configure it in Stages.
  
-Register the exact redirect URI (callback URL) provided by your Stages version. Do not guess this URL: it must match exactly, including scheme, host, path, and any trailing slash. TODO+Register the following redirect URIs (callback URLs) for the client. Stages uses three different redirect URIs, which must all be registered exactly as shown, including scheme, host, path, and query parameter:
  
-Obtain the following values from the provider:+<code> 
 +https://stages.example.com/stages/auth/public/acs?client_name=oidc-idp 
 +https://stages.example.com/stages/auth/public/acs?client_name=passive-oidc-idp 
 +https://stages.example.com/stages/auth/public/acs?client_name=forceAuth-oidc-idp 
 +</code>
  
 +Replace ''<nowiki>https://stages.example.com</nowiki>'' with the base URL of your Stages installation. The value ''oidc-idp'' in the ''client_name'' parameter corresponds to the ''name'' attribute of the OIDC authentication method in ''conf/config.xml'' (see [[#enable-oidc-for-stages|Enable OIDC for Stages]]). If you use a different method name, adjust the redirect URIs accordingly.
 +
 +Request the scopes:
 +  * ''openid''
 +  * ''profile''
 +  * ''email''
 +
 +Obtain the following values from the provider:
   * OIDC discovery URL   * OIDC discovery URL
   * Client ID   * Client ID
   * Client secret   * Client secret
-  * The scopes and claims required to identify users 
  
 The provider's discovery document is normally available at the issuer's ''/.well-known/openid-configuration'' endpoint. The provider's discovery document is normally available at the issuer's ''/.well-known/openid-configuration'' endpoint.
- 
-Request the scopes ''openid'', ''profile'' and ''email''. 
- 
  
 ===== Enable OIDC for Stages ===== ===== Enable OIDC for Stages =====
Line 31: Line 38:
  
 <code xml> <code xml>
-<method type="Oidc" name="oidc-idp" enabled="${idp.oidc.enabled}"><!-- TODO -->+<method type="Oidc" name="oidc-idp" enabled="${idp.oidc.enabled}">
     <properties>     <properties>
         <property name="discoveryURI" value="${idp.oidc.discovery.url}" />         <property name="discoveryURI" value="${idp.oidc.discovery.url}" />
Line 52: Line 59:
 </code> </code>
  
-The ''discoveryURI'' points to the OIDC provider's discovery document. The ''scope'' determines which claims are requested. Set ''clientAuthenticationMethodAsString'' to a client authentication method supported by both Stages and your provider.+The ''discoveryURI'' points to the OIDC provider's discovery document. The ''scope'' determines which claims are requested.
  
 The following example configuration variables are referenced above. Adjust the discovery URL, scope, client ID, and client authentication method to match your provider's client registration. The following example configuration variables are referenced above. Adjust the discovery URL, scope, client ID, and client authentication method to match your provider's client registration.
Line 75: Line 82:
 </code> </code>
  
- +After you have configured the OIDC authentication method 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 OIDC authentication process when the OIDC configuration was changed after the user had been created. However, you can set the ''forceLicensePoolReassignment''  attribute on an ''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 OIDC authentication process when the OIDC configuration was changed after the user had been created. However, you can set the ''forceLicensePoolReassignment'' attribute on an ''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 claims of the OIDC 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 claims of the OIDC response are accessible as variables and can be used in the JavaScript expression.
  
 JavaScript expressions can be used with the following Stages attributes: JavaScript expressions can be used with the following Stages attributes:
Line 95: Line 100:
 **General JavaScript expression notation:**   **General JavaScript expression notation:**  
  
-<code javascript> <Stages_attribute>="=<JavaScript_expression>"  +<code xml> 
 +<Stages_attribute>="=<JavaScript_expression>"
 </code>   </code>  
  
 **JavaScript notation of if-clauses:** **JavaScript notation of if-clauses:**
-<code javascript> if (condition1) 'returnValue1'; else if (condition2) 'returnValue2'; else if (condition3) 'returnValue3'; else 'returnValue4';  +<code javascript> 
 +if (condition1) 'returnValue1'; else if (condition2) 'returnValue2'; else if (condition3) 'returnValue3'; else 'returnValue4';
 </code>   </code>  
  
 **JavaScript notation of value conditions:** **JavaScript notation of value conditions:**
  
-OIDC claims that are defined via identity_provider_attribute elements can be used in these scripts. E.g.  +OIDC claims that are defined via identity-provider-attribute elements can be used in these scripts. E.g.  
 <code xml>  <code xml> 
 <identity-provider-attribute name="email" id="<EMailAddress>" />   <identity-provider-attribute name="email" id="<EMailAddress>" />  
Line 120: Line 127:
  
 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 OIDC claim "id".    +  * The pattern matches the entry of the OIDC claim ''id'' 
-  * Depending on the users' email address (domain-part), OIDC claim "email" is used to assign different values for defaultRolesUsername, defaultLicenseType and licensePoolIdent +  * Depending on the users' email address (domain-part), OIDC claim ''email'' is used to assign different values for defaultRolesUsername, defaultLicenseType and licensePoolIdent
  
 <code xml>  <code xml> 
Line 140: Line 147:
  
 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.
- 
  
  
Line 160: Line 166:
  
 This will create a SSO button on the login page for each IDP. This will create a SSO button on the login page for each IDP.
-Please provide a user understandable naming by defining a translation property for each login.sso.[name] propertyin each supported language:+Please provide a user understandable naming by defining a translation property for each login.sso.[name] property in each supported language:
 ''conf/local.properties'', ''conf/local_de.properties'', ... ''conf/local.properties'', ''conf/local_de.properties'', ...
 <code properties> <code properties>