Security

Introduction

Golden Core implements enterprise-grade security with multiple authentication methods, role-based access control, and fine-grained permissions. This guide covers authentication, authorization, and security best practices.

Authentication Methods

Golden Core supports three authentication mechanisms:

Username and Password

Traditional authentication with email and password.

Endpoint: POST /api/security/auth

JSON

{
  "email": "[email protected]",
  "password": "SecurePassword123!"
}

Response:

JSON

{
  "token": "eyJhbGciOiJIUzUxMiJ9...",
  "type": "Bearer",
  "expiresIn": 3600000
}

Password Requirements:

Minimum 8 characters
At least 1 uppercase letter
At least 1 lowercase letter
At least 1 digit
At least 1 special character

JWT Token Authentication

After authentication, use JWT token for all subsequent requests.

Header Format:

CODE

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

Token Properties:

Contains user identity and role
Signed with HMAC512 algorithm
Configurable expiration time
Self-contained (no server-side sessions)

Single Sign-On (SSO)

Integration with external identity providers via OpenID Connect.

Supported Providers:

Google Workspace
Microsoft Azure AD
Custom OpenID Connect providers

Authentication Flow:

User authenticates with SSO provider
Obtain OpenID token from provider
Submit token to Golden Core:

JSON

POST /api/security/auth
{
  "email": "[email protected]",
  "openIdToken": "eyJhbGciOiJSUzI1NiJ9..."
}

Receive JWT token for Golden Core session

Advantages:

Centralized identity management
Single sign-on experience
Automatic user provisioning
No password management in Golden Core

Access Tokens for API Integration

For programmatic API access, use long-lived access tokens.

Creating Access Tokens

Endpoint: POST /api/security/tokens
Permission: security.token.save

JSON

{
  "name": "ETL Integration Token",
  "role": "STEWARD",
  "expires": "2026-01-30T00:00:00Z"
}

Response:

JSON

{
  "id": "t-abc123",
  "token": "golden:dGhpc2lzYXRva2Vu...",
  "name": "ETL Integration Token",
  "role": "STEWARD",
  "expires": "2026-01-30T00:00:00Z"
}

Token value is shown only once. Copy and store securely immediately.

Using Access Tokens

Include as Bearer token:

CODE

Authorization: Bearer golden:dGhpc2lzYXRva2Vu...

Managing Access Tokens

List tokens:

BASH

GET /api/security/tokens

Delete token:

BASH

DELETE /api/security/tokens/{id}

Regenerate token:

BASH

PUT /api/security/tokens/{id}/reset

Authorization Model

Role-Based Access Control (RBAC)

Golden Core uses roles to group permissions.

Built-in System Roles

Role	Description	Typical Users
ADMIN	Full system access	System administrators
STEWARD	Data management and curation	Data stewards, analysts
USER	Read-only access	Business users, viewers

System roles cannot be modified or deleted. They provide baseline security.

ADMIN Role Privileges

All operations (* wildcard)
User management
Security configuration
System configuration
Full entity, table, and resource access

STEWARD Role Privileges

View and manage entities
Work with golden records and buckets
Manage files and resources
View events and tasks
Execute ETL operations
Cannot manage users or security settings

USER Role Privileges

List and view entities
List and view tables
View golden records (read-only)
View metrics
Cannot modify data or configuration

Custom Roles

Organizations can define custom roles:

JSON

{
  "type": "role",
  "id": "data_analyst",
  "description": "Data analysis role",
  "privileges": [
    {"key": "entity.list", "type": "ALLOW"},
    {"key": "entity.view", "type": "ALLOW"},
    {"key": "golden.searchRecord", "type": "ALLOW"},
    {"key": "golden.viewRecord", "type": "ALLOW"},
    {"key": "table.view", "type": "ALLOW"},
    {"key": "table.export", "type": "ALLOW"}
  ]
}

User Management

User Types

Internal Users:

Authenticate with username/password
Managed within Golden Core
Password reset via email

SSO Users:

Authenticate via external provider
Auto-provisioned on first login
No password stored in Golden Core

User Properties

id - Unique identifier
email - Login username (must be unique)
name/surname - Display name
role - Assigned role
enabled - Account active status
locked - Lock status (after failed logins)
internal - Internal vs SSO user

User Operations

List Users

Endpoint: GET /api/security/users
Permission: security.user.list

Get User Details

Endpoint: GET /api/security/users/{id}
Permission: security.user.view

Create or Update User

Endpoint: POST /api/security/users
Permission: security.user.save

JSON

{
  "email": "[email protected]",
  "name": "Jane",
  "surname": "Smith",
  "role": "STEWARD",
  "enabled": true,
  "password": "SecurePassword123!"
}

Delete User

Endpoint: DELETE /api/security/users/{id}
Permission: security.user.delete

Enable/Disable User

Endpoint: PUT /api/security/users/{id}/enabled/{true|false}
Permission: security.user.save

Password Management

Password Requirements

Minimum 8 characters
At least 1 uppercase letter (A-Z)
At least 1 lowercase letter (a-z)
At least 1 digit (0-9)
At least 1 special character (!@$%^&, etc.)

Change Your Password

Endpoint: PUT /api/security/password/change

