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

Understanding Scopes & Claims

Before creating clients, it's important to understand how Shyntr handles data visibility using Scopes and Claims:

• Claim: A single piece of information about a user (e.g., email, given_name, department).
• Scope: A bundle or permission bucket that groups multiple claims together (e.g., the profile scope typically contains name, family_name, and picture).

When you create a client in Shyntr, you assign it allowed Scopes. During login, the user grants these scopes. Shyntr then automatically filters the user's raw data and embeds only the permitted Claims into the final OIDC id_token or SAML AttributeStatement.

OIDC Clients

Creating an OIDC Client

Strict OIDC Enforcement

Shyntr enforces strict OpenID Connect specifications for high security:

1. Refresh Tokens: Requesting the offline_access scope is not enough. You must explicitly add refresh_token to the client's grant_types list to receive one.
2. Response Modes: For the authorization code flow, you must explicitly whitelist query in the client's response_modes.
3. Secure Logout: To prevent Open Redirect attacks, Shyntr will block post-logout redirects unless the exact URI (including trailing slashes) is registered in the client's post_logout_redirect_uris array.

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](https://app.example.com/callback,https://app.example.com/silent-refresh)" \
  --post-logout-uris "[https://app.example.com/](https://app.example.com/)" \
  --scopes "openid,profile,email,offline_access" \
  --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](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
--post-logout-uris	No	-	Exact URIs allowed for redirection after logout
--scopes	No	openid,profile,email,offline_access	Comma-separated allowed scopes
--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](https://acme.my.salesforce.com)" \
  --acs-url "[https://acme.my.salesforce.com/sso/saml](https://acme.my.salesforce.com/sso/saml)" \
  --slo-url "[https://acme.my.salesforce.com/sso/slo](https://acme.my.salesforce.com/sso/slo)" \
  --allowed-scopes "openid,profile,email"

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
--slo-url	-	Single Logout (SLO) Service URL
--allowed-scopes	-	Scopes used to map claims to the SAML Response
--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/t/default/saml/idp/metadata](https://auth.example.com/t/default/saml/idp/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](https://accounts.google.com)" \
  --client-id "xxx.apps.googleusercontent.com" \
  --client-secret "GOCSPX-xxx" \
  --scopes "openid,profile,email"

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.

Outbound Policy Enforcement

The issuer URL is validated against Shyntr's outbound policy rules before discovery is performed.

If the destination violates outbound security restrictions, the connection creation will be rejected.

SAML Identity Providers

Connect external SAML IdPs (Okta, ADFS, etc.) using either a local file or a dynamic URL:

Outbound Policy Enforcement

When --metadata-url is used, Shyntr validates the outbound request against outbound policy rules before fetching metadata.

Requests to disallowed destinations are blocked before execution.

Dynamically Connect Okta SAML as IdP

./shyntr create-saml-connection \
  --tenant-id default \
  --name "Okta Enterprise" \
  --metadata-url "[https://dev-xxx.okta.com/app/xxx/sso/saml/metadata](https://dev-xxx.okta.com/app/xxx/sso/saml/metadata)"

Connect Okta SAML as IdP

./shyntr create-saml-connection \
  --tenant-id default \
  --name "Legacy ADFS" \
  --metadata-file /path/to/adfs-metadata.xml \
  --sign-request=true

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.

Federation Endpoints Cheat Sheet

When configuring external Identity Providers (like Okta/Keycloak) or internal Service Providers (like your SaaS app), you will need Shyntr's exact endpoints.

(Replace default with your specific tenant_id if using multi-tenancy)

Shyntr as an Identity Provider (IdP)

Use these URLs when configuring your applications to trust Shyntr:

Protocol	Endpoint Type	URL
OIDC	Discovery Document	/t/default/.well-known/openid-configuration
SAML	IdP Metadata	/t/default/saml/idp/metadata
SAML	SSO (Login) URL	/t/default/saml/idp/sso
SAML	SLO (Logout) URL	/t/default/saml/idp/slo

Shyntr as a Service Provider (SP)

Use these URLs when configuring external Identity Providers (Keycloak, Auth0, Corporate ADFS) to trust Shyntr:

Protocol	Endpoint Type	URL
OIDC	Callback (Redirect) URI	/t/default/oidc/callback
SAML	SP Metadata	/t/default/saml/sp/metadata
SAML	ACS (Assertion Consumer)	/t/default/saml/sp/acs
SAML	SLO (Single Logout)	/t/default/saml/sp/slo

Next Steps

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