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.

Configuration in SmartLink

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

5. WebFinger Configuration (Recommended)

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] which 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. Enable Groups in SmartLink

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

2. Configure Tailscale ACLs

Example 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 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 groups 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 delete the user in SmartLink
2. Tailscale access will be automatically revoked upon token expiration
3. For immediate revocation, also delete 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 you are 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

• Tailscale SSO Documentation
• WebFinger RFC 7033
• SmartLink OpenID Connect API
• Tailscale Forum