Subjects

Subjects in Authlink represent the entities that can be authenticated and authorized within the system. Understanding subjects is fundamental to implementing secure authentication and authorization in your applications.

Subject Types

Authlink supports multiple types of subjects, each serving different use cases:

User Subjects

Users are the primary subject type, representing individual people who interact with your applications. This includes:

• End users accessing web applications
• Mobile app users
• API consumers with individual accounts
• Administrative users managing the system

Confidential Client Subjects

Confidential clients can act as subjects when they need to access resources on their own behalf (not on behalf of a user). This includes:

• Service-to-service authentication
• Background processes and scheduled tasks
• API integrations requiring system-level access
• Administrative automation tools

Future Extensions

Authlink's architecture is designed to support additional subject types as they become relevant:

• AI Agents: Autonomous systems that may need their own identity and permissions
• Device Identities: IoT devices or hardware tokens with authentication capabilities
• Organizational Units: Departments or teams as collective subjects

Core Identity

Every subject in Authlink has a stable, immutable identifier that ensures consistent identity across all authentication and authorization flows. This identity becomes crucial when Clients request access to Audiences on behalf of subjects.

Subject ID

The SubjectId is the most critical aspect of a subject:

• Immutable: Never changes once assigned, ensuring stable identity
• Opaque: Provides no information about the subject to external systems
• OAuth2/OIDC Compliant: Used as the sub claim in access tokens and ID tokens
• Cross-session: Remains consistent across multiple authentication sessions

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "aud": "https://api.example.com",
  "iss": "https://identity.authlink.co.za",
  "exp": 1640995200
}

User Subjects

The primary type of subject in Authlink is the User, representing individual people who interact with the system.

Profile Information

Users contain comprehensive profile information:

• Names: First name, last name, and full name
• Contact: Email address and phone number with verification status
• Identity: Government identifier for compliance scenarios
• Localization: Preferred locale and address information
• Custom Data: Extensible key-value pairs for application-specific data

Authentication State

User subjects track authentication-related state:

• Username: Optional unique username for login
• Email Verification: Whether the email address has been confirmed
• Phone Verification: Whether the phone number has been confirmed
• Status: Active, Inactive, or Deleted lifecycle state

Access Control

Subjects are the foundation of Authlink's access control system, with multiple layers of authorization.

Roles and Permissions

Subjects can be assigned both direct permissions and roles that contain collections of permissions:

• Direct Permissions: Individual permissions assigned specifically to a subject
• Roles: Named collections of permissions that can be assigned to multiple subjects
• Effective Permissions: The union of direct permissions and all permissions from assigned roles

Attributes

Subjects support custom attributes that provide additional metadata and context:

• Flexible Schema: Attributes can be added dynamically without schema changes
• Typed Values: Support for various data types (strings, numbers, booleans)
• Access Control: Attributes can be used in policy decisions
• Extensibility: Applications can define domain-specific attributes

Multi-tenancy Support

Authlink supports multi-tenant architectures where subjects can be isolated by tenant:

• Tenant Isolation: Subjects belong to specific tenants for data separation
• Cross-tenant Access: Controlled scenarios where subjects access multiple tenants
• Tenant-specific Roles: Roles and permissions scoped to specific tenants

Token Integration

Subjects are represented in OAuth2 and OIDC tokens with relevant claims. These tokens are issued by Clients and used to access Audiences:

Access Tokens

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "aud": "https://api.example.com",
  "iss": "https://identity.authlink.co.za",
  "scope": "openid profile roles permissions",
  "permissions": ["view-users", "create-document", "update-document"],
  "roles": ["editor", "reviewer"]
}

ID Tokens (OIDC)

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "name": "John Doe",
  "email": "john@example.com",
  "email_verified": true,
  "phone_number": "+1234567890",
  "phone_number_verified": false,
  "locale": "en-US"
}

Security Features

Token Versioning

Subjects include a token version that enables immediate token revocation:

• Version Increment: When roles/permissions change, the token version increments
• Token Invalidation: Existing tokens become invalid when version changes
• Security: Prevents use of tokens with outdated authorization information

Audit Trail

All subject modifications are tracked for security and compliance:

• Creation Tracking: Who created the subject and when
• Modification History: All changes with timestamps and responsible users
• Access Logs: Authentication and authorization events
• Compliance: Support for regulatory requirements and audit needs

Subject Management

Managing subjects effectively is crucial for maintaining security and ensuring proper access control. Authlink provides two primary approaches for subject management: the Authlink Portal web interface for administrators and the Portal API for programmatic management.

