Identity and Access Management (IAM) app

Note

Version 1.3.0 marks the General Availability (GA) of the ITRS Analytics IAM app, transitioning from its Beta phase into a fully supported, production-ready release.

Manage access and roles with IAM app Copied

The ITRS Analytics IAM (Identity and Access Management) app is a comprehensive management solution that provides centralized user authentication, authorization, and access control for the ITRS Analytics platform. It serves as the primary interface for managing users, roles, permissions, and identity provider integrations within the Obcerv ecosystem.

The application consists of three main components:

• Frontend UI — a modern web interface for managing IAM configurations.
• Backend service — a Java-based gRPC service that handles IAM operations.
• Keycloak integration — integration with Keycloak as the underlying identity and access management platform.

The IAM app serves as an important security layer within the ITRS Analytics platform, providing:

• Single point for user credential verification across all platform applications.
• Role-Based Access Control (RBAC) with resource-level and entity-level permissions.
• Integration with external identity providers via OIDC and SAML protocols.
• Token-based authentication for programmatic access to platform services.

Target users Copied

The IAM app is designed for the following user personas. This is just an example of targeted personas and is not limited to the roles listed below. It may vary depending on the business organization.

Primary users:

• System administrators — configure identity providers, manage system-wide security policies, and oversee user provisioning.
• Security officers — define and maintain role hierarchies, permission structures, and access control policies.
• Platform administrators — manage user accounts, reset passwords, and handle day-to-day IAM operations.

Secondary users:

• Application developers — generate and manage API tokens for service-to-service authentication.
• Support engineers — troubleshoot authentication issues and evaluate user permissions.
• End users — indirectly interact through login processes and permission-based feature access.

Comparison: Local users vs Identity Provider integration Copied

This section describes the two primary deployment patterns for the IAM app, along with detailed workflows, technical considerations, and best practices.

• Local users management
• Identity Provider integration

Local users management Copied

In the local users scenario, administrators manually create and manage all user accounts, roles, and permissions directly within the IAM app. This approach is suitable for:

• Small to medium deployments (up to 100 users).
• Organizations without enterprise identity providers.
• Development and testing environments.
• Quick-start deployments.

Initial setup for admnistrator Copied

1. Access the ITRS Analytics IAM app in the Web Console: https://<your-itrs-analytics-hostname>/admin/iam.

2. Login with admin credentials (default: username admin, password configured during installation).

Create roles Copied

After creating the role, you can assign it to users or associate it with permissions under the Users and Permissions sections.

Note

Pre-built roles available:

• admin — full system access including IAM management.
• user — standard user with default entity read access.
• Additional custom roles as needed.

1. Click Roles in the sidebar.

2. Click + Add Role.

3. Configure role:

   • Name — descriptive role name (for example, “Operations Team”, “Read-Only Users”)
   • Description — purpose of the role.

4. Save the role.

Create permissions Copied

You can assign permissions to individual users, roles, or both. Roles are typically used to manage access for groups of users.

Note

Default permission:

• entities-user-read: Gives all users with the user role full read access to all entities.
• This should be modified in production environments to restrict access appropriately.

1. Click Permissions in the sidebar.

2. Click + Add Permission.

3. Configure permission:

   • Name — descriptive name (for example, “Production Gateway Access”).
   • Resource — select from available resource types:
     • entities — access to monitoring data.
     • entity-management — ability to modify entity configurations.
   • Roles/Users — assign the permission to specific roles or users.
   • Access Level:
     • For entities — Full Read Access or custom expression-based access.
     • For entity-management — Read or Write access.
   • Expression Filters (optional) — define data-level restrictions.
     • Example: source_gateway = 'Production Gateway'
     • Example: environment = 'prod' AND region = 'us-east'

4. Save the permission.

Create local users Copied

Use this section to create user accounts managed directly by the IAM app. Local users authenticate with passwords stored in IAM and are suited for small teams, test environments, or deployments without an external identity provider.

1. Click Users in the sidebar.
2. Click + Add User.
3. Enter user details:
   • Username — unique login identifier (for example, “itrs.user”).
   • First Name — user’s first name.
   • Last Name— user’s last name.
   • Set initial password:
     • Enter a temporary password.
     • Toggle Temporary Password (user will be required to change on first login).
4. Save the user.

Operational procedures Copied

The following procedures cover routine, day-to-day administration for local users, including sign-in, password management, and account updates. Use these steps to handle common requests safely and consistently.

User login Copied

1. Navigate to https://<your-itrs-analytics-hostname>.
2. Enter username and password.
3. If temporary password, follow prompts to set new password.
4. Access granted based on assigned roles and permissions.

Password management Copied

• User self-service: Users can change their own password via the profile menu.

