Clients

Clients in FerrisKey represent applications or services that interact with your IAM system. Each client is registered within a realm and is assigned its own credentials, roles, and permissions.

What are Clients?

A client is an entity (such as a web app, API, or service) that needs to authenticate and authorize users or itself against FerrisKey. Clients are fundamental for enabling secure access to your applications.

• Unique Credential: Each client has its own client ID and secret for authentication.
• Role Assignment: Clients can be assigned roles that define their permissions within the realm.
• Per-Realm Registration: Clients are registered within a specific realm, ensuring isolation.
• Protocol Support: Supports OAuth2, OpenID Connect, and other standard protocols.

Use Cases

Application Authentication

Register web, mobile, or backend applications as clients to enable user login and secure API access.

Service-to-Service Communication

Secure communication between microservices by registering each service as a client with its own credentials.

Third-Party Integrations

Allow external partners or SaaS products to integrate securely by registering them as clients.

Client Architecture

Registration & Credentials

Clients are registered with a unique client ID and secret. These credentials are used for authentication and token requests.

CREATE TABLE clients (
    id UUID PRIMARY KEY,
    realm_id UUID REFERENCES realms(id) NOT NULL,
    name VARCHAR(255) NOT NULL,
    client_id VARCHAR(255) NOT NULL UNIQUE,
    client_secret VARCHAR(255) UNIQUE,
    redirect_uris TEXT[],
    enabled BOOLEAN NOT NULL DEFAULT TRUE,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

Role Assignment

Roles are directly linked to a client via the client_id column, enabling per-client permission models within a realm.

CREATE TABLE roles (
    id UUID PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    description TEXT,
    permissions BIGINT NOT NULL DEFAULT 0,
    realm_id UUID NOT NULL REFERENCES realms(id) ON DELETE CASCADE,
    client_id UUID REFERENCES clients(id) ON DELETE CASCADE,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

• Per-Client Roles: Each role can be scoped to specific client, or left NULL for realm-wide roles.
• Fine-Grained Permissions: Assign only the necessary permissions to each client’s roles.

Security Best Practices

• Least Privilege: Assign only the required roles and permissions to each client.
• Secret Management: Store client secrets securely and rotate them regularly.
• Redirect URI Validation: Always specify and validate redirect URIs to prevent misuse.
• Audit Logging: All client authentication and authorization events are logged for compliance.

Create Client

To create a new client in FerrisKey, you can use either the web interface or the API. Each client requires a unique name, client ID, and will be registered within a specific realm.

Using the Web Interface

1. Navigate to your realm’s client management section
2. Click “Create Client” or the ”+” button
3. Fill in the required fields:
   • Client Name: A descriptive name for your application
   • Client ID: A unique identifier (auto-generated if left blank)
   • Redirect URIs: Valid redirect URLs for OAuth flows
   • Client Type: Choose between public or confidential client
4. Configure additional settings as needed
5. Click “Create” to register the client

Using the API

curl -X POST "https://your-ferriskey-instance/realms/{realm}/clients" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "string",
    "client_type": "string",
    "enabled": true,
    "name": "string",
    "protocol": "string",
    "public_client": true,
    "service_account_enabled": true
  }'

Once created, you’ll receive the client credentials that your application will use for authentication.