Identity Providers

Shoehorn uses OIDC (OpenID Connect) for authentication. It supports multiple identity providers out of the box.

Supported Providers

Provider	Config Value	Notes
Zitadel	zitadel	Recommended for open-source deployments
Okta	okta	Enterprise SSO
Microsoft Entra ID	entra-id	Microsoft 365 environments
Keycloak	keycloak	Self-hosted open-source

Zitadel Setup

Zitadel is the recommended identity provider and can be deployed alongside Shoehorn.

1. Create a Project

In the Zitadel console:

1. Create a new project (e.g., “Shoehorn”)
2. Note the Project ID

2. Create an Application

1. In the project, create a new Web application
2. Set the redirect URI: https://shoehorn.example.com/auth/callback
3. Set the post-logout redirect: https://shoehorn.example.com
4. Note the Client ID

3. Create a Service User

For server-to-server communication:

1. Create a Service User in the organization
2. Generate a Personal Access Token (PAT)
3. Grant the service user access to the project

4. Configure Shoehorn

AUTH_PROVIDER=zitadel
ZITADEL_URL=http://zitadel:8080              # Internal URL
ZITADEL_EXTERNAL_URL=https://auth.example.com # Browser-accessible URL
ZITADEL_PROJECT_ID=349308689758290610
ZITADEL_CLIENT_ID=349310449335993010
ZITADEL_SERVICE_USER_PAT=your-pat-here

Okta Setup

1. Create an Application

1. In the Okta admin console, go to Applications > Create App Integration
2. Select OIDC - OpenID Connect and Web Application
3. Set sign-in redirect URI: https://shoehorn.example.com/auth/callback
4. Set sign-out redirect URI: https://shoehorn.example.com
5. Assign users/groups

2. Configure Shoehorn

AUTH_PROVIDER=okta
OKTA_DOMAIN=your-org.okta.com
OKTA_CLIENT_ID=0oa1234567890abcdef
OKTA_CLIENT_SECRET=your-client-secret

Microsoft Entra ID Setup

1. Register an Application

1. In the Azure portal, go to Azure Active Directory > App registrations
2. Click New registration
3. Set redirect URI: https://shoehorn.example.com/auth/callback (Web)
4. Note the Application (client) ID and Directory (tenant) ID
5. Create a Client secret under Certificates & secrets

2. Configure API Permissions

Add these permissions:

• openid (delegated)
• profile (delegated)
• email (delegated)
• User.Read (delegated)

3. Configure Shoehorn

AUTH_PROVIDER=entra-id
ENTRA_TENANT_ID=your-tenant-id
ENTRA_CLIENT_ID=your-client-id
ENTRA_CLIENT_SECRET=your-client-secret

Group Claims

To enable group-based team mapping, configure your IdP to include group claims in the JWT token:

Zitadel

Groups are included by default in the groups claim.

Okta

1. Go to Security > API > Authorization Servers
2. Add a groups claim with filter “Matches regex .*”

Entra ID

1. In the app registration, go to Token configuration
2. Add a groups claim
3. Select Security groups

Session Management

• Sessions are stored in encrypted cookies (shoehorn_session)
• Cookie properties: HttpOnly, SameSite=Lax, Secure (HTTPS)
• Token refresh is automatic (transparent to the user)
• Set AUTH_ENCRYPTION_KEY for cookie encryption in production

Multi-Provider Support

Shoehorn can verify tokens from any OIDC-compliant provider. The JWT verifier auto-detects the issuer from the token and validates against the configured provider.