| At line 2 changed one line |
| The plugin supports __OpenID Connect SSO__ ( more info: [https://en.wikipedia.org/wiki/OpenID]), an authentication protocol built on top of the OAuth 2.0 ([https://en.wikipedia.org/wiki/OAuth]) authorization framework.\\ |
| The plugin supports __OpenID Connect SSO__ (More info: [OpenID Wikipedia Link|https://en.wikipedia.org/wiki/OpenID]), an authentication protocol built on top of the OAuth 2.0 ([OAuth Wikipedia Link|https://en.wikipedia.org/wiki/OAuth]) authorization framework.\\ |
| At line 4 changed one line |
| __!!! Constraints__: It only works through __HTTP__ or __HTTPS__ protocol. __Authorization Code Flow__ is supported (Implicit Flow or Hybrid Flow are not supported). It requires __Enterprise License__.\\ |
| ---- |
| __⚠️ Important__: Ensure that all {{''__(Required❗)__''}} fields are properly configured as outlined on this wiki page.\\ |
| ---- |
| __⚠️ Proxy Configuration__: If your server accesses the internet through a proxy, ensure that the __Identity Provider__’s (IdP’s) domains are whitelisted to allow the authentication process.\\ |
| ---- |
| __⚠️ Constraints__:\\ |
| • It only works through __HTTP__ or __HTTPS__ protocol.\\ |
| • __Authorization Code Flow__ is supported (Implicit Flow or Hybrid Flow are not supported).\\ |
| • It requires __Enterprise License__.\\ |
| • In __Preferences → Misc__, set the “__HTTP Redirect Base__” value to empty, as the default is “__DISABLED”__.{{''__(Required)__''}}\\ |
| At line 15 added 3 lines |
| [oidc_redirect_base_setting.png]\\ |
| \\ |
| ---- |
| At line 7 changed 4 lines |
| The plugin requires the following IdP information and configuration:\\ |
| • 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:\\ |
| \\ |
| The plugin requires the following information and configurations from the IdP's __App Registration__:\\ |
| • __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:\\ |
| At line 15 changed one line |
| Google: [https://support.google.com/googleapi/answer/6158849]\\ |
| __Apple__: Apple Sign-In requires different plugin settings because the client secret is generated using the private key, Key ID, and Team ID.\\ |
| At line 17 changed one line |
| !!!2. Plugin Configuration\\ |
| [Apple Sign In Configuration/apple_oidc_config.png]\\ |
| __⚠️ See details at__: [Apple Sign In Configuration]\\ |
| At line 33 added 21 lines |
| __Google__:\\ |
| __1.__ Go to: __Google Cloud Console__ – __Credentials__: [Google APIs & Services Link|https://console.developers.google.com/projectselector/apis/credentials]\\ |
| __2.__ Create an __OAuth 2.0 Client ID__\\ |
| • Application type: __Web application__\\ |
| • Set your __Redirect URL__ (e.g., https://your.domain.com/SSO_OIDC/)\\ |
| __3.__ Enable the __People API__ (if you need access to the user’s name, profile pic, ...)\\ |
| • Navigate to __APIs & Services__ -> __Library__\\ |
| • Search for __People API__ and click __Enable__\\ |
| \\ |
| As a reference example, see the [GDriveSetup] documentation.\\ |
| \\ |
| __Microsoft__: Refer to the App registration: [Microsoft Sign in Configuration]\\ |
| \\ |
| __Microsoft B2C__: Refer to the App registration section under: [Azure Active Directory B2C Configuration]. Ensure the redirect URL is described above.\\ |
| \\ |
| __Amazon Cognito__: Refer to the App registration section under: [Amazon Cognito Configuration]. Ensure the redirect URL is described above.\\ |
| \\ |
| __Dropbox__: Refer to the App registration section under: [Dropbox Integration]. Ensure the redirect URL is described above.\\ |
| \\ |
| ---- |
| !!!2. Plugin Configuration\\ |
| At line 23 changed one line |
| !2.1.1 OpenID Configuration URL {{''__(Required)__''}}: \\ |
| !2.1.1 OpenID Configuration URL {{''__(Required❗)__''}}: \\ |
| At line 27 changed 2 lines |
| This HTTP URL is part of the OpenID Connect (OIDC) Discovery mechanism. It follows a standard called __RFC 5785__ ([https://datatracker.ietf.org/doc/html/rfc5785]), which defines the use of __.well-known__ URIs for discovering metadata about services. It queries this HTTP endpoint to configure itself dynamically, avoiding hard-coded values. The retrieved JSON document includes important endpoints and details like:\\ |
| • Authorization endpoint\\ |
| This HTTP(S) URL is part of the OpenID Connect (OIDC) Discovery mechanism. It follows a standard called __RFC 5785__ ([ Defining Well-Known Uniform Resource Identifiers Link|https://datatracker.ietf.org/doc/html/rfc5785]), which defines the use of __.well-known__ URIs for discovering metadata about services. It queries this HTTP(S) endpoint to configure itself dynamically, avoiding hard-coded values. The retrieved JSON document includes important endpoints and details like:\\ |
| • Authorization endpoint {{''__(Required❗)__''}}\\ |
| At line 71 added one line |
| Apple: https://appleid.apple.com/.well-known/openid-configuration |
| At line 47 changed one line |
| You can reference a __local JSON file__ if the identity provider (IdP) does not support OpenID Connect but does support __OAuth 2.0__ (like Box cloud storage). Instead of specifying an HTTP URL, provide the path to a local JSON file, such as:\\ |
| You can reference a __local JSON file__ if the identity provider (IdP) does not support OpenID Connect but does support __OAuth 2.0__ (like Box Cloud Storage). Instead of specifying an HTTP URL, provide the path to a local JSON file, such as:\\ |
| At line 52 changed one line |
| The JSON file should include the __authorization endpoint__. Example for Box cloud storage: |
| The JSON file should include the __authorization endpoint__ {{''__(Required)__''}}. Example for Box cloud storage: |
| At line 62 changed one line |
| __Client ID__: Provide the Client ID (the unique identifier) of your IdP.\\ |
| __Client ID__: Provide the Client ID (the unique identifier of your IdP's App registration) of your IdP.\\ |
| At line 65 changed one line |
| !2.1.3 Authorization related settings {{''__(Required)__''}}:\\ |
| !2.1.3 Authorization related settings {{''__(Required❗)__''}}:\\ |
| At line 76 changed one line |
| • {oidc_redirect_url}: An autogenerated URL by CrushFTP, composed of the initial host and port, followed by __/SSO_IDC/__. This URL is used to redirect the user after successful authentication. __!!! It must exactly match the redirect URL registered and configured in the IdP.__\\ |
| • {oidc_redirect_url}: An autogenerated URL by CrushFTP, composed of the initial host and port, followed by __/SSO_IDC/__. This URL is used to redirect the user after successful authentication. __⚠️ It must exactly match the redirect URL registered and configured in the IdP.__\\ |
| At line 86 changed one line |
| __Get Refresh Token__: It is used to access the user's cloud storage through the IdP. It adjusts the __Authorization URL__ by appending the following parameters:\\ |
| __Get Refresh Token__: It is used for access the user's cloud storage through the IdP. It adjusts the __Authorization URL__ by appending the following parameters:\\ |
| At line 92 changed one line |
| __The refresh token enables access to the user's cloud storage through the IdP. __CrushFTP supports cloud storage integration with services such as Google Drive ([GDriveSetup]), OneDrive ([OneDriveSetup]), SharePoint ([SharePoint Integration]), and Dropbox ([Dropbox Integration]).\\ |
| __The refresh token enables access to the user's cloud storage through the IdP. __CrushFTP supports cloud storage integration with services such as Google Drive ([GDriveSetup]), Google Cloud Storage ([Google Cloud Storage Integration]), OneDrive ([OneDriveSetup]), SharePoint ([SharePoint Integration]), and Dropbox ([Dropbox Integration]).\\ |
| At line 96 changed 2 lines |
| Google: https://www.googleapis.com/auth/drive |
| Dropbox: files.metadata.write files.content.write files.content.read |
| Google: https://www.googleapis.com/auth/drive |
|
| GStorage: https://www.googleapis.com/auth/devstorage.full_control |
|
| Dropbox: files.metadata.write files.content.write files.content.read |
| At line 100 changed one line |
| __Microsoft__ does not require additional scopes for this purpose. Ensure that the __App Registration__ includes the __"Files.ReadWrite.All"__ permission, configured as either Delegated or Application. More info at [SharePoint Integration].\\ |
| __Microsoft Azure App Registration__ does not require additional scopes for this purpose. Ensure the __App Registration__ includes the required __API Permissions__ configured as either __Delegated__ or __Application__. More info at [SharePoint Integration] or at [OneDriveSetup].\\ |
| At line 102 changed one line |
| At "__Custom VFS__" settings you can reference the gained __refresh token__ as variable: |
| At __2.2.7 Custom VFS__ [Link|https://www.crushftp.com/crush11wiki/Wiki.jsp?page=CrushOIDC#section-CrushOIDC-2.2.7CustomVFSRequiredUnderSpecificConditions] settings you can reference the gained __refresh token__ as variable: |
| At line 109 changed one line |
| __Verify ID Token:__ The Authorization Code Flow uses the code value returned by the IdP to obtain the ID token. Although this step is not mandatory in the OpenID protocol, you can enable an additional verification of the returned ID token by selecting this checkbox. __!!!__ This feature works only if the OpenID configuration includes the "__jwks_uri__" endpoint. __It provides an extra layer of validation for the ID token.__\\ |
| __Verify ID Token:__ The Authorization Code Flow uses the code value returned by the IdP to obtain the ID token. Although this step is not mandatory in the OpenID protocol, you can enable an additional verification of the returned ID token by selecting this checkbox. ⚠️ This feature works only if the OpenID configuration includes the "__jwks_uri__" endpoint. __It provides an extra layer of validation for the ID token.__\\ |
| At line 113 changed one line |
| __Check User Endpoint URL?__: This option enables CrushFTP to retrieve additional information about the user from the IdP via the "__user_info__" endpoint URL. __!!!__ This feature only works if the OpenID configuration includes a "userinfo_endpoint" URL or if you manually specify it in the "__User Endpoint URL__" input field. \\ |
| __Check User Endpoint URL?__: This option enables CrushFTP to retrieve additional information about the user from the IdP via the "__user_info__" endpoint URL. ⚠️ This feature only works if the OpenID configuration includes a "userinfo_endpoint" URL or if you manually specify it in the "__User Endpoint URL__" input field. \\ |
| At line 156 added 6 lines |
| ⚠️ __Special Case for Microsoft Azure AD:__ When using __Microsoft Azure AD__ as the Identity Provider (IdP), a specific user endpoint is required to retrieve group information for the authenticated user:\\ |
| {{{ |
| https://graph.microsoft.com/v1.0/me |
| }}} |
| In this scenario, the plugin makes __an additional API call to this endpoint__ to fetch the user's __group membership__ details. The App registration must include the __Group.Read.All__ permission to enable access to group information.\\ |
| \\ |
| At line 126 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__. |
| __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__. |
| At line 128 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__.\\ |
| __⚠️__ 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 138 changed one line |
| __Enable__: Activate the plugin. {{''__(Required)__''}}\\ |
| __Enable__: Activate the plugin. {{''__(Required❗)__''}}\\ |
| At line 144 changed one line |
| !2.2.1 Login Button {{''__(Required)__''}}:\\ |
| !2.2.1 Login Button {{''__(Required❗)__''}}:\\ |
| At line 149 changed one line |
| !2.2.2 Username matching {{''__(Required)__''}}:\\ |
| !2.2.2 Username matching {{''__(Required❗)__''}}:\\ |
| At line 165 changed one line |
| ([User Manager] defines user's access.) -> If users already exist in CrushFTP's User Manager, you can use the CrushOIDC plugin __just for authentication__. |
| It is useful when user accounts are already defined and managed within CrushFTP's [User Manager], you can leverage the CrushOIDC plugin to authenticate users against external Identity Providers. This allows existing users to utilize OIDC for login while maintaining their existing user accounts and access privileges as defined within CrushFTP.\\ |
| At line 167 changed one line |
| !2.2.5 User Templates {{''__(Required)__''}}:\\ |
| !2.2.5 User Templates {{''__(Required❗)__''}}:\\ |
| At line 169 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]). ⚠️ __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!__\\ |
| At line 176 changed one line |
| __Authentication aspect__: Permit users based on specific IdP claims. \\ |
| __Authentication aspect__: Permit users based on specific IDP claims. \\ |
| At line 178 changed one line |
| __!!! Important__: If roles are configured and the IdP's user does not match any of the predefined roles, the authentication will be rejected due to the absence of matching roles.\\ |
| __⚠️ Important__: If roles are configured and the IdP's user does not match any of the predefined roles, the authentication will be rejected due to the absence of matching roles.\\ |
| At line 180 changed 2 lines |
| __Template User Aspect__: You can configure different Template Users (see 2.2.5 User Templates) based on IdP claims. If a template user is specified, the signed-in user inherits both the settings and the VFS items (as Linked [VFS]).\\ |
| __!!! Important__: Template user must exist in the [User Manager], otherwise, it will have no effect.\\ |
| __Template User Aspect__: You can configure different Template Users (See at __2.2.5 User Templates__ [Link|https://www.crushftp.com/crush11wiki/Wiki.jsp?page=CrushOIDC#section-CrushOIDC-2.2.5UserTemplatesRequired]) based on IdP claims. If a template user is specified, the signed-in user inherits both the settings and the VFS items (as Linked [VFS]).\\ |
| __⚠️ Important__: Template user must exist in the [User Manager], otherwise, it will have no effect.\\ |
| At line 228 added 5 lines |
| __IdP Attribute Value__ -> Supports different types of matching:\\ |
| • __Exact Match__: Matches the value exactly as provided.\\ |
| • __Simple Match__: Use patterns like __*mail.com*__ to match substrings.\\ |
| • __Regex Match__: Use the format __REGEX:<<your-regular-expression>>__ for more complex patterns.\\ |
| \\ |
| At line 185 removed one line |
|
| At line 255 added 4 lines |
| If the attribute value is an array, you can reference only one element for an exact match. Example: If the IDP attribute value is __:\\ |
| {{{ |
| [groups:"group1", "group2"] -> you can match with "group1". |
| }}}\\ |
| At line 260 added 90 lines |
| !2.2.7 Custom VFS {{''__(Required Under Specific Conditions❗)__''}}: |
| \\ |
| [VFS] related settings. You can configure a custom [VFS] for CrushOIDC users.\\ |
| __⚠️ 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:\\ |
| • Template User (See at __2.2.5 User Templates__ [Link|https://www.crushftp.com/crush11wiki/Wiki.jsp?page=CrushOIDC#section-CrushOIDC-2.2.5UserTemplatesRequired])\\ |
| • Roles (See at __2.2.6 Roles__ [Link|https://www.crushftp.com/crush11wiki/Wiki.jsp?page=CrushOIDC#section-CrushOIDC-2.2.6Roles])\\ |
| • Custom VFS\\ |
| \\ |
| __Custom VFS examples:__ This Custom VFS setup allows access to remote resources using a refresh token obtained through OpenID Connect (OIDC) authentication.\\ |
| \\ |
| __a.) GDrive__:\\ |
| \\ |
| {{{ |
| gdrive://{oidc_client_id}~{oidc_client_secret_decoded}:{oidc_refresh_token}@www.google.com/ |
| }}}\\ |
| __More info at__: [GDriveSetup]\\ |
| __⚠️ It requires the scope__:\\ |
| {{{ https://www.googleapis.com/auth/drive}}}\\ |
| Check the description of : __2.1.3 Authorization related settings__ [Link|https://www.crushftp.com/crush11wiki/Wiki.jsp?page=CrushOIDC#section-CrushOIDC-2.1.3AuthorizationRelatedSettingsRequired] regarding scope.\\ |
| [CrushOIDC/oidc_gdrive_settings.png] |
| \\ |
| __b.) Google Cloud Storage__:\\ |
| \\ |
| {{{ |
| gstorage://{oidc_client_id}~{oidc_client_secret_decoded}:{oidc_refresh_token}@storage.googleapis.com/ |
| }}}\\ |
| \\ |
| __More info at__: [Google Cloud Storage Integration]\\ |
| __⚠️ It requires the scope__:\\ |
| {{{ https://www.googleapis.com/auth/devstorage.full_control}}}\\ |
| Check the description of : __2.1.3 Authorization related settings__ [Link|https://www.crushftp.com/crush11wiki/Wiki.jsp?page=CrushOIDC#section-CrushOIDC-2.1.3AuthorizationRelatedSettingsRequired] regarding scope.\\ |
| [CrushOIDC/oidc_gstorage_settings.png]\\ |
| \\ |
| __c.) OneDrive__:\\ |
| \\ |
| {{{ |
| Onedrive Personal Type: onedrive://{oidc_client_id}~{oidc_client_secret_encoded}:{oidc_refresh_token}@graph.microsoft.com/ |
| or |
| OneDrive Business Type: onedrive://app_permission~{oidc_client_id}:{oidc_client_secret_decoded}@graph.microsoft.com/ |
| }}}\\ |
| __More info at__: [OneDriveSetup]\\ |
| __⚠️ Note__:\\ |
| -Ensure the __Azure App Registration__ includes the required __API Permission__ (More info at [OneDriveSetup]).\\ |
| -__User id or User principal name__: Provide the user's ID or the user principal name (UPN) or {user_name} variable.\\ |
| [CrushOIDC/oidc_onedrive_settings.png]\\ |
| \\ |
| __d.) SharePoint__:\\ |
| \\ |
| {{{ |
| Sharepoint Delegated Permission: sharepoint://{oidc_client_id}~{oidc_client_secret_encoded}:{oidc_refresh_token}@graph.microsoft.com/ |
| or |
| Sharepoint Application Permission: sharepoint://app_permission~{oidc_client_id}:{oidc_client_secret_decoded}@graph.microsoft.com/ |
| or |
| SharePoint REST service API-based: sharepoint2://delegated_permission~{oidc_client_id}~{oidc_client_secret_encoded}:{oidc_refresh_token}@graph.microsoft.com/ |
| }}}\\ |
| __More info at__: [SharePoint Integration]\\ |
| __⚠️ Note__:\\ |
| - Ensure the __Azure App Registration__ includes the required __API Permission__ (More info at [SharePoint Integration]).\\ |
| - __Configure the Sharepoint-specific settings__ too (More info at [SharePoint Integration]):\\ |
| __Tennant:__ See at App Registration -> Overview -> Directory (tenant) ID. Based on the App Registration Account type it can be an ID, common, or consumer. |
| __Site id__ : The SharePoint domain name.\\ |
| __Site Path__: The path of the SharePoint site. It should start and end with a slash.\\ |
| __Drive name__: Each SharePoint site has a Document Library where the site-related files are stored. See [SharePoint: Documents and Libraries Description Link|https://support.microsoft.com/en-us/office/what-is-a-document-library-3b5976dd-65cf-4c9e-bf5a-713c10ca2872] Provide its name\\ |
| __Folder__: Relative path of the document library of the SharePoint site.\\ |
| [CrushOIDC/oidc_sharepoint2_settings.png]\\ |
| \\ |
| __e.) DropBox__:\\ |
| \\ |
| {{{ |
| DropBox: dropbox://{oidc_client_id}~{oidc_client_secret_decoded}:{oidc_refresh_token}@api.dropboxapi.com/ |
| }}}\\ |
| More info at: [Dropbox Integration]\\ |
| [CrushOIDC/oidc_dropbox_settings.png]\\ |
| \\ |
| ---- |
| !3. DMZ\\ |
| \\ |
| [CrushOIDC/oidc_dmz_plugin_settings.png]\\ |
| \\ |
| The DMZ's CrushOIDC plugin has a slightly different UI because IdP user validation is handled exclusively on the internal node. To function properly, the __DMZ must replicate the internal node's settings__ for the following parameters:\\ |
| \\ |
| • Plugin name\\ |
| • OpenID Configuration URL\\ |
| • Client ID\\ |
| • Client Secret (Optional): Only if it is required for the authorization url.\\ |
| • Authorization URL\\ |
| • Scope\\ |
| • Get Refresh Token\\ |
| • Login button text\\ |
| \\ |
