Skip to main content
Last updated on

Single-use refresh tokens

This page explains single-use refresh tokens for OAuth applications integrated with Databricks and describes how to configure them using the Databricks API. Single-use refresh tokens enhance security by requiring token rotation after each use.

What are single-use refresh tokens?​

Custom and published application integrations use single-use refresh tokens (also called refresh token rotation) in the user-to-machine (U2M) authentication flow. They enhance OAuth security by allowing each refresh token to be used only once. When a client application uses a refresh token to get new access credentials, Databricks issues a new refresh token and invalidates the old one.

Single-use refresh tokens are enabled by default for:

For most other published apps and custom OAuth integrations, use the Databricks API to enable this feature.

Most modern OAuth client applications handle single-use refresh tokens automatically with no behavioral changes for end users. Not all client applications support this feature. If a client application doesn't work correctly with single-use refresh tokens enabled, you can disable the feature to revert to multi-use refresh tokens.

Configure single-use refresh tokens​

You can configure single-use refresh tokens through the Databricks API or the Databricks CLI. For more information on the API, see the Databricks API documentation. For more information on the Databricks CLI, see What is the Databricks CLI?.

To enable single-use refresh tokens and set the OAuth session time-to-live (TTL), specify the enable_single_use_refresh_tokens and absolute_session_lifetime_in_minutes fields under token_access_policy.

JSON
{
  "confidential": true,
  "name": "Example Tableau Server",
  "redirect_urls": ["https://example.online.tableau.com/auth/add_oauth_token"],
  "scopes": ["all-apis", "offline_access"],
  "token_access_policy": {
    "access_token_ttl_in_minutes": 60,
    "refresh_token_ttl_in_minutes": 1440,
    "enable_single_use_refresh_tokens": true,
    "absolute_session_lifetime_in_minutes": 43200
  }
}