JSON

{
  "currentPassword": "OldPassword123!",
  "newPassword": "NewSecurePassword456!"
}

Reset Password (Self-Service)

Step 1: Request Reset

Endpoint: PUT /api/security/password/reset/{email}

System sends email with reset token (valid for 10 minutes).

Step 2: Set New Password

Endpoint: POST /api/security/password/update

JSON

{
  "token": "abc123...",
  "password": "NewPassword789!"
}

Admin Password Reset

Administrators can reset user passwords:

Endpoint: PUT /api/security/users/{id}/password
Permission: security.user.password

JSON

{
  "password": "TempPassword123!"
}

Advise users to change temporary passwords immediately.

API Security

Required Headers

All authenticated endpoints require:

CODE

Authorization: Bearer <jwt-token-or-access-token>
Content-Type: application/json

Public Endpoints

These endpoints do not require authentication:

POST /api/security/auth - Authentication
GET /api/security/whoami - Check authentication status
PUT /api/security/password/reset/{email} - Request password reset
POST /api/security/password/update - Complete password reset
GET /actuator/health - Health check

Error Responses

401 Unauthorized:

Missing authorization header
Invalid or expired token
Malformed token

403 Forbidden:

Valid authentication
Insufficient privileges for operation

Example:

JSON

{
  "status": 403,
  "error": "Forbidden",
  "message": "Access denied"
}

Security Best Practices

For End Users

Strong passwords - Follow complexity requirements
Protect credentials - Never share passwords or tokens
Report suspicious activity - Contact administrators immediately
Regular password changes - Update passwords periodically
Logout after use - Especially on shared computers

For API Integration

Secure token storage - Use environment variables or secret managers
Never commit tokens - Don't store in version control
Minimal privileges - Use role with least required permissions
Token rotation - Rotate tokens periodically
Monitor usage - Track token usage patterns
Revoke unused tokens - Disable tokens no longer needed

For Administrators

Principle of least privilege - Grant minimum required permissions
Regular access reviews - Audit user permissions quarterly
Strong password policies - Enforce password requirements
SSO preferred - Use SSO for centralized identity management
Monitor failed logins - Investigate account lock events
Token lifecycle management - Enforce expiration policies
User offboarding - Promptly disable departing users

Common Security Scenarios

Setting Up a New User

Create user account with appropriate role
Send credentials securely (not via email)
User logs in and changes password
Verify user can access required resources

Creating Integration Token

Determine minimum required permissions
Create custom role if needed
Generate token with appropriate expiration
Store token in secure secret manager
Test token with integration
Document token purpose and owner

Handling Compromised Credentials

Immediately disable user account or delete token
Review audit logs for unauthorized activity
Reset user password or generate new token
Notify security team
Investigate scope of compromise

User Unable to Access Resource

Verify user account is enabled
Check user role and permissions
Check entitlement filters
Review resource-level permissions
Test with admin account to isolate issue

Compliance and Auditing

Audit Trail

When tables have audit: true:

All record changes tracked
User identity captured
Timestamp recorded
Operation type logged (INSERT, UPDATE, DELETE)

Accessing Audit Information

View audit trail in expanded record view:

BASH

GET /golden/record/{id}?entity=customers&expanded=true

Compliance Features

Password complexity enforcement
Account lockout after failed attempts
Session timeout configuration
Audit trail for sensitive operations
Role-based access control
Entitlement filtering for data privacy

Troubleshooting

401 Unauthorized Error

Causes:

Missing Authorization header
Expired JWT token
Invalid token format
Token from different environment

Solutions:

Re-authenticate to get new token
Verify Authorization header format
Check token hasn't expired
Ensure using correct API endpoint

403 Forbidden Error

Causes:

Insufficient permissions for operation
User account disabled
Entitlement filter excluding resource

Solutions:

Verify user has required permission
Check user account is enabled
Contact administrator for access

Account Locked

Causes:

Multiple failed login attempts

Solutions:

Wait for automatic unlock (typically 15 minutes)
Contact administrator for manual unlock
Use password reset if password forgotten

Token Not Working

Causes:

Token expired
Token deleted or disabled
Wrong token format

Solutions:

Verify token hasn't expired
Check token is enabled
Regenerate new token if needed
Ensure proper Bearer format

API Authentication Example

Complete Flow

Step 1: Authenticate

BASH

curl -X POST https://api.example.com/api/security/auth 
  -H "Content-Type: application/json" 
  -d '{
    "email": "[email protected]",
    "password": "SecurePassword123!"
  }'

Response:

JSON

{
  "token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyQGV4YW1wbGUuY29tIn0...",
  "type": "Bearer",
  "expiresIn": 3600000
}

Step 2: Make Authenticated Request

BASH

curl -X GET https://api.example.com/entities 
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyQGV4YW1wbGUuY29tIn0..." 
  -H "Content-Type: application/json"

Step 3: Handle Token Expiration

When token expires (after expiresIn milliseconds):

Receive 401 Unauthorized response
Re-authenticate to get new token
Retry request with new token

Additional Resources

Swagger UI: /swagger-ui - Interactive API documentation
Health Check: /actuator/health - System status
Contact: System administrator for access issues