Overview

The IDSYS document defines how Gateway integrates with an external identity management system such as:

• LDAP

• Active Directory (AD)

• Linux PAM

IDSYS controls:

• User authentication

• Group resolution

• Token-based authentication

• Token administration privileges

• Identity inheritance across Root, Tenant, and Storage Domain scopes

IDSYS documents are JSON-formatted configuration objects. An IDSYS document may exist at:

• Root level

• Tenant level

• Storage domain level

When multiple IDSYS documents exist, the lowest level overrides the higher level. If a lower level does not define an IDSYS, it inherits from the higher level.

Common IDSYS Fields

Below are the common fields within all IDSYS documents. Fields specific to the back-end identity management system are broken out into separate sections.

The tokenAdmin field defines the default principal (user or group) trusted to manage authentication tokens for other users.

Token administration includes the ability to:

• Create authentication tokens on behalf of other users

• List tokens belonging to other users

• Delete tokens belonging to other users

User and Group Support

Both IDSYS and policy support:

• Users

• Groups

When a group is specified, all members of the group are granted token administration permissions. Nested or recursive groups are not supported.

The tokenAdmin field accepts a principal name as a string. The format is the same for both users and groups.

For example:

The value is resolved by the configured identity management system:

• If admin matches a user, that user is treated as the token administrator.

• If admin matches a group, all members of that group are granted token administration permissions.

There is no syntax difference between users and groups in the IDSYS configuration. Resolution is determined by the identity provider (LDAP, Active Directory, or PAM).

Name Conflict Between User and Group

If the same name exists as both a user and a group (for example, "admin"):

• The value is resolved by the identity provider.

• Gateway does not provide a way to explicitly specify whether the value refers to a user or a group.

To avoid ambiguity:

• Use distinct names for users and groups, or

• Use fully qualified names where supported

When to Use IDSYS vs Policy

Use IDSYS tokenAdmin when:

• Defining a default or single token administrator

• Assigning a single user or group

Use policy (TokenAdmin action) when:

• Granting access to multiple users or groups

• Enabling cross-tenant or cross-scope access

• Implementing fine-grained access control

Policy can extend or override the tokenAdmin value defined in IDSYS.

Multi-Tenant and Cross-Scope Behavior

Policy-based authorization enables token administration across IDSYS scopes.

A user or group defined in one scope (for example, Root) can perform token administration in another scope (for example, Tenant) if:

• The principal is properly qualified, and

• A policy grants the TokenAdmin action in that scope

IDSYS Scope and Inheritance

The tokenAdmin value follows the IDSYS precedence model:

• Root IDSYS applies cluster-wide unless overridden

• Tenant IDSYS overrides Root if defined

• Domain IDSYS overrides Tenant if defined

Policy evaluation is applied within the effective IDSYS scope of the request.

When using HTTP Basic authentication (that is, authentication without tokens or S3 HMAC), user credentials are validated against the configured identity management system.

• For LDAP, the password is validated using the configured user attribute (commonly userPassword).

• For PAM, the system uses the underlying operating system authentication mechanism.

Passwords may be stored and validated using formats supported by the respective identity provider.

LDAP and AD Examples

These are examples of IDSYS documents for LDAP and Active Directory. They contain fields specific to LDAP as well as fields common to all IDSYS documents.

LDAP

The block beginning with "uidAttribute" makes this specific to Active Directory:

Active Directory

LDAP and AD Fields

These are the fields within the IDSYS document specific to the LDAP or Active Directory back-end identity management system.

The adminDN and adminPassword parameters define the credentials with which the Gateway binds to the LDAP system to perform queries and read records for users and groups. The adminDN entity within LDAP needs to have read level access (rscdx privileges) within the LDAP tree. It is not necessary to grant write or manage level access to Gateway.

• A user's name in an access control Policy document is the value of the LDAP attribute named by the uidAttribute parameter. This is the uid attribute of a user's LDAP record by default.

• A group's name in an access control Policy document is the cn attribute for the group LDAP entity. The name of this attribute cannot be configured. A group's name may contain spaces and other non-alphanumeric characters.

PAM Example

There are no fields within the IDSYS document specific to the PAM back-end identity management system. Follow this process to implement identity management if using PAM:

1. Because the root user (uid=0) on this Content Gateway server cannot be used to authenticate to the Gateway, create another user (such as superuser@admindomain.example.com) on this server for this purpose. 

