gradient fox will integrate seamlessly with any OIDC compliant external IdP that your organization is currently using. This reduces maintenance overhead since you do not need to create and manage local users in the gradient fox system.
You will still need to create groups and define their permissions in gradient fox, but your IdP users can automatically be mapped to those groups when they log into gradient fox for the first time.
Below you will find instructions how to integrate your IdP with gradient including the environment variables you need to set for the integration.
Without proper group mapping, the SSO users will have no groups assigned to them after they log in via your SSO provider. You could manually assign groups in gradient fox to users after their initial SSO login, but this solution requires a lot of manual work and is not very scalable.
In order for the automatic mapping to groups to take place during SSO login, you must configure external identifiers for your gradient fox user groups. This can be done when a user group is added or later on the group properties page. You need to enter the group name/id as they appear in your organizations IdP. You can enter multiple external names/ids by separating them with a comma. Notice that even if the name of the group in your IdP is exactly the same as the group name in gradient fox, you need to enter it in the 'External Name' field.
Notice that the external names are case-sensitive, so make sure the value matches exactly with the names returned in the 'groups' claim in the OIDC Identity Token. Also make sure you leave no extra spaces between the 'External Names' field.
The following environment variables (under webserver/environment in the Docker compose file) need to be set in order to integrate gradient fox with Okta.
GF_SSO_OKTA_CLIENT_ID=<clientId> GF_SSO_OKTA_CLIENT_SECRET=<clientSecret> GF_SSO_OKTA_ISSUER=https://<host>.okta.com
To set up the integration in Okta, you first need to log into your Okta console. Under Applications/Applications left nav item, click on the 'Create App Integration' button. This will bring up the dialog displayed below. Select OIDC as the Sign-in method and Web Application as the application type as shown below.
After creating the new application integration, navigate to the application that was just created. You can find the values for the GF_SSO_OKTA_CLIENT_ID and GF_SSO_OKTA_CLIENT_SECRET environment variables under the General-tab as shown below. If you do not see a value under CLIENT SECRETS, click on the Generate new secret-button to add a new secret. Copy the client id and client secret values to the environment variables specified above.
The value for the GF_SSO_OKTA_ISSUER environment variable can be found under the Sign On-tab in the 'OpenID Connect ID Token' section. Copy the entire URL seen in the Issuer-dropdown, shown as https://xxxx.okta.com below.
The screen shot below also shows how to configure the groups claim for your application. The claim name must be groups and you can specify a filter to restrict the group names that will be returned. The screen shot shows a regex that matches all groups, so all groups will be returned in the ID token.
You also need to configure the Sign-in redirect URL to match the host/port where your gradient fox server is running. This can be done under the LOGIN-section. The format of the URI is as follows.
https://<yourHost>:<yourPort>/login/oauth2/code/okta
Similarly, the Sign-Out redirect URL needs to be configured to match your environment.
https://<yourHost>:<yourPort>
Once your gradient fox environment variables are configured, you will see the SSO-tab on the login page and there is an option for Okta on the list of providers. You need to restart the server after changing the environment variables for the new values to take effect. If there are any errors in your configuration either in Okta or gradient fox, you will see an error during startup and the server may not start at all.
The following environment variables (under webserver/environment in the Docker compose file) need to be set in order to integrate gradient fox with Microsoft Entra ID (formerly Azure Active Directory).
GF_SSO_ENTRA_CLIENT_ID=<clientId> GF_SSO_ENTRA_CLIENT_SECRET=<clientSecret> GF_SSO_ENTRA_ISSUER=https://login.microsoftonline.com/<yourTenantId>/v2.0
To set up the integration in Entra ID, you first need to log into your Microsoft Azure console, then go to the Entra ID service. Select the 'App registrations' left nav item, then click on the 'New registration' button. This will bring up the page displayed below. Select Web under the Redirect URI section and enter the redirect URI to match the host/port where your gradient fox server is running. The format of the URI is as follows (use http if you have not set up SSL on your gradient fox server).
https://<yourHost>:<yourPort>/login/oauth2/code/okta
After creating the new application integration, navigate to the application that was just created. You can find the value for the GF_SSO_ENTRA_CLIENT_ID environment variable under the Essentials-tab of the Overview-left nav item as shown below. The client id value is shown as xxxx below.
On this screen you can also find the tenant id that you will need to included in the GF_SSO_ENTRA_ISSUER environment variable shown above. The tenant id value is shown as zzzz below.
The value for the GF_SSO_ENTRA_CLIENT_SECRET environment variable can be set by clicking on the Certificates & secrets left nav item. Click on the 'New client secret' button and give a name and expiration for the new secret. The value for the new secret can now be seen on the secrets page, but only immediately after creating it, so make sure you copy the value.
Once your gradient fox environment variables are configured, you will see the SSO-tab on the login screen and there is an option for Entra ID on the list of providers. You need to restart the server after changing the variables for the new values to take effect. If there are any errors in your configuration either in Azure or gradient fox, you will see an error during startup and the server may not start at all.
If your IdP is not one of the ones listed above, you can still integrate gradient fox with it as long as it is OpenID Connect compliant provider such as AWS Cognito, Auth0, Keycloak, etc.
In order to use the Generic OIDC feature, you need to configure the following gradient fox environment variables using 'OIDC' as the provider name as seen below.
GF_SSO_OIDC_CLIENT_ID=<clientId> GF_SSO_OIDC_CLIENT_SECRET=<clientSecret> GF_SSO_OIDC_ISSUER=<yourIssuerUri>
If your environment variables are correctly configured, you will see the SSO-tab on the login screen and there is a Generic OIDC option on the list of providers. You need to restart the server after changing the variables for the new values to take effect. If there are any errors in your configuration either in your IdP or gradient fox, you will see an error during startup and the server may not start at all
In some cases you need to modify the default scope that will be used in the request that gradient fox issues to your IdP. You can do it for any supported provider by configuring the GF_SSO_<provider>_SCOPE environment variable where the 'provider' value depends on your IdP. Below you can see an example of how to configure the scope for the generic OIDC provider case.
GF_SSO_OIDC_SCOPE=openid,profile,email,groups