跳转至主要内容

Tailscale

This guide explains how to set up Single Sign-On (SSO) between SmartLink and Tailscale using OpenID Connect with WebFinger for simplified configuration.

Prerequisites​

  • Tailscale account with a plan supporting custom SSO (Business or Enterprise)
  • Administrative access to Tailscale
  • Domain verified in Tailscale
  • Application configured in SmartLink with OpenID Connect
  • WebFinger configured on SmartLink (optional but recommended)

Overview​

Tailscale supports SSO authentication via OpenID Connect with a unique feature: WebFinger. This allows users to simply log in with their email address without needing to know the provider's URL.

1. Create the application​

  1. Log in to SmartLink as an administrator
  2. Go to Applications → Add
  3. Create a new application:
    • Name: Tailscale
    • URL: https://login.tailscale.com
    • Description: VPN Mesh Tailscale
    • Icon: Choose or upload the Tailscale icon

2. Configure OpenID Connect​

  1. In the Authentication tab
  2. Select OpenID Connect as the authentication type
  3. Configure the parameters:
    • Client ID: tailscale-xxxxxx (will be generated automatically)
    • Client Secret: secret-xxxxxx (will be generated automatically)
    • App ID: [appid] (unique identifier of the application in SmartLink)
    • Client Type: Confidential

3. Configure Redirect URLs​

Add the following URLs to Allowed Redirect URLs:

https://login.tailscale.com/a/oauth_response
https://controlplane.tailscale.com/a/oauth_response

4. Configure Scopes and Claims​

Required Scopes:

  • openid
  • profile
  • email

Additional Claims (optional):

  • groups: To map SmartLink groups to Tailscale ACLs
  • picture: For user avatar

WebFinger allows users to log in with their email instead of the full provider URL.

Verify WebFinger Configuration​

Your domain (not your SmartLink) should automatically expose WebFinger at:

https://<yourdomain>/.well-known/webfinger

Test with:

curl "https://example.com/.well-known/webfinger"

The response should contain:

{
  "subject": "acct:user@example.com",
  "links": [
    {
      "rel": "http://openid.net/specs/connect/1.0/issuer",
      "href": "https://your-smartlink.link.vaultys.org/api/oidc/[appid]"
    }
  ]
}

Configuration in Tailscale​

1. Access SSO Settings​

  1. Log in to Tailscale Admin Console
  2. Go to Settings → Identity provider
  3. Click on Configure custom OIDC

2. Configure OpenID Connect Provider​

Fill in the following fields:

  • Issuer URL: https://your-smartlink.link.vaultys.org
  • Client ID: [Copy from SmartLink]
  • Client Secret: [Copy from SmartLink]

Note: The application created in SmartLink automatically generates an [appid] that will be used in the endpoint URLs.

3. Endpoint Configuration (if not auto-discovered)​

If Tailscale does not automatically detect the endpoints via .well-known/openid-configuration, configure manually:

  • Configuration URL: https://your-smartlink.link.vaultys.org/api/oidc/[appid]/.well-known/openid-configuration
  • Authorization endpoint: https://your-smartlink.link.vaultys.org/api/oidc/[appid]/authorize
  • Token endpoint: https://your-smartlink.link.vaultys.org/api/oidc/[appid]/token
  • UserInfo endpoint: https://your-smartlink.link.vaultys.org/api/oidc/[appid]/userinfo
  • JWKS endpoint: https://your-smartlink.link.vaultys.org/api/oidc/[appid]/jwks

4. Attribute Mapping​

User mapping configuration:

  • Email claim: email
  • Name claim: name or email
  • Groups claim: groups (if using group-based ACLs)

5. Domain Configuration​

In Email domain requirements:

  • Add your email domain: @example.com
  • Enable Allow only verified domains

WebFinger Configuration for Simplified Login​

Advantages of WebFinger​

With WebFinger configured, users can log in using just:

user@example.com

Instead of:

https://your-smartlink.link.vaultys.org

DNS Configuration for WebFinger​

If your email domain is different from the SmartLink domain, add a redirection:

  1. Create a CNAME or A record for webfinger.example.com
  2. Configure your web server to redirect: 
    location /.well-known/webfinger {
        return 307 https://your-smartlink.link.vaultys.org/.well-known/webfinger$is_args$args;
    }

Test WebFinger with Tailscale​

  1. On the Tailscale login page
  2. Enter your email: user@example.com
  3. Tailscale should automatically discover SmartLink as the provider
  4. You will be redirected to SmartLink for authentication

Group-Based ACL Configuration​

  1. In the Tailscale application on SmartLink
  2. Ensure that the groups scope is enabled
  3. Verify that groups are returned in the claims

