Skip to content

05-supported-providers.md

Latest commit

 

History

History
181 lines (119 loc) · 15 KB

05-supported-providers.md

File metadata and controls

181 lines (119 loc) · 15 KB

🔑 Supported providers

GitHub

To use GitHub for user authentication, create an OAuth2 application and configure the callback to https://<endpoint>/portals/<portal>/oauth2/callback (see examples depending on how Traefik Forward Auth is exposed).

Configure a provider with these options in the github property:

  • clientID: OAuth2 client ID of your application
  • clientSecret: OAuth2 client secret of your application

Full list of configuration options for GitHub and example

Google

To use Google for user authentication, create an OAuth2 application and configure the callback to https://<endpoint>/portals/<portal>/oauth2/callback (see examples depending on how Traefik Forward Auth is exposed).

Configure a provider with these options in the google property:

  • clientID: OAuth2 client ID of your application
  • clientSecret: OAuth2 client secret of your application

Full list of configuration options for Google and example

Microsoft Entra ID

To use Microsoft Entra ID (formerly Azure AD) for user authentication, create an OAuth2 application and configure the callback to https://<endpoint>/portals/<portal>/oauth2/callback (see examples depending on how Traefik Forward Auth is exposed).

Configure a provider with these options in the microsoftEntraID property:

  • tenantID: ID of the tenant where your application resides
  • clientID: Client ID of your application
  • clientSecret: Client secret of your application

Full list of configuration options for Microsoft Entra ID and example

Using Federated Identity Credentials

Using Federated Identity Credentials is an alternative to configuring your Microsoft Entra ID application with a client secret. This offers better security because there are no pre-shared secrets to manage, and easier maintenance since client secrets need to be rotated periodically.

Using Federated Identity Credentials is the recommended approach when:

  • The application is running on Azure on a platform that supports Managed Identity. Both system-assigned and user-assigned identities are supported.
  • The application is running on platforms that support Workload Identity Federation, for example on Kubernetes (on any cloud or on-premises) or other clouds.
  • The application is running on Kubernetes and can use service account tokens
  • The application is running on a node connected to a Tailscale network and you have deployed tsiam

Check the documentation for your platform on configuring the managed identity or the workload identity for your application.

To use Federated Identity Credentials, you first need to configure your Entra ID applictaion. The steps below show an example for using managed identity; for using workload identity federation, consult the documentation for your platform.

For managed identity, you will need the object ID (i.e. "principal ID") of your identity. This can usually be found on the Azure Portal in the "Identity" section of your resource.

# Set this to the ID of your Entra ID application
APP_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# Set this to the UUID of your managed identity
IDENTITY_OBJECT_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# Set the TENANT_ID environmental variable
TENANT_ID=$(az account show | jq -r '.tenantId')

az ad app federated-credential create \
  --id "$APP_ID" \
  --parameters "{\"name\": \"mi-${IDENTITY_OBJECT_ID}\",\"issuer\": \"https://login.microsoftonline.com/${TENANT_ID}/v2.0\",\"subject\": \"${IDENTITY_OBJECT_ID}\",\"description\": \"Federated Identity for Managed Identity ${IDENTITY_OBJECT_ID}\",\"audiences\": [\"api://AzureADTokenExchange\"]}"

Finally, configure Traefik Forward Auth by setting a value for clientAssertion:

  • AzureManagedIdentity: uses Azure Managed Identity with a system-assigned identity
  • AzureManagedIdentity=client-id: uses Azure Managed Identity with a user-assigned identity whose client id is "client-id" (e.g. "AzureManagedIdentity=00000000-0000-0000-0000-000000000000")
  • AzureWorkloadIdentity: uses Azure Workload Identity, e.g. in Kubernetes
  • KubernetesServiceAccountToken=path: uses a token read from a Kubernetes service account token file. If path is omitted, defaults to /var/run/secrets/kubernetes.io/serviceaccount/token.
  • tsiam=endpoint: uses tsiam to obtain Workload Identity from nodes that use Tailscale. Specify the endpoint of tsiam as value, e.g. tsiam=https://tsiam. Uses as resource name the constant value api://AzureADTokenExchange.

Other OpenID Connect providers

Traefik Forward Auth support generic OpenID Connect providers. This includes Auth0, Okta, etc.

To use an OpenID Connect provider for user authentication, create an application and configure the callback to https://<endpoint>/portals/<portal>/oauth2/callback (see examples depending on how Traefik Forward Auth is exposed).

Configure a provider with these options in the openIDConnect property:

  • tokenIssuer: Token issuer
    This is generally a URL like https://tenant.identityprovider.com/.
    Traefik Forward Auth will try to fetch the OpenID Configuration document at <tokenIssuer>/.well-known/openid-configuration; in this example, https://tenant.identityprovider.com/.well-known/openid-configuration.
  • clientID: Client ID of your application
  • clientSecret: Client secret of your application

