Audiences

Audiences in Authlink represent the protected resources and services that Clients can access on behalf of Subjects. Authlink currently focuses on API Resources as the primary audience type, with a robust framework designed to support additional audience types in the future.

API Resources

API Resources are Authlink's current audience implementation, providing comprehensive protection for APIs and web services.

Core Concept

An audience is fundamentally a protected API or service that requires authorization to access. In OAuth2 terms, the audience appears as the aud (audience) claim in access tokens, telling the resource server which API the token is intended for.

Audience Identity

Each API Resource has multiple identifiers serving different purposes:

Audience ID: Internal identifier for relationships and policy evaluation

• Immutable throughout the resource's lifecycle
• Used for internal references and data relationships
• Not exposed in tokens or external APIs

Identifier (URL): Public identifier used in OAuth2 flows

• Appears as the aud claim in access tokens
• Used as the audience parameter in authorization requests
• Typically a URL representing the API (e.g., https://api.example.com)

{
  "aud": "https://api.example.com",
  "sub": "user-123", 
  "iss": "https://identity.authlink.co.za",
  "scope": "read write",
  "permissions": ["view-documents", "create-document"]
}

API Resource Protection

API Resources define what can be accessed and who can access it through multiple authorization layers. These layers work with Subject permissions and Client authorization to control access.

Permission-based Access

Fine-grained permissions define specific actions within an API:

Permission Assignment: API Resources maintain a list of permissions that can be granted for that resource

Granular Control: Permissions represent specific actions (read, write, delete, admin)

Scope Mapping: OAuth2 scopes map to one or more permissions

Role-based Access

Roles provide convenient groupings of permissions:

Role Assignment: API Resources can accept specific roles for access

Permission Inheritance: Roles carry their associated permissions

Hierarchical Access: Different roles provide different levels of access

API Resource Client Authorization

API Resources control which clients can access them and what permissions those clients receive.

Confidential Client Access

Confidential clients can be granted direct access to API Resources:

Configure confidential client access to API Resources.

Public Client Access

Public clients access resources on behalf of users:

Configure public client access to API Resources. Public clients access resources on behalf of authenticated users.

API Resource Application Integration

API Resources support application-level access control where applications can have different permissions within the same resource.

Application Permissions

• Application Scoping: Different applications get different permissions
• Microservice Support: Each service can have specific access levels
• Deployment Isolation: Staging vs production permission differences
• Team-based Access: Different teams get different application permissions

API Resource Policy Integration

API Resources integrate with Authlink's policy system for advanced authorization scenarios.

Policy-based Access Control

• Dynamic Authorization: Policies evaluate context at runtime
• Conditional Access: Access based on time, location, risk, etc.
• Complex Rules: Multi-factor authorization decisions
• Compliance: Support for regulatory requirements

API Resource Token Configuration

API Resources define token settings that control how tokens are issued for that resource.

Token Settings

{
  "access_token_lifetime": 3600,
  "refresh_token_lifetime": 86400,
  "id_token_lifetime": 3600,
  "token_format": "JWT",
  "include_claims": [
    "sub",
    "permissions", 
    "roles",
    "tenant_id"
  ],
  "signing_algorithm": "RS256"
}

• Lifetime Control: Different token durations for different resources
• Format Selection: JWT vs reference tokens
• Claim Inclusion: What information appears in tokens
• Security Settings: Signing and encryption preferences

Multi-tenancy Support

API Resources support tenant-based isolation:

Tenant Scoping

• Tenant Isolation: Resources scoped to specific tenants
• Cross-tenant Resources: Shared services across tenants
• Tenant-specific Permissions: Different access rules per tenant
• Data Separation: Logical separation of tenant data

API Resource Management

Managing API Resources effectively is crucial for protecting your APIs and ensuring proper access control. Authlink provides two primary approaches for API Resource 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 API Resources through an intuitive user experience.

API Resource Management Interface

The Portal's API Resource management interface allows administrators to:

• Create New API Resources: Define protected APIs with identifiers and permissions
• Update Resource Settings: Modify token configurations, lifetime settings, and security options
• Manage Client Authorization: Control which clients can access specific API Resources
• Assign Permissions: Configure available permissions and roles for each resource
• Monitor Access Patterns: Review client usage and access logs
• Configure Token Settings: Set token lifetimes, formats, and included claims

Portal Access

Access to API Resource management features requires appropriate administrative permissions. Ensure your account has the necessary roles before attempting to manage API Resources.

API Resource Creation Workflow:

Navigate to https://portal.authlink.co.za/api-resources and click on the "New API Resource" button

Fill in the required form fields needed to create an API resource and submit once finished

API Management

For developers who need to manage API Resources programmatically, the Portal API provides comprehensive CRUD operations and client authorization management.

Authlink Portal API Resource

The Authlink Portal API provides programmatic access to all API Resource management operations available through the web portal. This API resource enables:

• Complete CRUD Operations: Create, read, update, and delete API Resources
• Client Authorization Management: Programmatically manage which clients can access resources
• Permission Configuration: Set up and modify permission structures
• Token Configuration: Configure token settings and claim inclusion rules

Setting Up API Access

To manage API Resources through the Portal API, follow the authentication setup process detailed in the Client Management section. The same confidential client and authentication flow applies to API Resource management.

API Operations

Once authenticated, your confidential client can perform API Resource management operations:

API Resource Management Examples:

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

# Get specific API Resource
curl -X GET https://portal.authlink.co.za/api/api-resources?apiResourceId=550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json"

# Create API Resource
curl -X POST https://portal.authlink.co.za/api/api-resources \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test API Resource",
    "description": "API resource for testing purposes.",
    "identifier": "https://api.example.com"
  }'

# Delete API Resource
curl -X DELETE https://portal.authlink.co.za/api/api-resources \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "apiResourceId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Best Practices

• Use meaningful and stable URLs as API Resource identifiers
• Implement least-privilege principle when authorizing clients
• Regularly audit client authorizations and remove unused access
• Monitor API Resource usage patterns for security anomalies
• Configure appropriate token lifetimes based on security requirements
• Document permission schemas clearly for development teams

Understanding audience types, particularly API Resources, is essential for protecting your APIs and services with Authlink.