Identity and Access Management (IAM) app

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 ITRS Analytics platform.

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.

Built-in users, roles, and permissions Copied

When ITRS Analytics is installed, the platform IAM service bootstraps a default realm configuration. These built-in objects appear in the IAM app and should not be deleted. Some are marked read-only in the platform.

Built-in users Copied

Note

The admin and realm-admin accounts are treated as read-only users by the platform and must not be deleted.

Built-in roles Copied

Important

Built-in roles such as admin, user, iam-admin, platform-admin, and apps-admin are read-only and must not be deleted.

Built-in permissions Copied

Default permissions follow the naming pattern <resource>-<role>-<access> (for example, entities-user-read). Common defaults include:

Installed apps can add further default permissions. For example:

• Commands app: command-management-default-permission grants the user role read and write on command-management.
• Capacity app: capacity-admin (read/write for admin) and capacity-read (read for user).
• Signal Forecaster app: forecaster-config-management-admin and forecaster-forecast-management-admin for the user role.

For the full resource catalogue, see Resource types and permissions.

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 administrator Copied

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

2. Log in 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 out of the box include admin, user, iam-admin, platform-admin, and apps-admin. See Built-in users, roles, and permissions for what each role is for.

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.

The Resource dropdown lists every resource type registered on your deployment, such as platform defaults and installed apps. See Resource types and permissions for what each resource controls.

1. Click Permissions in the sidebar.

2. Click + Add Permission.

3. Configure permission:

   • Name — descriptive name (for example, “Production Gateway Access”).
   • Resource — select a resource type from the dropdown (for example, entities, entity-management, audit, capacity, or forecaster-config-management).
   • Roles/Users — assign the permission to specific roles or users.
   • Access Level:
     • Full Read Access — available when the resource supports read access.
     • Full Write Access — available when the resource supports write access.
     • For entities, you can also use expression-based access instead of full read.
   • Expression Filters (optional, for resources that support expressions such as entities) — 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 using a temporary password, follow the prompts to set a new password.
4. Access is 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)

API tokens Copied

API tokens provide long-lived credentials for programmatic access to ITRS Analytics APIs (for example, the API Gateway) without an interactive login. Tokens inherit access from the roles you assign when you create them.

Note

You need a principal with the iam-admin role (such as the built-in admin user) to create and delete API tokens.

Create an API token Copied

1. Open the IAM app.

2. Click API Tokens in the sidebar.

3. Click Add API Token to create a new token.

4. Configure the token:

   • Name — unique name for the token.
   • Description — optional description of its purpose.
   • Roles — one or more roles that define what the token can access. At least one role is required.
   • Expires In — lifetime of the token. Default is 5 minutes. Choose a unit of minutes, hours, or days. Maximum lifetime is 365 days.

5. Click Save. After successfully creating an API token, the API Token Created Successfully dialog shows the token value once.

   Important

   Copy and store the token value immediately. It is shown only once and cannot be retrieved again. After you close the dialog, you can still view token metadata (name, description, roles, created and expiry times) and delete the token, but you cannot edit it or reveal the secret again.

6. Optionally expand Curl example in the dialog for a sample Authorization: Bearer request against the entities API.

7. Click Copy Token & Close.

Manage API tokens Copied

• The API Tokens list shows Name, Description, Created, Expires At, and status (OK, expiring soon within 24 hours, or expired).
• Opening an existing token is view-only. You can delete the token, but you cannot change its name, roles, or expiry.
• Use the token as an HTTP Bearer credential when calling protected REST APIs:

Authorization: Bearer <token-value>

Best practices for API tokens Copied

• Grant only the roles the integration needs (least privilege).
• Prefer short lifetimes for temporary automation, and use longer lifetimes only when required.
• Store tokens in a secrets manager, not in source control.
• Delete unused or compromised tokens immediately.

Identity Provider integration Copied

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

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.
4. Set the Sync Mode. This controls how federated user profile attributes are synchronized from the IdP: Expand table

   Sync Mode	Behavior
   Inherit	Uses the default sync behavior for the provider (typical default).
   Import	Imports user attributes from the IdP on first login only.
   Force	Updates user attributes from the IdP on every login. This is useful when testing and must be used carefully in production.
   Legacy	Uses legacy Keycloak sync behavior.

Configure OIDC provider Copied

