| At line 18 added 18 lines |
| !!! Quick Start Configuration\\ |
| \\ |
| These are the essential settings you must configure in the CrushOIDC plugin so that it functions properly with an OpenID Connect (OIDC) Identity Provider (IdP). All “Required” items must be set correctly.\\ |
| \\ |
| • Enable Plugin [Link|https://www.crushftp.com/crush11wiki/Wiki.jsp?page=CrushOIDC#section-CrushOIDC-2.2CrushFTPRelatedPluginSettings]\\ |
| • OpenID Configuration URL [Link|https://www.crushftp.com/crush11wiki/Wiki.jsp?page=CrushOIDC#section-CrushOIDC-2.1.1OpenIDConfigurationURLRequired]\\ |
| • IDP's Redirect URL [Link|https://www.crushftp.com/crush11wiki/Wiki.jsp?page=CrushOIDC#section-CrushOIDC-1.IdentityProviderSIdPGeneralConfiguration]\\ |
| • Client ID [Link|https://www.crushftp.com/crush11wiki/Wiki.jsp?page=CrushOIDC#section-CrushOIDC-2.1.2AppRegistrationRelatedInformation]\\ |
| • Client Secret [Link|https://www.crushftp.com/crush11wiki/Wiki.jsp?page=CrushOIDC#section-CrushOIDC-2.1.2AppRegistrationRelatedInformation]\\ |
| • Authorization URL [Link|https://www.crushftp.com/crush11wiki/Wiki.jsp?page=CrushOIDC#section-CrushOIDC-2.1.3AuthorizationRelatedSettingsRequired]\\ |
| • Scope(s) [Link|https://www.crushftp.com/crush11wiki/Wiki.jsp?page=CrushOIDC#section-CrushOIDC-2.1.3AuthorizationRelatedSettingsRequired]\\ |
| • Login Button Text [Link|https://www.crushftp.com/crush11wiki/Wiki.jsp?page=CrushOIDC#section-CrushOIDC-2.2.1LoginButtonRequired]\\ |
| • Claim as Username [Link|https://www.crushftp.com/crush11wiki/Wiki.jsp?page=CrushOIDC#section-CrushOIDC-2.1.5ClaimAndIdPSessionRelatedConfigs] \\ |
| • Username matching [Link|https://www.crushftp.com/crush11wiki/Wiki.jsp?page=CrushOIDC#section-CrushOIDC-2.2.3UsernameMatchingRequired]\\ |
| • User Template [Link|https://www.crushftp.com/crush11wiki/Wiki.jsp?page=CrushOIDC#section-CrushOIDC-2.2.5UserTemplatesRequired]\\ |
| • Custom VFS [Link|https://www.crushftp.com/crush11wiki/Wiki.jsp?page=CrushOIDC#section-CrushOIDC-2.2.7CustomVFSRequiredUnderSpecificConditions]\\ |
| \\ |
| ---- |
| At line 21 changed 3 lines |
| • __Client ID__\\ |
| • __Client Secret__: Authorization Code Flow requires it.\\ |
| • __Redirect URL__: The redirect URL is the endpoint in your IdP application where the IdP directs the user after successful authentication. This URL receives the authorization code or access token as part of the authentication process. The redirect URL must target the CrushFTP server and conclude with __/SSO_OIDC/__. Like:\\ |
| • __Client ID__(Required❗)\\ |
| • __Client Secret__(Required❗): Authorization Code Flow requires it.\\ |
| • __Redirect URL__(Required❗): The redirect URL is the endpoint in your IdP application where the IdP directs the user after successful authentication. This URL receives the authorization code or access token as part of the authentication process. The redirect URL must target the CrushFTP server and conclude with __/SSO_OIDC/__. Like:\\ |
| At line 46 added 2 lines |
| __Common Identity Providers (IdPs):__\\ |
| \\ |
| At line 96 changed one line |
| !2.1.2 App registration related informations:\\ |
| !2.1.2 App registration related information:\\ |
| At line 169 changed one line |
| !2.1.6 Claim and IdP session related configs:\\ |
| !2.1.5 Claim and IdP session related configs:\\ |
| At line 171 changed one line |
| __Claim as Username__ {{''__(Required❗)__''}}: Specify the name of the claim within the IdP's response that should be used as the __username for the CrushFTP session__. |
| !2.1.5.1 Claim as Username {{''__(Required❗)__''}}:\\ |
| At line 173 changed one line |
| __⚠️__ If this claim is not present or its value is missing in the IdP's response (either within the ID Token or retrieved from the user endpoint), __the authentication will fail due to a missing username__.\\ |
| Specify the name of the claim within the IdP's response that should be used as the __username for the CrushFTP session__. |
| At line 195 added 2 lines |
| __❗__ If this claim is not present or its value is missing in the IdP's response (either within the ID Token or retrieved from the user endpoint), __the authentication will fail due to a missing username__.\\ |
| \\ |
| At line 177 changed one line |
| __End Session URL__: This URL is called at __the end of the CrushFTP session__ to terminate the user's session. You can use the "end_session_endpoint" provided in the OpenID configuration data by referencing it as the variable __{end_session_endpoint}__, or you can specify the URL manually.\\ |
| !2.1.5.2 End Session URL\\ |
| At line 201 added 39 lines |
| This URL is called at __the end of the CrushFTP session__ to terminate the user's session. You can use the "end_session_endpoint" provided in the OpenID configuration data by referencing it as the variable __{end_session_endpoint}__, or you can specify the URL manually.\\ |
| \\ |
| Examples:\\ |
| \\ |
| The placeholders like {id_token} and {oidc_client_id} are variables CrushFTP substitutes at runtime when the user logs out.\\ |
| \\ |
| {{{ |
| Microsoft Azure AD/B2C: {end_session_endpoint}?id_token_hint={id_token}&post_logout_redirect_uri=https%3A%2F%2FyourCrushFTP.example.com%2F |
|
| Okta: {end_session_endpoint}?id_token_hint={id_token}&post_logout_redirect_uri=https%3A%2F%2FyourCrushFTP.example.com%2F |
|
| Auth0: {end_session_endpoint}?federated&client_id={oidc_client_id}&returnTo=https%3A%2F%2FyourCrushFTP.example.com%2F |
| }}}\\ |
| \\ |
| For all providers, you must configure the logout redirect URI (post-logout / returnTo) in the IdP’s application settings. If it is not explicitly allowed there, the logout call will be rejected or will not redirect properly back to CrushFTP.\\ |
| \\ |
| __WebInterface Logout Customizations:__\\ |
| \\ |
| When using the OIDC plugin, CrushFTP can pass the OIDC provider’s end-of-session URL to the OIDC provider during logout. This ensures that not only does the CrushFTP session end, but also the user’s session at the external IDP.\\ |
| \\ |
| Configure one of the following WebInterface Customizations ([UserManager WebInterface|UserManagerWebInterface]) in the user template by using __Import settings from CrushFTP user__ [Link|https://www.crushftp.com/crush11wiki/Wiki.jsp?page=CrushOIDC#section-CrushOIDC-2.2.5UserTemplatesRequired]:\\ |
| \\ |
| 1. URL to open in popup on logout\\ |
| \\ |
| [UserManagerWebInterface/oidc_end_session_pop_up_url.png]\\ |
| {{{ |
| {user_crushOIDC_end_session_url} |
| }}}\\ |
| When the user logs out of the CrushFTP WebInterface, CrushFTP opens the IdP’s end session endpoint in a popup window.\\ |
| \\ |
| 2. Redirect to this location after logout\\ |
| \\ |
| [UserManagerWebInterface/oidc_end_session_redirect_url.png]\\ |
| \\ |
| {{{ |
| {user_crushOIDC_end_session_url} |
| }}}\\ |
| Instead of (or in addition to) a popup, the user is redirected to the IdP’s end session URL after logging out.\\ |
| \\ |
| At line 194 changed one line |
| !2.2.2 Username matching {{''__(Required❗)__''}}:\\ |
| !2.2.2 Key Mapping in CrushFTP (IDP → User Keys):\\ |
| At line 257 added 11 lines |
| [CrushOIDC/oidc_key_mappings.png]\\ |
| \\ |
| The Key Mapping feature in CrushFTP allows attributes received from an external Identity Provider (IDP) to be mapped directly into CrushFTP’s internal user properties.\\ |
| • IDP Key: This is the attribute name coming from the Identity Provider (e.g., phone, email, displayName).\\ |
| • CrushFTP Key: This is the corresponding property in the CrushFTP user account where the IDP value will be stored.\\ |
| \\ |
| How it works:\\ |
| When a user authenticates through the OIDC plugin, CrushFTP receives attribute data from the IDP. Using the key mapping configuration, CrushFTP will copy the IDP attribute value into the designated user property.\\ |
| \\ |
| !2.2.3 Username matching {{''__(Required❗)__''}}:\\ |
| \\ |
| At line 214 changed 2 lines |
| __Template Username__: The signed-in user inherits both the settings and the VFS items(as Linked [VFS]). __It must have a value!__\\ |
| __Import settings from CrushFTP user__: The signed-in user inherits only the settings from the specified user. __It must have a value!__\\ |
| __Template Username__: The signed-in user inherits both the settings and the VFS items(as Linked [VFS]). ❗ __You must provide a username that already exists.__\\ |
| __Import settings from CrushFTP user__: The signed-in user inherits only the settings from the specified user. ❗__You must provide a username that already exists.__\\ |
| At line 226 changed one line |
| __⚠️ Important__: Template user must exist in the [User Manager], otherwise, it will have no effect.\\ |
| __⚠️ Important__: Template user must exist in the [User Manager], otherwise, the setting will not take effect.\\ |
| At line 263 changed one line |
| __⚠️ Important:__ If the CrushOIDC user has no assigned VFS, __authentication will be rejected due to the absence of an assigned [VFS]__. CrushOIDC user can inherit VFS configuration from:\\ |
| __❗Important:__ If the CrushOIDC user has no assigned VFS, __authentication will be rejected due to the absence of an assigned [VFS]__. CrushOIDC user can inherit VFS configuration from:\\ |
