Page Comparison

IDSYS documents are JSON-formatted objects and IDSYS documents are JSON-formatted objects and are specific to the back-end identity management system: Active Directory, LDAP, and Linux PAM.

Common IDSYS Fields

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

¹ For details regarding token-based authentication, see Token-Based Authentication.

When a user authenticates to the Gateway using HTTP Basic authentication (that is, not token-based authentication and not S3 HMAC), the user's password is stored in the normal field for LDAP or PAM and it may be hashed in whatever formats are supported by the system. For LDAP, this field is normally userPassword; for PAM with the traditional Unix authentication mechanism, it is the second field in the /etc/shadow file.

LDAP and AD Examples

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

LDAP

{"ldap": {
	"name" : "idsys-ldap",
	"description": "LDAP identity management configuration",

	"protocol" : "ldaps",
	"ldaphost": ["ldap.example.com", "ldap-sec.example.com"],
	"ldapport": 636,

	"adminDN": "uid=YOURUSERNAME,ou=Users,dc=example,dc=com",
	"adminPassword": "YOURPASSWORD",

	"userBase": "ou=Users,dc=example,dc=com",
	"groupBase": "ou=Groups,dc=example,dc=com",

	"userFilter": "objectclass=account",
	"groupMemberUidAttr": "memberUid",

	"cookieName": "token",
	"tokenPath": "/.TOKEN/",
	"tokenAdmin": "superuser@admindomain.example.com"
} }

The block

...

beginning with "uidAttribute"

...

makes this

...

specific to Active Directory:

Active Directory

{"ldap": {
    "name": "idsys-ad",
    "description": "Active Directory example configuration",
​
    "protocol" : "ldaps",
    "ldaphost": "ad.mycompany.com",
    "ldapport": "636",
​
    "adminDN": "cn=BINDUSER,ou=Applications,dc=mycompany,dc=com",
    "adminPassword": "BINDPASSWORD",
​
    "userBase":  "ou=Users,dc=mycompany,dc=com",
    "groupBase": "ou=Groups,dc=mycompany,dc=com",
​
    "uidAttribute":"sAMAccountName",
    "userFilter":"objectclass=*",
    "groupMemberDNAttr": "member",
​
    "cookieName": "token",
    "tokenPath": "/.TOKEN/",
    "tokenAdmin" : "caringoadmin@"
  }

...

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

¹ The groupMemberUidAttr and groupMemberDNAttr parameters are mutually exclusive and you must only define one of them must be defined in IDSYS.

² The s3SecretKeyAttr parameter is only needed when using S3 Protocol Personality with a user password stored in LDAP. It is not required when using token authentication exclusively.

The adminDN and adminPassword parameters define the credentials with which the Gateway binds to the LDAP system in order 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. By default this

  will be

  is the uid attribute of a user's LDAP record.

• 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 that are specific to the PAM back-end identity management system. If you are using PAM, follow Follow this process to implement your 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

   your

   the IDSYS document: /etc/caringo/cloudscaler/idsys.json.

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

3. Update the tokenAdmin to match

   your

   the authentication user.

Modifying IDSYS

The root IDSYS configuration is stored in the idsys.json file on the Gateway server's disk so that it is always available and so that an administrator can always modify it. In other words, you can't lock yourself this prevents locking oneself out of the storage cluster. Changes to the local file take effect without the need to restart the Gateway.

For modifying a tenant or storage domain's sub-resource through the management API, see Defined ETC Documents.

For details on modifying a storage domain's sub-resource through the storage API, see SCSP Context Sub-resources.

When updating an IDSYS sub-resource through the management API or the storage API, the The entire JSON document with all fields must be provided in the update request, even if only 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. When The lowest level overrides the higher levels when IDSYS documents exist at multiple levels in the hierarchy, the lowest level overrides the higher levels. When . It inherits from a higher level when a lower level lacks an IDSYS, it inherits from a higher level.

...

For example, if only a Root IDSYS exists, all tenants and all storage domains will inherit from the Root IDSYS. In this case, there will is only be one identity management system with one set of users and groups. If, however, the tenants each defined their own IDSYS, each Each tenant and the storage domains owned by them would share their own an identity system that would be separate from the Root IDSYS if the tenants each defines an IDSYS. In this second case, the storage domains would inherit from their the Tenant IDSYS.

The IDSYS inheritance also works at the field level, meaning that tenant and storage domain IDSYS documents can choose to override specific fields. For example, if tokenAdmin is defined in the Root IDSYS and not in the tenant or domain IDSYS, its the value will be is inherited by the tenant and domain levels. Similarly, the Root IDSYS may define the LDAP adminDN and adminPassword and let the tenant and domain IDSYS documents 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

    that serves

    serving a single company. The configuration in this scenario is

    that

    the Root IDSYS

    defines

    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

    will

    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

    that has

    with business units each with

    their own

    separate identity management systems

    , has

    and multiple user/group sources. The configuration in this scenario is

    that

    the Root IDSYS

    defines

    defining the cluster administrator users and groups and the Tenant IDSYS documents

    define

    defining the users and groups for each

    customer

    client or business unit. The storage domains do not define an IDSYS so

    that

    they inherit the definition from the tenant and share the users and groups with the other storage domains owned by

    their

    the tenant.

• Service Provider with Resellers

  • This is an extension of the previous scenario except

    that

    each tenant could be a reseller offering storage domains to separate, unrelated companies. In this case, each storage domain

    would define

    defined an IDSYS that

    would override

    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

    their

    the tenant, and others do not.

Qualifying User and Group Names

You It may need be required to fully qualify your the user and group principal names to ensure correct policy resolution. In access control policies and x-owner-meta headers, a "fully qualified" principal has its a tenant name or storage domain appended directly to its 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 — Use care with tokens, because they are bound to the IDSYS of the context both where and when they were created. That is, if you create creating a tenant-level token but that tenant doesn't the tenant does not have an IDSYS, then the token has to take the root scope, meaning that all requests using this token will authenticate using the root IDSYS (and likely fail, not finding the user there), even if a correct tenant-level IDSYS is added later. And if you create creating a tenant-level token with a tenant IDSYS, the token must ignore any domain-level IDSYS, current or future. If you want to have domain-level controls over tokens, either create  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.