feat: add Okta OAuth provider (#429)

Co-authored-by: Sébastien Chopin <seb@nuxt.com>
Co-authored-by: Sébastien Chopin <atinux@gmail.com>

Author: bisand

.gitignore

@@ -1,5 +1,6 @@
 # Dependencies
 node_modules
+.pnpm-store
 
 # Logs
 *.log*

README.md

@@ -239,6 +239,7 @@ It can also be set using environment variables:
 - LinkedIn
 - LiveChat
 - Microsoft
+- Okta
 - PayPal
 - Polar
 - Salesforce

playground/.env.example

@@ -136,4 +136,9 @@ NUXT_OAUTH_SLACK_REDIRECT_URL=
 #Heroku
 NUXT_OAUTH_HEROKU_CLIENT_ID=
 NUXT_OAUTH_HEROKU_CLIENT_SECRET=
-NUXT_OAUTH_HEROKU_REDIRECT_URL=
+NUXT_OAUTH_HEROKU_REDIRECT_URL=
+# Okta
+NUXT_OAUTH_OKTA_CLIENT_ID=
+NUXT_OAUTH_OKTA_CLIENT_SECRET=
+NUXT_OAUTH_OKTA_DOMAIN=
+NUXT_OAUTH_OKTA_REDIRECT_URL=

playground/app.vue

@@ -248,6 +248,12 @@ const providers = computed(() =>
       disabled: Boolean(user.value?.heroku),
       icon: 'i-simple-icons-heroku',
     },
+    {
+      label: user.value?.okta || 'Okta',
+      to: '/auth/okta',
+      disabled: Boolean(user.value?.okta),
+      icon: 'i-simple-icons-okta',
+    },
   ].map(p => ({
     ...p,
     prefetch: false,

playground/auth.d.ts

@@ -43,6 +43,7 @@ declare module '#auth-utils' {
     salesforce?: string
     slack?: string
     heroku?: string
+    okta?: string
   }
 
   interface UserSession {

playground/server/routes/auth/okta.get.ts

@@ -0,0 +1,13 @@
+export default defineOAuthOktaEventHandler({
+  config: {},
+  async onSuccess(event, { user }) {
+    await setUserSession(event, {
+      user: {
+        okta: user?.name,
+      },
+      loggedInAt: Date.now(),
+    })
+
+    return sendRedirect(event, '/')
+  },
+})

src/module.ts

@@ -468,5 +468,14 @@ export default defineNuxtModule<ModuleOptions>({
       redirectURL: '',
       scope: '',
     })
+    // Okta OAuth
+    runtimeConfig.oauth.okta = defu(runtimeConfig.oauth.okta, {
+      clientId: '',
+      clientSecret: '',
+      domain: '',
+      audience: '',
+      scope: [],
+      redirectURL: '',
+    })
   },
 })

src/runtime/server/lib/oauth/okta.ts

@@ -0,0 +1,311 @@
+import type { H3Event } from 'h3'
+import { eventHandler, getQuery, sendRedirect, createError, deleteCookie } from 'h3'
+import { withQuery } from 'ufo'
+import { defu } from 'defu'
+import { handleMissingConfiguration, handleState, handleInvalidState, handleAccessTokenErrorResponse, getOAuthRedirectURL, requestAccessToken } from '../utils'
+import { useRuntimeConfig } from '#imports'
+import type { OAuthConfig } from '#auth-utils'
+
+export interface OpenIdConfig {
+  authorization_endpoint: string
+  token_endpoint: string
+  userinfo_endpoint: string
+  end_session_endpoint?: string
+  [key: string]: unknown
+}
+
+interface CachedOpenIdConfig {
+  data: OpenIdConfig
+  expiresAt: number
+}
+
+const openIdConfigCache = new Map<string, CachedOpenIdConfig>()
+const DEFAULT_CACHE_TTL = 1000 * 60 * 60 * 24 // 24 hours in milliseconds
+
+export interface OAuthConfigExt<TConfig, TResult = {
+  user: Record<string, unknown>
+  tokens: Record<string, unknown>
+  openIdConfig: OpenIdConfig
+}> extends OAuthConfig<TConfig, TResult> {
+  config?: TConfig
+  onSuccess: (event: H3Event, result: TResult) => Promise<void> | void
+  onError?: (event: H3Event, error: unknown) => Promise<void> | void
+}
+
+export interface OAuthOktaConfig {
+  /**
+   * Okta OAuth Client ID
+   * @default process.env.NUXT_OAUTH_OKTA_CLIENT_ID
+   */
+  clientId?: string
+  /**
+   * Okta OAuth Client Secret
+   * @default process.env.NUXT_OAUTH_OKTA_CLIENT_SECRET
+   */
+  clientSecret?: string
+  /**
+   * Okta OAuth Issuer
+   * @default process.env.NUXT_OAUTH_OKTA_DOMAIN
+   */
+  domain?: string
+  /**
+   * Okta OAuth Authorization Server
+   * @see https://developer.okta.com/docs/guides/customize-authz-server/main/#create-an-authorization-server
+   * @default process.env.NUXT_OAUTH_OKTA_AUTHORIZATION_SERVER
+   */
+  authorizationServer?: string
+  /**
+   * Okta OAuth Audience
+   * @default process.env.NUXT_OAUTH_OKTA_AUDIENCE
+   */
+  audience?: string
+  /**
+   * Okta OAuth Scope
+   * @default []
+   * @see https://okta.com/docs/get-started/apis/scopes/openid-connect-scopes
+   * @example ['openid']
+   */
+  scope?: string | string[]
+  /**
+   * Require email from user, adds the ['email'] scope if not present
+   * @default false
+   */
+  emailRequired?: boolean
+  /**
+   * Maximum Authentication Age. If the elapsed time is greater than this value, the OP must attempt to actively re-authenticate the end-user.
+   * @default 0
+   * @see https://okta.com/docs/authenticate/login/max-age-reauthentication
+   */
+  maxAge?: number
+  /**
+   * Login connection. If no connection is specified, it will redirect to the standard Okta login page and show the Login Widget.
+   * @default ''
+   * @see https://okta.com/docs/api/authentication#social
+   * @example 'github'
+   */
+  connection?: string
+  /**
+   * Extra authorization parameters to provide to the authorization URL
+   * @see https://okta.com/docs/api/authentication#social
+   * @example { display: 'popup' }
+   */
+  authorizationParams?: Record<string, string>
+  /**
+   * Redirect URL to to allow overriding for situations like prod failing to determine public hostname
+   * @default process.env.NUXT_OAUTH_OKTA_REDIRECT_URL or current URL
+   */
+  redirectURL?: string
+  /**
+   * OpenID Configuration cache TTL in milliseconds
+   * @default 86400000 (24 hours)
+   */
+  openIdConfigCacheTTL?: number
+}
+
+export function defineOAuthOktaEventHandler({ config, onSuccess, onError }: OAuthConfigExt<OAuthOktaConfig>) {
+  function normalizeScope(scope: unknown, emailRequired?: boolean): string[] {
+    let result: string[]
+    if (!scope || (typeof scope === 'string' && scope.trim() === '')) {
+      result = ['openid', 'email', 'profile']
+    }
+    else if (typeof scope === 'string') {
+      result = scope.split(/[,| ]+/).filter(Boolean)
+    }
+    else if (Array.isArray(scope) && scope.length > 0) {
+      result = scope
+    }
+    else {
+      result = ['openid', 'email', 'profile']
+    }
+    result = [...new Set(result)]
+    if (emailRequired && !result.includes('email')) {
+      result.push('email')
+    }
+    return result
+  }
+
+  // Event handler for Okta OAuth. Is called multiple times during the OAuth flow.
+  return eventHandler(async (event: H3Event) => {
+    const runtimeConfig = useRuntimeConfig(event)
+    config = defu(config, runtimeConfig.oauth?.okta, {
+      authorizationParams: {},
+    }) as OAuthOktaConfig
+
+    if (!config.clientId || !config.clientSecret || !config.domain || typeof config.domain !== 'string' || !config.domain.trim()) {
+      return handleMissingConfiguration(event, 'okta', ['clientId', 'clientSecret', 'domain'], onError)
+    }
+
+    const query = getQuery<{ code?: string, state?: string, error?: string, error_description?: string }>(event)
+
+    if (query.error) {
+      const error = createError({
+        statusCode: 401,
+        message: `Okta login failed: ${query.error || 'Unknown error'} - ${query.error_description || ''}`,
+        data: query,
+      })
+      if (!onError) throw error
+      return onError(event, error)
+    }
+
+    config.scope = normalizeScope(config.scope, config.emailRequired)
+
+    const getOpenIdConfig = async (openIdConfigurationUrl: string, event?: H3Event): Promise<OpenIdConfig> => {
+      const now = Date.now()
+      const cacheTTL = config?.openIdConfigCacheTTL || DEFAULT_CACHE_TTL
+
+      const cached = openIdConfigCache.get(openIdConfigurationUrl)
+      if (cached) {
+        if (cached.expiresAt > now) {
+          return cached.data
+        }
+        else {
+          openIdConfigCache.delete(openIdConfigurationUrl) // Lazy eviction of expired entry
+        }
+      }
+
+      let openIdConfig: OpenIdConfig | null = null
+      try {
+        openIdConfig = await $fetch<OpenIdConfig>(openIdConfigurationUrl)
+        if (openIdConfig) {
+          openIdConfigCache.set(openIdConfigurationUrl, {
+            data: openIdConfig,
+            expiresAt: now + cacheTTL,
+          })
+        }
+      }
+      catch (error) {
+        if (config && config.domain) {
+          const authz = config.authorizationServer
+          openIdConfig = {
+            authorization_endpoint: authz
+              ? `https://${config.domain}/oauth2/${authz}/v1/authorize`
+              : `https://${config.domain}/oauth2/v1/authorize`,
+            token_endpoint: authz
+              ? `https://${config.domain}/oauth2/${authz}/v1/token`
+              : `https://${config.domain}/oauth2/v1/token`,
+            userinfo_endpoint: authz
+              ? `https://${config.domain}/oauth2/${authz}/v1/userinfo`
+              : `https://${config.domain}/oauth2/v1/userinfo`,
+            end_session_endpoint: undefined,
+          }
+
+          openIdConfigCache.set(openIdConfigurationUrl, {
+            data: openIdConfig,
+            expiresAt: now + Math.min(cacheTTL / 24, 1000 * 60 * 60), // 1 hour or 1/24th of configured TTL, whichever is smaller
+          })
+        }
+        else {
+          // Log and throw a more actionable error if OpenID config fetch fails and no fallback is possible
+          console.error('Failed to fetch Okta OpenID configuration. Please check your Okta domain and network connectivity:', error)
+          const err = createError({
+            statusCode: 500,
+            message: 'Could not get Okta OpenID configuration. Please verify that your Okta domain is correct and reachable, and that the OpenID configuration endpoint is accessible.',
+            data: error,
+          })
+          if (onError) await onError(event!, err)
+          throw err
+        }
+      }
+      return openIdConfig
+    }
+
+    const authServer = config.authorizationServer
+    const openIdConfigurationUrl = authServer ? `https://${config.domain}/oauth2/${authServer}/.well-known/openid-configuration` : `https://${config.domain}/.well-known/openid-configuration`
+
+    const openIdConfig = await getOpenIdConfig(openIdConfigurationUrl, event)
+    const authorizationURL = openIdConfig.authorization_endpoint
+    const tokenURL = openIdConfig.token_endpoint
+    const userInfoUrl = openIdConfig.userinfo_endpoint
+
+    const redirectURL = config.redirectURL || getOAuthRedirectURL(event)
+
+    const state = await handleState(event)
+
+    // Step 1: Authorization Request
+    if (!query.code) {
+      return sendRedirect(
+        event,
+        withQuery(authorizationURL as string, {
+          response_type: 'code',
+          client_id: config.clientId,
+          redirect_uri: redirectURL,
+          scope: config.scope.join(' '),
+          audience: config.audience || '',
+          max_age: config.maxAge || 0,
+          connection: config.connection || '',
+          state,
+          ...config.authorizationParams,
+        }),
+      )
+    }
+
+    // Step 2: Validate callback state
+    if (query.state !== state) {
+      deleteCookie(event, 'nuxt-auth-state')
+      return handleInvalidState(event, 'okta', onError)
+    }
+
+    // Step 3: Request Access Token
+    const tokens = await requestAccessToken(tokenURL as string, {
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: {
+        response_type: 'code',
+        grant_type: 'authorization_code',
+        client_id: config.clientId,
+        client_secret: config.clientSecret,
+        scope: config.scope?.join(' '),
+        redirect_uri: redirectURL,
+        code: query.code,
+        state: query.state,
+      },
+    })
+
+    if (tokens.error) {
+      return handleAccessTokenErrorResponse(event, 'okta', tokens, onError)
+    }
+
+    if (
+      !tokens.access_token || typeof tokens.access_token !== 'string'
+      || !tokens.token_type || typeof tokens.token_type !== 'string'
+    ) {
+      const err = createError({
+        statusCode: 400,
+        message: 'Invalid token response from Okta',
+        data: tokens,
+      })
+      if (onError) return onError(event, err)
+      throw err
+    }
+
+    const tokenType = tokens.token_type
+    const accessToken = tokens.access_token
+
+    // Step 4: Fetch user info from Okta using the access token
+    let user: Record<string, unknown>
+    try {
+      user = await $fetch(userInfoUrl, {
+        headers: {
+          Authorization: `${tokenType} ${accessToken}`,
+        },
+      })
+    }
+    catch (error: unknown) {
+      const err = createError({
+        statusCode: 410,
+        message: `Could not get Okta user info - ${error instanceof Error ? error.message : String(error)}`,
+        data: tokens,
+      })
+      if (onError) return onError(event, err)
+      throw err
+    }
+
+    // Step 5: Call onSuccess handler with tokens, user, and OpenID config
+    return onSuccess(event, {
+      tokens,
+      user,
+      openIdConfig,
+    })
+  })
+}

src/runtime/types/oauth-config.ts

@@ -2,7 +2,7 @@ import type { H3Event, H3Error } from 'h3'
 
 export type ATProtoProvider = 'bluesky'
 
-export type OAuthProvider = ATProtoProvider | 'atlassian' | 'auth0' | 'authentik' | 'azureb2c' | 'battledotnet' | 'cognito' | 'discord' | 'dropbox' | 'facebook' | 'gitea' | 'github' | 'gitlab' | 'google' | 'hubspot' | 'instagram' | 'kick' | 'keycloak' | 'line' | 'linear' | 'linkedin' | 'microsoft' | 'paypal' | 'polar' | 'spotify' | 'seznam' | 'steam' | 'strava' | 'tiktok' | 'twitch' | 'vk' | 'workos' | 'x' | 'xsuaa' | 'yandex' | 'zitadel' | 'apple' | 'livechat' | 'salesforce' | 'slack' | 'heroku' | (string & {})
+export type OAuthProvider = ATProtoProvider | 'atlassian' | 'auth0' | 'authentik' | 'azureb2c' | 'battledotnet' | 'cognito' | 'discord' | 'dropbox' | 'facebook' | 'gitea' | 'github' | 'gitlab' | 'google' | 'hubspot' | 'instagram' | 'kick' | 'keycloak' | 'line' | 'linear' | 'linkedin' | 'microsoft' | 'paypal' | 'polar' | 'spotify' | 'seznam' | 'steam' | 'strava' | 'tiktok' | 'twitch' | 'vk' | 'workos' | 'x' | 'xsuaa' | 'yandex' | 'zitadel' | 'apple' | 'livechat' | 'salesforce' | 'slack' | 'heroku' | 'okta' | (string & {})
 
 export type OnError = (event: H3Event, error: H3Error) => Promise<void> | void