Service setup

What this service does

IDENTITY Services is the shared authentication and directory source for your applications. It manages local service administrators, shared end users, OTP and password-based login, application registration, API auth keys, user-to-application assignment, audit logging, and one-way user sync.

Installation and local deployment

1. Make sure Docker and Docker Compose are available on the host.
2. Make sure your shared Traefik container is already running and can route auth.localhost.
3. From the project folder, start the stack.

cd /Users/mkargal/codex/deplAS

docker compose up -d --build

The stack runs two containers: the auth service and MySQL. Traefik remains external and forwards http://auth.localhost to this service.

Initial setup

1. Open the setup console at http://auth.localhost/setup.
2. Create or sign in with a local administrator account.
3. Set the Public hostname and token secret under Platform.
4. Configure OTP Providers if SMS or email OTP delivery is required.
5. Register each consuming application and define its allowed IP addresses.
6. Create an API Auth Key for each registered application.
7. Create or import users in Directory and assign them to one or more applications.

Application onboarding model

How other applications integrate

1. Register the application in Platform.
2. Add the allowed source IPs or CIDR ranges for that application.
3. Create an API auth key and store it securely in the consuming app.
4. Assign users to that application in Directory.
5. Call the auth APIs by sending X-Auth-Service-Key with each request.

curl http://auth.localhost/users/sync   -H "X-Auth-Service-Key: ask_your_api_key"

The service identifies the calling application from the API key, checks the request IP against the allow-list, and returns only users assigned to that application.

Recommended end-user login flow for consuming apps

1. User enters email address or mobile number in the consuming app.
2. The app calls /auth/register or /auth/otp/request to validate that the user exists in the shared directory and is assigned to that application.
3. If the user does not exist, the response is User not in the directory service.
4. If the user exists but is not assigned, the response is You are not allowed to access this application. Contact Administrator.
5. If the user is valid and assigned, continue with OTP verify or password login.
6. Store access and refresh tokens in the consuming application session.
7. Use /auth/session to validate tokens and load the authenticated user profile.

User sync contract

Sync is one-way from IDENTITY Services to the consuming application. The consuming application must not push user changes back into this service.

• Use /users/sync to retrieve assigned users.
• Store auth_user_id from this service in the consuming application.
• Update local copies only when mapped fields change and sync_hash changes.
• Do not sync local Identity Services admin accounts to consuming applications.
• Mapped fields include name, mobile_number, email, optional emp_id, and status-related data.

Maintenance and operations

Backup and recovery

The durable data lives in MySQL and the mounted data volume used for uploaded branding assets. Back up both on a regular schedule.

docker compose ps

docker compose logs --tail=100 auth-service

docker compose logs --tail=100 mysql

• Back up the MySQL database before upgrades.
• Back up persistent volumes that contain uploaded assets.
• After recovery, verify the setup console, application registry, API keys, and OTP configuration.

Security checklist

• Use a strong token secret in production.
• Restrict each application with an explicit IP allow-list.
• Rotate API auth keys periodically.
• Review audit events for rejected IPs and unusual API activity.
• Use HTTPS at the reverse proxy in non-local environments.
• Limit local administrator accounts to people who manage the identity service itself.

Troubleshooting