Portal Management

The Authlink Portal provides a comprehensive web interface for managing subjects through an intuitive user experience.

User Management Interface

The Portal's user management interface allows administrators to:

• Create New Users: Complete user registration with profile information
• Update User Profiles: Modify names, contact information, and verification status
• Manage Authentication: Set usernames, reset passwords, and handle verification
• Assign Permissions: Grant or revoke direct permissions and role assignments
• Set Custom Attributes: Add application-specific metadata and properties
• Monitor Activity: Review authentication logs and access patterns

Portal Access

Access to subject management features requires appropriate administrative permissions. Ensure your account has the necessary roles before attempting to manage subjects.

User Creation Workflow:

Navigate to https://portal.authlink.co.za/users and click on the "New User" button

Fill in the required form fields needed to create a user and submit once finished

Permission Management:

The user roles interface allows administrators to assign and manage roles for subjects. Use the switch controls to assign or revoke roles, and utilize the search functionality to quickly find specific roles by name when working with large role lists.

The user permissions interface provides granular control over individual permissions assigned to subjects. Toggle permissions on or off using the switch controls, and search for specific permissions by name to efficiently manage access rights.

API Management

For developers who need to manage subjects programmatically, Authlink provides a comprehensive Portal API that enables automated subject management workflows and integration with existing systems.

Authlink Portal API Resource

The Authlink Portal API is a system-defined resource that provides programmatic access to all subject management operations available through the web portal. This API resource:

• Always Exists: The Portal API resource is automatically available in every Authlink installation
• Comprehensive Access: Provides complete CRUD operations for subjects, roles, and permissions
• Secure by Design: Requires proper authentication and authorization for all operations
• RESTful Interface: Follows standard REST conventions for predictable integration

Setting Up API Access

To manage subjects through the Portal API, you need to establish proper authentication:

1. Create a Confidential Client

First, create a confidential client that will be used for API authentication:

Navigate to https://portal.authlink.co.za/confidential-clients and click on the "New Confidential Client" button

Fill in the required form fields needed to create a confidential client and submit once finished

2. Create Client Secret

After creating a confidential client, you must generate a client secret for secure authentication with the Portal API:

• Security Purpose: The client secret provides cryptographic proof of the client's identity
• Required for Authentication: Confidential clients must use both client ID and client secret for token requests
• Portal API Access: The secret enables secure server-to-server communication with the Portal API
• Secret Management: Store the secret securely as it will only be displayed once during creation

Navigate to the Client Secrets section

Fill in the required form fields needed to create a client secret and submit once finished

Remember to store the newly generated secret. This will only be available to copy once

3. Obtain Access Token

Use the client credentials to obtain an access token:

curl -X POST https://identity.authlink.co.za/api/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret" \
  -d "scope=roles permissions"

API Operations

Once authenticated, your confidential client can perform subject management operations:

User Management Examples:

# Get users
curl -X GET https://portal.authlink.co.za/api/users \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json"

# Get user
curl -X GET https://portal.authlink.co.za/api/users?userId=f8d8e49c-a487-41bc-ac08-176c4be687d9 \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json"

# Create user
curl -X POST https://portal.authlink.co.za/api/users \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith", 
    "email": "jane.smith@example.com",
    "phoneNumber": "0000000000",
    "identifierKind": 0,
    "countryIso2": "ZA",
    "identifier": "0000000000000"
  }'

# Update user
curl -X PUT https://portal.authlink.co.za/api/users \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json"
  -d '{
    "userId": "f8d8e49c-a487-41bc-ac08-176c4be687d9",
    "firstName": "Jane",
    "lastName": "Smith", 
    "email": "jane.smith@example.com",
    "phoneNumber": "0000000000",
    "identifierKind": 0,
    "countryIso2": "ZA",
    "identifier": "0000000000000"
  }'

# Delete user
curl -X DELETE https://portal.authlink.co.za/api/users \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json"
  -d '{
    "userId": "f8d8e49c-a487-41bc-ac08-176c4be687d9"
  }'

Best Practices

• Implement proper subject lifecycle management with clear creation and deletion policies
• Use meaningful custom attributes to enhance authorization decisions without exposing sensitive data
• Regularly review and audit subject permissions to maintain least-privilege access
• Monitor subject authentication patterns and implement anomaly detection for security
• Store subject credentials securely and never expose them in client-side code
• Implement proper token caching to avoid unnecessary token requests

Understanding subjects is fundamental to working with Authlink's authorization model. Next, learn how Clients integrate with subjects to request access to protected resources and establish authorization flows.