5. 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. When signature validation is enabled, the following options become available:
     • Use JWKS URL — controls whether signing keys are loaded from a JSON Web Key Set (JWKS) endpoint. Enable this when your identity provider publishes rotating keys at a stable JWKS URL, which is typical for OpenID Connect. Disable it when your environment is configured to validate tokens using a different trust mechanism and you do not want to use a JWKS URL for keys.
     • JWKS URL — The HTTPS URL of the provider’s JWKS document, which lists the public keys used to verify signed tokens. This field is required when the Use JWKS URL toggle is enabled. Use the URL provided in your identity provider’s documentation or discovery document, typically alongside the issuer or OpenID Provider metadata.

   You can also click Discover and enter the IdP OpenID configuration URL (for example, http://my-idp/realms/idp/.well-known/openid-configuration) to import endpoint settings automatically.

Configure SAML provider Copied

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

   

   a. Click the Discover button.

   b. Enter the SAML URL (for example, http://my-idp/realms/master/protocol/saml/descriptor).

   c. System imports configuration from XML metadata.

7. Option B: Manually configure the following fields:

   

   • Name — descriptive name (for example, Corporate SAML).
   • Signing Certificate — X.509 certificate used to validate signed SAML messages from the IdP.
   • Single Logout Service URL — IdP’s logout URL (optional).
   • Name Id Policy Format — SAML NameID format (usually urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress).
   • IDP Entity Id — unique identifier for the identity provider (Issuer).
   • Metadata Descriptor URL — URL where the IdP publishes SAML metadata. Used for Discover/import and optional certificate refresh.
   • Single Sign On Service URL — IdP’s SAML authentication URL.
   • Artifact Resolution Service URL — IdP artifact resolution endpoint when artifact binding is used.
   Expand table

   SAML toggle option	When enabled
   Validate Signatures	Verifies that SAML requests and responses from the IdP are digitally signed.
   Post Binding Logout	Uses HTTP-POST binding for Single Logout. When disabled, HTTP-Redirect binding is used.
   Post Binding Response	Uses HTTP-POST binding when responding to SAML requests from the IdP. When disabled, HTTP-Redirect binding is used. Commonly enabled for enterprise IdPs.
   Login Hint	Forwards a login_hint (subject) to the IdP so the IdP can pre-fill the login form.
   Enabled From Metadata	Indicates settings were populated from IdP metadata. Typically set automatically when you use Discover/import.
   Post Binding Authn Request	Sends authentication requests to the IdP using HTTP-POST binding. When disabled, HTTP-Redirect binding is used.
   Want Authn Requests Signed	Signs AuthnRequest messages with the realm key pair before sending them to the IdP. Enable when the IdP requires signed authentication requests.
   Add Extensions Element With Key Info	Includes a SAML Extensions element with KeyInfo in AuthnRequest messages. Enable only if your IdP requires this extension.
   Artifact Binding Response	Uses SAML artifact binding for responses. When disabled, the Post Binding Response setting applies instead. Many IdPs use POST only and leave this off.

   Match these binding and signing toggles to your IdP metadata or IdP administrator guidance. Incorrect combinations often produce opaque SAML errors such as INVALID_SIGNATURE or REQUEST_NOT_SUPPORTED.

8. Save your configuration changes.

Configure Identity Provider mappers Copied

Mappers are how group or role claims from your corporate IdP become local IAM roles. Permissions are still assigned in IAM to those roles.

After you save an identity provider, open it and select the Mappers tab to map IdP claims or SAML attributes to ITRS Analytics roles and user profile fields. Click Add Identity Provider Mapper, then choose a mapper type.

OIDC mapper types Copied

SAML mapper types Copied

Note

External users are synced into IAM but appear as read-only user records. Role mapping from the IdP only grants local roles. You must still create or assign Permissions in IAM so those roles can access entities and app resources.

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 include “Engineering”, “Operations”, and “Management”. Use IdP mappers to assign these roles automatically from IdP claims or attributes.

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).

Resource types and permissions Copied

Permissions in the IAM app grant Full Read Access, Full Write Access, or expression-based access on a selected resource. The Resource dropdown is populated dynamically from the platform and any installed apps, so the exact list depends on your deployment.

Platform resource types Copied

These resources are created when the platform realm is initialized:

Some internal resources (for example, backup, configuration-install, internal-entity-management, ingestion-policy-filter) are used by platform service accounts such as platform-admin and may not appear in the IAM Permissions resource list.

App resource types Copied

Installed apps register additional resource types. Common examples:

Note

If a resource does not appear in the dropdown, confirm the related app is installed and that its IAM configuration job completed successfully.

Access levels and expressions Copied

• Full Read Access — grants unrestricted read scope on the resource.
• Full Write Access — grants write scope where the resource supports modification.
• Expressions — available for resources that support them (notably entities). Expressions restrict which entities (and associated metrics) a user can see, for example source_gateway IN ('ITRS Demo', 'My-GW-Demo') or ENVIRONMENT != 'production'.

Supported expression operators include AND, OR, NOT, and IN. Multiple expression scopes on the same permission are evaluated independently with OR semantics unless you combine conditions in a single expression.

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 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 (OIDC) or attributes (SAML) in the token or assertion.
2. Configure mappers on the identity provider Mappers tab in the IAM app (Claim to Role, Attribute to Role, or Advanced variants).
3. Check claim or attribute names and values match exactly (unless regex matching is enabled on an advanced mapper).
4. Confirm the target local role already exists in IAM.

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 matches your installation (commonly obcerv or itrs-analytics).
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