Skip to main content

Auth Providers

NetFoundry Frontdoor includes OAuth integration for Custom Frontends, allowing you to authenticate users through various OAuth providers before they can access your shared resources. You can configure multiple OAuth providers and restrict access based on email address patterns.

Planning for OAuth Authentication​

OAuth authentication in NetFoundry Frontdoor is configured at the Custom Frontend level and applied to individual Shares. Each Custom Frontend can have multiple Auth Providers configured, and each Share can be protected with a specific Auth Provider.

The OAuth authentication flow uses the Custom Frontend's domain to handle redirects from OAuth providers. This means you'll need a Custom Frontend with a properly configured domain name that is accessible by your end users.

Configuring Auth Providers​

Auth Providers are configured through the NetFoundry Frontdoor REST API. Each Auth Provider defines how users authenticate with external identity providers before accessing your Shares.

Supported Provider Types​

NetFoundry Frontdoor supports three types of OAuth providers:

  1. OIDC - Standard OpenID Connect provider for custom identity providers
  2. GITHUB - GitHub OAuth authentication
  3. GOOGLE - Google OAuth authentication

Creating an Auth Provider​

Use the REST API to create an Auth Provider within your Frontdoor:

curl -X POST "https://api.netfoundry.io/frontdoor/{frontdoorId}/auth-providers" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-token>" \
  -d '{
    "name": "google-auth",
    "type": "GOOGLE",
    "config": {
      "clientId": "<google-client-id>",
      "clientSecret": "<google-client-secret>"
    }
  }'

See the Auth Provider API Guide for more details.

Configuration Parameters by Provider Type​

Each provider type requires specific configuration parameters:

OIDC (OpenID Connect)​

  • clientId: OIDC client ID from your identity provider
  • clientSecret: OIDC client secret from your identity provider
  • issuerUrl: The issuer URL for your OIDC provider
  • scopes: Array of OAuth scopes to request (e.g., ["openid", "email", "profile"])

Google OAuth​

  • clientId: Google OAuth client ID from Google Cloud Console
  • clientSecret: Google OAuth client secret from Google Cloud Console

GitHub OAuth​

  • clientId: GitHub OAuth app client ID
  • clientSecret: GitHub OAuth app client secret

OAuth Identity Considerations​

Session Management​

Session duration is controlled by the Auth Provider configuration, requiring users to re-authenticate when sessions expire. Sessions are scoped to the specific Share, meaning that switching between Shares may require re-authentication depending on the configuration.

Identity Verification and Trust​

Ensure OAuth providers require verified email addresses before allowing authentication while validating that user identities remain consistent across authentication sessions using stable identifiers such as user ID rather than just email addresses. Only configure trusted OAuth providers with strong security practices and up-to-date security certifications, preferring OAuth providers that enforce multi-factor authentication for enhanced security.

Token Security Best Practices​

Request only the minimum necessary OAuth scopes such as openid, email, and profile to follow the principle of least privilege while ensuring that Frontdoor securely manages OAuth tokens server-side without exposing raw tokens to client applications. Configure appropriate token lifetimes that balance security and user experience, typically ranging from 1-24 hours for access tokens, and use OAuth providers that support refresh token rotation to minimize long-term credential exposure.

Privacy and Data Protection​

Only collect and process user identity information necessary for authentication and authorization decisions while ensuring OAuth consent flows clearly communicate what data is being accessed and how it will be used. Implement policies for how long authentication session data and user information is retained, and consider data residency requirements when using global OAuth providers to ensure compliance with applicable regulations.

Compliance and Audit Considerations​

All authentication events, successes, and failures are logged for security monitoring and compliance while requiring regular reviews and audits of which users have access to OAuth-protected resources. Ensure OAuth provider configurations meet relevant compliance requirements such as SOC 2, GDPR, and HIPAA, and establish procedures for revoking access and rotating credentials in case of security incidents.

Risk Mitigation Strategies​

Avoid single points of failure by supporting multiple OAuth providers when appropriate while considering backup authentication methods for critical applications. Monitor for unusual authentication patterns such as logins from new geographic locations or unusual access times, implement rate limiting on authentication attempts to prevent brute force attacks, and provide mechanisms to forcibly invalidate user sessions across all Shares when needed.

Using OAuth with Shares​

Once you have configured Auth Providers in your Frontdoor, you can protect Shares by specifying an Auth Provider when creating the Share.

Creating an OAuth-Protected Share​

When creating a Share through the REST API, specify the Auth Provider:

curl -X POST "https://api.netfoundry.io/frontdoor/{frontdoorId}/shares" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-token>" \
  -d '{
    "name": "protected-app",
    "frontendId": "{customFrontendId}",
    "environmentId": "{environmentId}",
    "target": "http://localhost:8080",
    "authProviderId": "{authProviderId}",
    "emailPatterns": ["*@example.com", "admin@*"]
  }'

See the Share API Guide for more details.

Email Pattern Restrictions​

Use the emailPatterns array to restrict access to users whose email addresses match specific patterns. You can allow any user with a specific domain using *@example.com, permit users with emails starting with a specific prefix using admin@*, or restrict access to only a specific email address using user@company.org.

HTTP Headers for Proxied Requests​

When Frontdoor successfully authenticates a user via OAuth, it automatically adds authentication headers to all proxied requests sent to your backend application. These headers allow your application to identify the authenticated user and make authorization decisions.

Authentication Headers​

Frontdoor sets the following HTTP headers on every proxied request after successful OAuth authentication: zrok-auth-provider contains the name of the OAuth provider used for authentication such as google-auth or github-corp, zrok-auth-email provides the authenticated user's email address as provided by the OAuth provider, and zrok-auth-expires includes the timestamp when the authentication session will expire, formatted as RFC3339 such as 2024-01-15T14:30:00Z.

Security Considerations​

These headers are only present when requests come through Frontdoor's OAuth-protected Custom Frontend, as direct access to your backend would not include these headers. Your application should validate that these headers are present when OAuth protection is expected, and use the zrok-auth-expires header to implement client-side session warnings or automatic logout.

Managing Auth Providers​

Frontdoor supports CRUD operations for Auth Providers. See the Auth Provider API Guide for details.

Provider-Specific Setup Guides​

For detailed setup instructions for each provider type, including how to obtain client credentials and configure redirect URLs, see the provider-specific guides:

When configuring OAuth applications with these providers, use your Custom Frontend's domain for the authorized redirect URLs in the format: https://oauth.your-custom-frontend.com/{auth-provider-name}/auth/callback

Common Use Cases​

Enterprise Single Sign-On (SSO)​

Integrate with your organization's existing identity provider to provide seamless access:

{
  "name": "company-sso",
  "type": "OIDC",
  "config": {
    "clientId": "frontdoor-app-id",
    "clientSecret": "secure-client-secret",
    "issuerUrl": "https://auth.company.com",
    "scopes": ["openid", "email", "profile"]
  }
}

Use with email patterns to restrict access to employees: ["*@company.com"]

Partner and External Access​

Provide secure access to external partners using their existing accounts:

{
  "name": "google-partners",
  "type": "GOOGLE",
  "config": {
    "clientId": "google-oauth-client-id",
    "clientSecret": "google-oauth-secret"
  }
}

Restrict access to specific partner domains: ["*@partner1.com", "*@partner2.com"]

Development Team Collaboration​

Enable development teams to access shared resources using GitHub accounts:

{
  "name": "github-developers",
  "type": "GITHUB",
  "config": {
    "clientId": "github-app-client-id",
    "clientSecret": "github-app-secret"
  }
}

Limit access to organization members: ["*@github.yourorg.com"]

Customer Portal Access​

Create customer-facing portals with Google OAuth for easy access:

{
  "name": "customer-portal",
  "type": "GOOGLE",
  "config": {
    "clientId": "customer-portal-client-id",
    "clientSecret": "customer-portal-secret"
  }
}

Allow access to specific customer domains or individual accounts.

Multi-Tenant Application Access​

Support multiple customer organizations with their own identity providers:

  • Configure separate OIDC Auth Providers for each tenant
  • Use distinct email patterns for each organization
  • Create tenant-specific Shares with appropriate Auth Provider assignments

Compliance and Audit Requirements​

Implement OAuth authentication for regulatory compliance:

  • Use enterprise-grade identity providers with audit logging
  • Configure appropriate session timeouts for sensitive applications
  • Enable multi-factor authentication through OAuth provider settings
  • Implement email verification requirements

Best Practices​

  • Use descriptive names for Auth Providers that clearly indicate their purpose such as google-employees or github-contractors while implementing specific email patterns to limit access to authorized users.
  • Rotate OAuth client secrets regularly and configure appropriate session lifetimes based on your security requirements.
  • Monitor authentication metrics consistently to detect unusual access patterns and maintain system security.

Next Steps​

  • Learn how to create and manage Auth Providers using the Auth Provider API
  • Explore Custom Frontends to understand how Auth Providers integrate with branded domains
  • Review Shares to learn how to protect services with OAuth authentication
  • Set up provider-specific OAuth applications using the Auth Provider Types reference