The OpenID Connect provider supports additional configuration options that can be helpful to configure how Traefik Forward Auth communicates with the Identity Provider:

  • tlsInsecureSkipVerify: If true, skips validating TLS certificates when communicating with the Identity Provider. While this option can enable support for self-signed TLS certificates, it should be used with caution.
  • tlsCACertificatePEM: PEM-encoded CA certificate used when communicating with the Identity Provider.
  • tlsCACertificatepath: Path to a file containing the PEM-encoded CA certificate used when communicating with the Identity Provider.

Full list of configuration options for OpenID Connect and example

Pocket ID

To use Pocket ID for user authentication, create a new OAuth2 Client (application) and configure the callback to https://<endpoint>/portals/<portal>/oauth2/callback (see examples depending on how Traefik Forward Auth is exposed).

Configure a provider with these options in the pocketID property:

  • endpoint: Pocket ID server endpoint.
    This is generally a URL like https://pocketidid.example.com.
  • clientID: Client ID of your application
  • clientSecret: Client secret of your application

The Pocket ID provider supports additional configuration options that can be helpful to configure how Traefik Forward Auth communicates with the Pocket ID:

  • tlsInsecureSkipVerify: If true, skips validating TLS certificates when communicating with Pocket ID. While this option can enable support for self-signed TLS certificates, it should be used with caution.
  • tlsCACertificatePEM: PEM-encoded CA certificate used when communicating with Pocket ID.
  • tlsCACertificatepath: Path to a file containing the PEM-encoded CA certificate used when communicating with Pocket ID.

Full list of configuration options for Pocket ID and example

Using Federated Client Credentials

Using Federated Client Credentials is an alternative to configuring your Pocket ID application with a client secret. This offers better security because there are no pre-shared secrets to manage, and easier maintenance since client secrets need to be rotated periodically.

Using Federated Client Credentials is the recommended approach when:

  • The application is running on Azure on a platform that supports Managed Identity. Both system-assigned and user-assigned identities are supported.
  • The application is running on platforms that support Workload Identity Federation, for example on Kubernetes (on any cloud or on-premises) or other clouds.
  • The application is running on Kubernetes and can use service account tokens.
  • The application is running on a node connected to a Tailscale network and you have deployed tsiam.

To use Federated Client Credentials, you first need to configure your OAuth2 Client in Pocket ID, as described in the official documentation.

Finally, configure Traefik Forward Auth by setting a value for clientAssertion:

  • AzureManagedIdentity: uses Azure Managed Identity with a system-assigned identity
  • AzureManagedIdentity=client-id: uses Azure Managed Identity with a user-assigned identity whose client id is "client-id" (e.g. "AzureManagedIdentity=00000000-0000-0000-0000-000000000000")
  • AzureWorkloadIdentity: uses Azure Workload Identity, e.g. in Kubernetes
  • KubernetesServiceAccountToken=path: uses a token read from a Kubernetes service account token file. If path is omitted, defaults to /var/run/secrets/kubernetes.io/serviceaccount/token.
  • tsiam=endpoint: uses tsiam to obtain Workload Identity from nodes that use Tailscale. Specify the endpoint of tsiam as value, e.g. tsiam=https://tsiam. Uses as resource name the value of endpoint.

Tailscale Whois

You can configure Single Sign-On (SSO) for clients that access your Traefik server through Tailscale. Users will be automatically authenticated when the request comes through the Tailscale network.

This offers a similar behavior to the Tailscale nginx-auth component.

  1. Your container host must be joined to a Tailnet, and you must have the Tailscale service running on the host.
  2. Make sure that the socket /var/run/tailscale/ is mounted into the traefik-forward-auth container.
  3. Configure Traefik Forward Auth with a tailscaleWhois property in the provider's configuration:

You can restrict the Tailnets that can authenticate with your service using this option:

  • allowedTailnet: If set, restricts users who are part of this specific Tailnet. Note that due to how Tailscale works, Tailnet names are only returned for nodes that are part of the current Tailnet, and not nodes that are being added as "guests".

Traefik Forward Auth will also include in the session tokens Application Capabilities that are assigned to the node in the Tailnet's ACL configuration. Only capabilities listed in the capabilityNames option are included, whose default value is ["italypaleale.me/traefik-forward-auth"].

For example, you can assign app capabilities to a node by listing them in your ACL configuration:

"grants": [
  {
    "src": ["user@example.com", "group:engineering"],
    "dst": ["tag:traefik"],
    "app": {
      "italypaleale.me/traefik-forward-auth": [
        { /* Object 1 */ },
        { /* Object 2 */ }
      ],
    }
  }
]

The session tokens issued by Traefik Forward Auth will then include a claim {"italypaleale.me/traefik-forward-auth": [ { ... }, { ... } ]}.

Full list of configuration options for Tailscale Whois and example