Managing Clients & Identity Providers

This guide covers how to register and manage applications (clients) and external Identity Providers in Shyntr.

Understanding Client Types

Shyntr supports two types of clients:

Type	Protocol	Use Case
OIDC Client	OAuth2 / OpenID Connect	Modern web apps, SPAs, mobile apps, APIs
SAML Client	SAML 2.0	Legacy enterprise applications

OIDC Clients

Creating an OIDC Client

Via CLI

Create confidential client (backend apps)

./shyntr create-client \
  --tenant-id default \
  --name "My Web Application" \
  --redirect-uris "https://app.example.com/callback,https://app.example.com/silent-refresh" \
  --secret "your-secure-secret"

Create public client (SPAs, mobile apps)

./shyntr create-client \
  --tenant-id default \
  --name "My React SPA" \
  --redirect-uris "https://spa.example.com/callback" \
  --public

CLI Flags Reference

Flag	Required	Default	Description
--tenant-id	No	default	Tenant this client belongs to
--client-id	No	Auto-generated	Unique client identifier
--name	No	New Client <id>	Human-readable name
--secret	No	Auto-generated	Client secret (ignored if --public)
--redirect-uris	No	http://localhost:8080/callback	Comma-separated callback URLs
--public	No	false	Public client (no secret)

Client Types Explained

Confidential Clients

For server-side applications that can securely store secrets:

┌─────────────────────────────────────────────────────────────┐
│                    Confidential Client                      │
├─────────────────────────────────────────────────────────────┤
│  • Has a client_secret                                      │
│  • Token endpoint authentication: client_secret_basic       │
│  • Can use authorization_code, client_credentials grants    │
│  • Example: Node.js backend, Python Flask, Go server        │
└─────────────────────────────────────────────────────────────┘

Public Clients

For applications where secrets cannot be stored securely:

┌─────────────────────────────────────────────────────────────┐
│                      Public Client                          │
├─────────────────────────────────────────────────────────────┤
│  • No client_secret                                         │
│  • Token endpoint authentication: none                      │
│  • Must use PKCE (Proof Key for Code Exchange)              │
│  • Example: React SPA, Vue app, iOS/Android mobile app      │
└─────────────────────────────────────────────────────────────┘

PKCE Requirement

Public clients should always use PKCE to protect against authorization code interception attacks. Shyntr enforces PKCE for public clients.

Managing OIDC Clients

List all clients

./shyntr list-clients --tenant-id default

View client details

./shyntr get-client abc123

Update client

./shyntr update-client abc123 \
  --name "Updated Application Name" \
  --redirect-uris "https://new-url.example.com/callback"

Regenerate client secret

./shyntr update-client abc123 \
  --secret "new-secure-secret"

Delete client

./shyntr delete-client abc123

OIDC Client Configuration Example

After creating a client, you'll receive configuration details:

Client Configuration

{
  "client_id": "abc123def456",
  "client_secret": "secret_xxxxxxxxxxxxxxxx",
  "token_endpoint_auth_method": "client_secret_basic",
  "redirect_uris": [
    "https://app.example.com/callback"
  ],
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "response_types": [
    "code"
  ],
  "scope": "openid profile email offline_access"
}

SAML Clients (Service Providers)

Creating a SAML Client

Register SAML Service Provider

./shyntr create-saml-client \
  --tenant-id default \
  --name "Salesforce" \
  --entity-id "https://acme.my.salesforce.com" \
  --acs-url "https://acme.my.salesforce.com/sso/saml"

Required Flags

Flag	Description
--entity-id	The exact Entity ID expected by the Service Provider
--acs-url	Assertion Consumer Service URL (POST binding)

Optional Flags

Flag	Default	Description
--tenant-id	default	Tenant this client belongs to
--name	SAML App	Human-readable name

Shyntr SAML Metadata

After creating a SAML client, configure the Service Provider with Shyntr's IdP metadata:

https://auth.example.com/saml/metadata

Or download for offline configuration:

curl -o shyntr-metadata.xml https://auth.example.com/saml/metadata

Managing SAML Clients

View SAML client

./shyntr get-saml-client "https://acme.my.salesforce.com"

Update SAML client

./shyntr update-saml-client "https://acme.my.salesforce.com" \
  --acs-url "https://new-acs.example.com/sso"

Delete SAML client

./shyntr delete-saml-client "https://acme.my.salesforce.com"

Identity Provider Connections

Shyntr can federate authentication to external Identity Providers.

OIDC Identity Providers

Connect external OIDC providers (Google, Azure AD, Auth0, etc.):

Connect Google as IdP

./shyntr create-oidc-connection \
  --tenant-id default \
  --name "Google Workspace" \
  --issuer "https://accounts.google.com" \
  --client-id "xxx.apps.googleusercontent.com" \
  --client-secret "GOCSPX-xxx"

Connect Azure AD as IdP

./shyntr create-oidc-connection \
  --tenant-id default \
  --name "Azure AD" \
  --issuer "https://login.microsoftonline.com/{tenant-id}/v2.0" \
  --client-id "azure-client-id" \
  --client-secret "azure-client-secret"

Required Flags

Flag	Description
--issuer	The Issuer URL (used for OIDC Discovery)
--client-id	Client ID from the external IdP
--client-secret	Client Secret from the external IdP

OIDC Discovery

Shyntr automatically discovers endpoints (authorization, token, userinfo, JWKS) from the provider's .well-known/openid-configuration document.

SAML Identity Providers

Connect external SAML IdPs (Okta, ADFS, etc.):

Connect Okta SAML as IdP

./shyntr create-saml-connection \
  --tenant-id default \
  --name "Okta Enterprise" \
  --metadata-file /path/to/okta-metadata.xml

Obtaining IdP Metadata

1. Okta: Admin Console → Applications → Your App → Sign On → View Setup Instructions → Download Metadata
2. Azure AD: Azure Portal → Enterprise Applications → Your App → Single sign-on → Federation Metadata XML
3. ADFS: https://adfs.company.com/FederationMetadata/2007-06/FederationMetadata.xml

Managing IdP Connections

List connections

./shyntr list-oidc-connections --tenant-id default
./shyntr list-saml-connections --tenant-id default

View connection details

./shyntr get-oidc-connection connection-id
./shyntr get-saml-connection connection-id

Delete connection

./shyntr delete-oidc-connection connection-id
./shyntr delete-saml-connection connection-id

Best Practices

Client Registration

1. Use descriptive names: Acme Dashboard - Production is better than app1
2. Minimize redirect URIs: Only register URIs you actually need
3. Separate environments: Create different clients for dev, staging, production
4. Rotate secrets: Regularly rotate client secrets for confidential clients

IdP Connections

1. Verify metadata: Always verify IdP metadata integrity before importing
2. Test in staging: Test IdP connections in a staging tenant first
3. Monitor certificate expiry: SAML certificates expire; set up monitoring
4. Use tenant isolation: Keep customer IdP connections in separate tenants

Troubleshooting

Common Issues

Invalid Redirect URI

Error: redirect_uri_mismatch

Solution: Ensure the redirect URI in the authorization request exactly matches one of the registered URIs (including trailing slashes, protocol, and port).

SAML Signature Validation Failed

Error: signature_verification_failed

Solution: Re-download the IdP metadata to get the latest signing certificate. Certificates may have been rotated.

OIDC Discovery Failed

Error: discovery_failed

Solution: Verify the issuer URL is correct and accessible. Check network connectivity and TLS certificates.

Next Steps

• Deploy with Docker Compose
• Configure Environment Variables
• Explore the complete CLI Reference