• Administrator reset:

  

  1. Navigate to Users > Select user.
  2. Click Reset Password.
  3. Enter new password.
  4. Toggle Temporary Password if user should change it.

User modification Copied

• Update user details — edit name, email, enabled status.
• Modify role assignment — add or remove roles.
• View Resource Access — display the resources along with their read or write permissions.
• Account deletion — permanently removes user and all associated data.

Best practices Copied

1. Role design:

   • Create roles based on job functions, not individual users.
   • Follow principle of least privilege.
   • Document role purpose and intended use.
   • Review and update roles quarterly.

2. Permission strategy:

   • Start with restrictive permissions and grant access as needed.
   • Use expression filters for data-level security.
   • Group related permissions logically.
   • Test permissions before rolling out to production.

3. User lifecycle:

   • Use temporary passwords for initial account creation.
   • Disable accounts promptly when users leave.
   • Regularly review user access rights.
   • Implement periodic password rotation.

4. Administrative access:

   • Limit number of users with admin role.
   • Use separate admin accounts (not shared credentials).
   • Enable MFA for administrative accounts (configure in Keycloak).
   • Review admin audit logs regularly.

Example configuration Copied

Scenario: Multi-tier access for monitoring team

Roles Created:
- monitoring-admin: Full access to all monitoring data
- monitoring-engineer: Read/write access to test environments
- monitoring-viewer: Read-only access to production dashboards

Permissions Created:
1. "All Entity Admin Access"
   - Resource: entities
   - Roles: monitoring-admin
   - Access: Full Read Access
   
2. "Test Environment Access"
   - Resource: entities
   - Roles: monitoring-engineer
   - Access: Full Read Access
   - Expression: environment = 'test' OR environment = 'dev'
   
3. "Production Dashboard View"
   - Resource: entities
   - Roles: monitoring-viewer
   - Access: Full Read Access
   - Expression: environment = 'prod' AND metric_type = 'dashboard'

Users Created:
- admin (Roles: monitoring-admin)
- engineer (Roles: monitoring-engineer)
- viewer (Roles: monitoring-viewer)

Identity Provider integration Copied

In the Add Identity Provider, users authenticate via an external identity provider (IdP) using either OIDC or SAML only.

This approach is ideal for:

• Enterprise deployments with existing identity infrastructure.
• Organizations requiring SSO across multiple applications.
• Compliance requirements for centralized identity management.
• Large user bases (100+ users).

Configure Identity Provider in IAM app Copied

1. Navigate to Identity Providers in the sidebar.
2. Click + Add Identity Provider
3. On the Type menu, select OIDC or SAML.

Configure OIDC provider Copied

4. Provide the following information in the fields for manual configuration:
   • Name — descriptive name (for example, Azure AD OIDC).
   • Authorization URL — IdP’s OAuth2 authorization endpoint.
   • Token URL — IdP’s token endpoint.
   • Logout URL — IdP’s logout endpoint (optional).
   • User Info URL — IdP’s user information endpoint.
   • Client ID — application/client ID from IdP.
   • Client Secret — client secret from IdP.
   • Scopes — OpenID scopes (for example, openid profile email).
   • Issuer — expected issuer claim in JSON web token.
   • Validate Signatures — enable to verify JSON web token signatures.

Configure SAML provider Copied

5. Option A: Import the metadata and proceed with the following steps.

   

   a. Click Discover button.

   b. Enter the SAML URL.

   c. System imports configuration from XML metadata.

6. Option B: Perform the manual configuration and complete the following steps.

   

   • Name — descriptive name (for example, Corporate SAML).
   • Single Sign-On Service URL — IdP’s SAML authentication URL.
   • Single Logout Service URL — IdP’s logout URL (optional).
   • IDP Entity ID — unique identifier for the identity provider.
   • Signing Certificate — certificate for SAML assertion validation.
   • Name ID Policy Format — SAML NameID format (usually urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)
   • Validate Signatures — enable to verify SAML assertion signatures

7. Save your configuration changes.

Configure role mapping Copied

External users are automatically synced to IAM but appear as read-only. You must configure permissions manually:

Create Roles (if not already created) Copied

Define roles matching your organizational structure.

For example roles: “Engineering”, “Operations”, “Management”.

Assign Permissions to Roles Copied

1. Navigate to ITRS Analytics IAM > Permissions.
2. Create permissions linking roles to resources.
3. External users inherit permissions through their roles.

User login journey Copied

First-time login Copied

1. Navigate to https://<your-itrs-hostname>.
2. The login page displays a Sign in with [Identity Provider] button.
3. Click the button to be redirected to your IdP.
4. Enter your credentials at the IdP (or use your existing SSO session).
5. The IdP redirects you back to ITRS Analytics with an authentication token.
6. IAM automatically creates or updates your user record.
7. You are logged in and can now see the ITRS Analytics dashboard.