2. Copy and paste this example into the IDSYS document: /etc/caringo/cloudscaler/idsys.json.

   {"pam": { "name" : "idsys-pam", "description": "PAM identity management configuration", "cookieName": "token", "tokenPath": "/.TOKEN/", "tokenAdmin": "superuser@admindomain.example.com" } }

3. Update the tokenAdmin to match the authentication user.

Modifying IDSYS

The root IDSYS configuration is stored in the idsys.json file on the Gateway server's disk so it is always available and an administrator can always modify it. This prevents locking oneself out of the storage cluster. Changes to the local file take effect without the need to restart the Gateway.

See Defined ETC DocumentsPreview for modifying a tenant or storage domain's sub-resource through the management API.

See SCSP Context Sub-ResourcesPreview for details on modifying a storage domain's sub-resource through the storage API.

The entire JSON document with all fields must be provided in the update request, even if one field is being modified when updating an IDSYS sub-resource through the management API or the storage API.

IDSYS Precedence Model

The identity system is described by IDSYS documents can exist at the root, tenant, and storage domain within the system. The lowest level overrides the higher levels when IDSYS documents exist at multiple levels in the hierarchy. It inherits from a higher level when a lower level lacks an IDSYS.

Open

All tenants and all storage domains inherit from the Root IDSYS if a Root IDSYS exists. There is one identity management system with one set of users and groups. Each tenant and the storage domains owned by them share an identity system separate from the Root IDSYS if the tenants each defines an IDSYS. The storage domains inherit from the Tenant IDSYS.

The IDSYS inheritance also works at the field level. Tenant and storage domain IDSYS documents can choose to override specific fields. The value is inherited by the tenant and domain levels if tokenAdmin is defined in the Root IDSYS and not in the tenant or domain IDSYS. The Root IDSYS may define the LDAP adminDN and adminPassword and allows the tenant and domain IDSYS documents to override the userBase and groupBase values.

Single Company

• In this scenario, the company has one identity management system, there is one tenant per business unit, and each business unit has one or more storage domains. This scenario is likely with a private cloud serving a single company. The configuration in this scenario is the Root IDSYS defining the configuration of the identity management system and there are no IDSYS definitions for the tenants and storage domains. Therefore, the tenants and storage domains inherit from the Root IDSYS using a single source of users and groups.

Service Provider/Distributed Company

• In this scenario, a storage MSP, or a large company with business units each with separate identity management systems and multiple user/group sources. The configuration in this scenario is the Root IDSYS defining the cluster administrator users and groups and the Tenant IDSYS documents defining the users and groups for each client or business unit. The storage domains do not define an IDSYS so they inherit the definition from the tenant and share the users and groups with the other storage domains owned by the tenant.

Service Provider with Resellers

• This is an extension of the previous scenario except each tenant can be a reseller offering storage domains to separate, unrelated companies. In this case, each storage domain defined an IDSYS that overrides the Tenant IDSYS allowing a different set of users and groups for each storage domain. This scenario is not mutually exclusive with the previous one: a hybrid of the two is possible where some domains override the IDSYS of the tenant, and others do not.

Qualifying User and Group Names

It may be required to fully qualify the user and group principal names to verify correct policy resolution. In access control policies and x-owner-meta headers, a "fully qualified" principal has a tenant name or storage domain appended directly to the name:

The name in the policies may remain unqualified (no @domain or +tenant suffix on principal names) if a principal (user/group) authenticates from the same IDSYS as the resource they are accessing. 

Gateway uses the default assignment of the x-owner-meta header value to fully qualify the principal (such as user@domain or user+tenant) if a principal authenticates from a different IDSYS from the one used by the resource. Applications can also assign object ownership across domains, where the IDSYS of the storage domain differs from the user from another domain. There is no limit on the number of cross-domain relationships that exist, but all must be within the same Swarm cluster.

Tokens: Tokens are bound to the IDSYS of the context both where and when they are created. The token has to take the root scope if creating a tenant-level token but the tenant does not have an IDSYS. All requests using this token authenticate using the root IDSYS (and likely fail, not finding the user there), even if a correct tenant-level IDSYS is added later. The token must ignore any domain-level IDSYS, current or future if creating a tenant-level token with a tenant IDSYS. Either create a tenant-level IDSYS and use inherit at the domain-level or create tokens at the domain-level if domain-level controls over tokens is desired.