Configure authentication
Datagrok supports many authentication methods, including popular methods such as SSO and OAuth:
- General (login-password)
- LDAP
- OpenID (Google, Azure AD, Okta, and other OpenID Connect providers)
- SAML
- IAP
- Group synchronization (mirror identity-provider groups into Datagrok groups)
You can enable all methods separately or combined.
If supported authentication methods do not work for you, contact us on info@datagrok.ai, and we will discuss options for your specific case.
General (login-password) authentication
General (login-password) authentication is the most basic method to authenticate users with Datagrok.
To configure login-password authentication:
- Go to the Settings > Users and Sessions. This section contains all authentication settings.
- To use the login-password method, enable 'Internal authentication' in General section
- To disable signup uncheck 'Signup Allowed' option
- To restrict from which domains people can sign up to the platform, use the 'Signup Domains Whitelist' option. You can set several domains separated with commas.
- To force people to use active emails, enable the 'Require Email Confirm' option.
- To require strong passwords (a mix of uppercase and lowercase letters, digits, or special characters, and a minimum length), enable 'Enforce Password Policy'.
- To show a message on the login form, for example a support contact, set 'Prompt'.
- To let people sign up through OpenID or SAML when they sign in for the first time, enable 'Allow Oauth Signup'. Otherwise, an administrator must create the user first.
For login-password authentication, it is important to configure an email service that will deliver signup, welcome, confirmation and forgot password emails.
Add users
To create user:
- Go to Browse > Platform > Users.
- Click New and select New User.... The New User dialog opens.
- Enter the name, email, and login, and click OK.
For bulk provisioning, use the grok s CLI.
Use user groups to manage user permissions inside platform.
LDAP authentication
Datagrok integrates with your LDAP or Active Directory server enabling the smooth domain authentication mechanism across all your services.
- Go to the Settings > Users and Sessions. This section contains all authentication settings.
- To use the LDAP method, enable 'Domain authentication'
- Enable 'Domain signup' to enable all users present on a domain controller to authenticate in the Datagrok platform. If the option is disabled, it is required to create the user in the Datagrok platform first to allow the user to log into the platform
- Configure LDAP server address/DNS name
- Set LDAP server port
- Enable LDAP SSL if you use LDAPS on your server
- Set LDAP Base DN. It should look like
dc=datagrok,dc=ai. - Set LDAP User DN. It should look like
CN=USER-DATAGROK,OU=users,DC=datagrok,DC=ai - Set LDAP User password
Note: To ensure only domain-managed users can access the platform:
- Disable 'Signup Allowed' to prevent unauthorized users from registering directly on Datagrok.
- Enable 'Signup Enabled' in 'Domain Authentication' to allow new users already registered in the organization's LDAP or Active Directory (AD) system to log in.
LDAP authentication lets AD users sign in with their domain credentials, but
doesn't synchronize group membership. To keep Datagrok groups and shares in
sync with AD groups, drive the platform from a script using the
grok s CLI.
OpenID authentication
This is the preferred and most powerful way to integrate with an external identity provider.
Datagrok supports the OpenID protocol to allow users to be authenticated using OpenID providers
such as Azure AD, Google, Okta, Auth0, and any other OIDC-compliant identity provider.
For a step-by-step Microsoft Entra ID setup, including group sync, see Set up Microsoft Entra ID.
- Go to the Datagrok Settings section
Users and Sessions; this section contains all authentication settings. - Enable
Open Id authenticationto use the OpenID method - Get a well-known-configuration route and set it to 'Open Id Config Endpoint'. It should look
like
https://login.datagrok.ai/.well-known/openid-configuration. For Google, usehttps://accounts.google.com/.well-known/openid-configuration. - Set
Client Idas in your OpenID provider, and choose how Datagrok proves its identity to the provider inSecret Type:Client Secret: Paste the client secret from the provider intoClient Secret.AzureAD JWT: Certificate-based authentication for Microsoft Entra ID (Azure AD). Generate a certificate and a private RSA key, paste them intoClient CertificateandClient Private Key, and upload the certificate to your Entra ID application settings.Signed JWT: Datagrok signs the client assertion with the server's signing key, and the provider verifies it against the keys the server publishes (JWKS). No secret is shared, and the key rotates with the server keys.
- Set
Code Challenge Method(S256by default, orNoneif your provider doesn't support PKCE). - Set
Scopes(openid profile emailby default). - Map the claims in the login token to the user's attributes:
Login Claim(udnby default),Email Claim,First Name Claim,Last Name Claim, andPicture Claim. For Microsoft Entra ID, setLogin Claimtopreferred_username. - Enable
Auto Login using OpenIDto forward users to authentication automatically without showing the login form. - Make sure the correct Web Root is set in
Adminsection - Enable
Keep Tokenmode if you want to enable seamless integration with other services. Datagrok will requestoffline_accessscope and keep encrypted external token in session metadata.
If users sign in through an identity-aware proxy and you need OpenID only for the OAuth flows of data connectors,
turn off Use For Login.
Keep Token
Default authentication token expiration is 1 hour for OpenID, and it only can be used for validating user identity.
To be able to use the token for accessing external services, enable Keep Token in OpenID settings.
When Keep Token is enabled, Datagrok requests offline access from the OpenID provider during authentication.
This allows Datagrok to securely get a refresh token in addition to the access token.
Datagrok automatically refreshes the external OpenID token together with its own internal session token. Datagrok keeps a refresh token in the browser storage. Token refresh happens every 10 minutes and when a user session starts, ensuring uninterrupted user sessions and seamless integration with external services.
Datagrok applies different handling strategies depending on the token type, ensuring that server-side actions always require explicit user intent. If the external token is a JWT, the token signature is embedded into the Datagrok user token on the client side. The JWT payload is encrypted and stored in the database. Datagrok cannot perform external actions autonomously without token signature.
If the external token is opaque, the token is stored only inside the user JWT on the client side. The server never has direct access to the token contents.
That means, external tokens are never usable by the server without a user-initiated request
Calling external services with the kept token
Because the token is split between the browser and the server, plugins can't read it
(grok.dapi.users.currentSession() doesn't return it). Instead, send the request through
grok.dapi.fetchProxy and put the
${EXTERNAL_TOKEN} placeholder in a header. The server swaps in the current user's token
before it forwards the request:
const response = await grok.dapi.fetchProxy('https://api.example.com/v1/items', {
headers: {Authorization: 'Bearer ${EXTERNAL_TOKEN}'},
});
Use a plain string, not a template literal. In a template literal, JavaScript would try to
expand ${EXTERNAL_TOKEN} as a variable.
The placeholder only works for a signed-in user with Keep Token enabled. Otherwise the
request fails and the target service isn't called. The kept token is the provider's
access token, issued by the authorization server set in the configuration endpoint. Its
audience and claims, such as groups, are whatever that server puts in access tokens for the
requested scopes. If a claim your service needs is missing, add its scope to Scopes.
Long-lived sessions are supported without exposing privileged credentials, and Datagrok can integrate seamlessly with external systems while preserving user-controlled authorization boundaries.
Right now user OpenID authentication is supported by BigQuery and Databricks providers.
Package code can also pass the kept token to other services through
fetchProxy.
Group synchronization
Datagrok can mirror the groups a user belongs to in your identity provider into Datagrok groups. Groups are matched by name, missing groups are created, and memberships the user no longer has on the provider side are removed. Groups created by the sync are owned by the Administrators role and are deleted when their last synced member leaves. Groups and memberships that an administrator created by hand are never removed, and roles such as Administrators are never matched.
Synchronization runs:
- When a user logs in, for that user.
- On a schedule, for every active user, so a user removed from a group loses it without logging in.
- When an administrator clicks Sync now, for every active user.
If the provider has no record of a user, or can't be reached, the user keeps their groups.
Settings
Group sync settings are in Settings > Users and Sessions > Group Sync. Turn on Sync Groups to show the rest of the settings:
| Setting | Shown when | Description |
|---|---|---|
| Sync Groups | Always | Turns group synchronization on or off |
| Provider | Sync Groups is on | Azure Entra (Microsoft Entra ID through OpenID) or Google (Google Workspace) |
| Group Filter | Sync Groups is on | A regular expression, matched case-insensitively against group names. Only matching groups are synced. Empty syncs all groups |
| Sync Interval | Sync Groups is on | How often, in minutes, every user's groups are re-read. 0 syncs on login only. The default is 60 |
| Google Group Service Account | Provider is Google | The service account key JSON. See Google Workspace |
| Google Delegated Admin Email | Provider is Google | The Workspace super-admin the service account impersonates |
Settings saved before this layout carry over. A server that had Sync Google Groups on gets Sync Groups on with Provider set to Google. A server that had Sync Groups on gets Azure Entra.
To check the settings before you save them, enter a user's email next to Test for user and click Test. Datagrok lists the user's groups on the provider, greys out the ones the filter excludes, and shows the groups the sync currently manages for that user. Click Sync now to sync every user with the saved settings right away.
Microsoft Entra ID
Datagrok reads group names from the login token's groups claim. Entra ID usually puts object IDs
there, or no claim at all for users with many groups, so Datagrok reads the user's transitive group
membership from Microsoft Graph. Scheduled sync and the test run have no user token and call Graph
with the app's own token. To set it up:
- In the app registration, add the delegated Microsoft Graph permissions
User.ReadandGroupMember.Read.All, and the application permissionsUser.Read.AllandGroupMember.Read.All. Grant admin consent. - In Datagrok, configure OpenID authentication with a configuration endpoint on
login.microsoftonline.comand a client secret or certificate. Other hosts are treated as generic OpenID providers: only the token claim is read at login, and scheduled sync skips users. - Append
GroupMember.Read.Allto the OpenID Scopes, for exampleopenid profile email GroupMember.Read.All. - Set Login Claim to
preferred_username. Entra ID tokens carry noudnclaim. - In Group Sync, turn on Sync Groups and set Provider to Azure Entra.
Group display names must be unique in the tenant for matching to work. Use Group Filter to keep
unrelated groups out of Datagrok, for example ^datagrok-.
For the full walkthrough, see Set up Microsoft Entra ID.
Google Workspace
Google tokens never carry group membership, so Datagrok reads it through the Cloud Identity API using a service account. This works with Google OpenID login and with IAP.
- Create a service account, enable domain-wide delegation for the scope
https://www.googleapis.com/auth/cloud-identity.groups.readonly, and download its key JSON. - In Group Sync, turn on Sync Groups, set Provider to Google, paste the key JSON into Google Group Service Account, and set Google Delegated Admin Email to a Workspace super-admin the service account impersonates.
When Keycloak synchronization is enabled on the server, group sync is skipped.
SAML authentication
- Go to Datagrok Settings section 'Users and Sessions'
- Enable SAML authentication
- Copy ACS URI and Entity ID to SAML provider (i.e. Google or Azure AD)
- Copy SSO URI to Datagrok as IdP Endpoint and Certificate. Make sure you switch to a multiline edit mode when copying certificate.
- Map the attributes the provider sends to the user's attributes:
Email Claim,First Name Claim, andLast Name Claim(email,first_name, andlast_nameby default).
SAML doesn't synchronize group membership. To mirror directory groups, use the
grok s CLI or switch to
OpenID.
IAP authentication
Datagrok supports Google Identity-Aware Proxy (IAP) out of the box. Configure Identity-Aware Proxy for Datagrok server for automatic login.
Datagrok automatically detects x-goog-iap-jwt-assertion header, validates the token using Google keys, and authenticates user.