Subsequent logins Copied

• If IdP session is active, user is automatically signed in (true SSO).
• If IdP session expired, user re-authenticates at IdP.

Logout Copied

• User logs out from ITRS Analytics.
• Optionally triggers logout at IdP (if Single Logout configured).

Restrict access to entities with RBAC Copied

All data within ITRS Analytics is represented as entities. By default, all users have full read access to these entities.

1. Navigate to the Admin > IAM > Permissions.

2. Select the specific permission you want to apply restrictions to.

   For this example, select the entities-user-read permission. By default, this permission grants all users with the user role full read access to all entities.

   

3. Modify this permission to limit full read access only to users with the admin role. To do this:

   a. Delete user in the Roles field.

   b. Add admin.

   c. Click Save.

4. Configure access for specific users or roles based on defined criteria.

   In this example, grant users with the user role access to a Gateway named Production Gateway. To do this:

   a. Click + Add Permission.

   b. Enter a suitable Name.

   c. Set the Resource to entities.

   d. Add the role user.

   e. Add an expression and set it to: source_gateway = 'Production Gateway'

   Note

   If Gateways are publishing to ITRS Analytics, the expression editor will display valid keys and values (for example, gatewayName and Production Gateway).

5. Click Save to apply the changes.

   Users with the user role will now only see the Production Gateway in the Entity Viewer and other areas of ITRS Analytics.

Troubleshooting Copied

User cannot log in Copied

Issue: Unable to sign in to ITRS Analytics.

Resolution:

1. Check IdP configuration in IAM (credentials, URLs).
2. Verify user is assigned to the application in the IdP.
3. Check redirect URIs match exactly.
4. Review Keycloak logs: /var/log/keycloak/keycloak.log.

User appears but has no access Copied

Issue: User can sign in but has no access to data or features.

Resolution:

1. Remember: permissions must be manually configured.
2. Check the user’s roles in the IAM UI.
3. Verify permissions are assigned to those roles.

Roles not syncing Copied

Issue: Roles or groups from the IdP are not reflected in IAM.

Resolution:

1. Verify IdP sends group/role claims in token.
2. Configure mappers in Keycloak.
3. Check claim names match exactly.

Cannot access IAM UI Copied

Issue: 404 Not Found or Connection Refused.

Resolution:

1. Check pod status: kubectl get pods -n itrs | grep iam.
2. Check logs: kubectl logs -n itrs iam-webplatform-xxxxx.
3. Verify ingress: kubectl get ingress -n itrs.
4. Check service: kubectl get svc -n itrs.

Authentication fails Copied

Issue: Invalid credentials or redirect loop.

Resolution:

1. Verify Keycloak is running.
2. Check Keycloak configuration in application.yaml.
3. Review Keycloak logs.
4. Verify realm name is obcerv.
5. Check client configuration in Keycloak.

Permissions not working Copied

Issue: User has access to everything or nothing.

Resolution:

1. Check the user’s roles in the IAM UI.
2. Verify permissions are assigned to roles.
3. Check Keycloak authorization policies.
4. Review permission expressions for syntax errors.

Identity provider login fails Copied

Issue: Redirect to IdP works but callback fails.

Resolution:

1. Verify redirect URI matches exactly in IdP config.
2. Check client ID and secret are correct.
3. Verify IdP certificate is valid (for SAML).
4. Check IdP sends required claims (email, name, etc.).
5. Review Keycloak broker logs.

Troubleshooting decision tree Copied

Problem: User cannot log in
├── Is this a local user?
│   ├── Yes → Check user exists and is enabled in IAM UI
│   │         Check password is correct
│   │         Check Keycloak is running
│   └── No → Is this an IdP user?
│       └── Yes → Check IdP configuration in IAM UI
│                 Check redirect URI matches
│                 Check user assigned to app in IdP
│                 Check IdP is reachable
│
Problem: User has no access to data
├── Can user log in?
│   ├── No → See "User cannot log in" above
│   └── Yes → Check user's roles in IAM UI
│             Check permissions assigned to roles
│             Use Evaluate feature to test permissions
│             Check entity expressions are correct
│
Problem: Identity provider integration not working
├── Is configuration saved in IAM UI?
│   ├── No → Complete IdP configuration and save
│   └── Yes → Check redirect URI in IdP matches exactly
│             Check client ID and secret are correct
│             For SAML: Verify certificate is valid
│             For OIDC: Test discovery URL
│             Check Keycloak logs for errors
│
Problem: Application not accessible
├── Check pod status (kubectl get pods -n itrs | grep iam)
├── Check ingress configuration
├── Check DNS resolution
└── Check firewall rules / network connectivity

IAM key terms and definitions Copied