2. Configure Tailscale ACLs​

Example of ACL configuration in Tailscale:

{
  "groups": {
    "group:admin": ["user@example.com"],
    "group:dev": ["tag:dev-servers"]
  },
  "acls": [
    {
      "action": "accept",
      "src": ["group:admin"],
      "dst": ["*:*"]
    },
    {
      "action": "accept",
      "src": ["group:dev"],
      "dst": ["tag:dev-servers:*"]
    }
  ],
  "tagOwners": {
    "tag:dev-servers": ["group:admin"]
  }
}

3. Automatic Group Synchronization​

If configured correctly, SmartLink groups will be mapped to Tailscale:

  • SmartLink Group developers → group:developers in Tailscale
  • SmartLink Group admins → group:admins in Tailscale

Configuration Testing​

1. Initial Connection Test​

  1. Log out of Tailscale
  2. Go to login.tailscale.com
  3. Enter your corporate email
  4. You should be redirected to SmartLink
  5. Authenticate with your SmartLink credentials
  6. You should be connected to Tailscale

2. Test with Tailscale Client​

  1. Install the Tailscale client on your device
  2. Click on Log in
  3. Use your corporate email
  4. The client should open a browser to SmartLink
  5. After authentication, the client should connect

3. Permission Verification​

# Check connection status
tailscale status

# Check applied ACLs
tailscale netcheck

# Check tags and groups
tailscale debug acls

Troubleshooting​

"Invalid issuer" Error​

Issue: Tailscale does not recognize the SmartLink issuer

Solution:

  1. Verify that the issuer URL is exactly: https://your-smartlink.link.vaultys.org
  2. Test OpenID discovery with your appid: 
    curl https://your-smartlink.link.vaultys.org/api/oidc/[appid]/.well-known/openid-configuration
  3. Ensure the issuer in the configuration matches the returned one

WebFinger Not Working​

Issue: Simple email login is not working

Solution:

  1. Test WebFinger directly: 
    curl "https://your-smartlink.link.vaultys.org/.well-known/webfinger?resource=acct:test@example.com"
  2. If your email domain is different, configure DNS redirection
  3. Check CORS headers if necessary

"User not authorized" Error​

Issue: User cannot access Tailscale after authentication

Solution:

  1. Verify that the user's email matches the configured domain
  2. Ensure the user is assigned to the application in SmartLink
  3. Check Tailscale Admin Console logs

Groups Not Synchronized​

Issue: Group-based ACLs are not working

Solution:

  1. Verify that the groups scope is enabled
  2. Test the UserInfo endpoint to see the groups: 
    curl -H "Authorization: Bearer TOKEN" https://your-smartlink.link.vaultys.org/api/oidc/[appid]/userinfo
  3. Check the format of the returned groups (array of strings)
  4. Adjust Tailscale ACLs to match the group format

SSL Certificate Error​

Issue: SSL validation error during connection

Solution:

  1. Ensure you are using a valid SSL certificate (not self-signed)
  2. Check the full certificate chain
  3. Test with: 
    openssl s_client -connect your-smartlink.example.com:443 -showcerts

Security​

Best Practices​

  1. Mandatory HTTPS: Never use HTTP for OAuth endpoints
  2. Verified Domains: Limit access to verified email domains
  3. Secret Rotation: Regularly change the Client Secret
  4. Strict ACLs: Use the principle of least privilege
  5. Audit Logs: Monitor connections in Tailscale Admin

MFA Configuration​

Tailscale inherits MFA configuration from SmartLink:

  1. Enable MFA in SmartLink for users
  2. Users will need to authenticate with MFA when logging into Tailscale

Access Revocation​

To revoke a user's access:

  1. Disable or remove the user in SmartLink
  2. Tailscale access will be automatically revoked upon token expiration
  3. For immediate revocation, also remove the device in Tailscale Admin

Advanced Configuration​

Custom Session Expiration​

In SmartLink, configure token lifetimes:

  • Access Token: 1 hour (recommended)
  • Refresh Token: 30 days
  • Tailscale Session: Aligns with the Refresh Token

Integration with Headscale​

If using Headscale (open-source control server):

  1. Follow the Headscale guide
  2. OpenID configuration is similar
  3. WebFinger also works with Headscale

Automation with Terraform​

Example Terraform configuration for Tailscale:

resource "tailscale_acl" "main" {
  acl = jsonencode({
    groups = {
      "group:admin" = ["user@example.com"]
    }
    acls = [
      {
        action = "accept"
        src    = ["group:admin"]
        dst    = ["*:*"]
      }
    ]
  })
}

Resources​