SCIM

System for Cross-domain Identity Management is protocol for automating the exchange of user information between identity domains and IT systems. In addition to user data, it can also be used to import host data to PrivX. For cloud provider hosts, existing PrivX cloud provider specific directory types are sufficient, but for on-prem hosts, using SCIM to import the data would be one option.

To configure SCIM endpoint to PrivX:

  1. Create a new role for SCIM access. The role should have "sources-data-push" permission. Role's contextual restrictions can be used to limit the access to the SCIM endpoint.

2476

  1. Create a new API client in Administration/Deployment and attach the previously created role to your API client. API client's credentials will be used for OAuth authentication.

2380

  1. Create a new SCIM directory. Select "API Client" authentication type to use OAuth2.
    To automatically create missing roles for hosts imported via SCIM connector, enable Create roles; disable to manage roles manually.
    Automatically created roles will include 1:1 mapping rule between role's name and user's group name. Roles created by SCIM but not currenly used by any host will be periodically deleted (see the SCIM role cleanup interval in Administration→Settings→Role Store).

2394

You may optionally specify filters and only matching users from the imported ones will be made available for use.

2564

  1. After saving the SCIM directory, you can see the SCIM API endpoint and OAuth token endpoint in PrivX UI. Use them to configure your SCIM client.

2402

  1. After configuring the SCIM client, you should create the attribute mapping for your SCIM client for the following attributes:

User object (urn:ietf:params:scim:schemas:core:2.0:User)

AttributeTypeDescriptionExample
userNamestring (REQUIRED)User principal. Usually the same as unix_username.johndoe
externalIdstring (OPTIONAL)IDM identifier (_id) for the user object. If defined, needs to be unique within the SCIM directory. If externalId is not defined, userName is used as unique identifier instead.
Needs to match OIDC 'sub' field after successful OIDC login.		5c6598fe-608f-4121-b023-6bd1d293270e
displayNamestring (OPTIONAL)User’s full name. Used in connection logs and PrivX UI.John Doe
mailstring (OPTIONAL)User's email addressjohn@doe.com
titlestring (OPTIONAL)Comma separated list of user's group memberships. Equivalent to AD's memberOf -attribute.
Used, if groups -attribute has no values.developers,db-admin,adminrole1
groupsarray of strings (OPTIONAL)MultiValued string array of user's group memberships. Equivalent to AD's memberOf -attribute.
Used by default.["developers","db-admin","adminrole1"]

Host object (custom object type, urn:ietf:params:scim:schemas:ssh:2.0:Host)

AttributeTypeDescriptionExample
externalIdstring (REQUIRED)IDM identifier (_id) for the host object. Needs to be unique within the SCIM directory.ff558e65-cc83-5edb-6de7-c8cf6e2c8098
commonNamestring (REQUIRED)Name for the host. Shown to user in host listings.Web server dev-1
contactAddressstring (REQUIRED)Host connection address. Domain name or IP address.targethost.test.internal
descriptionstring (OPTIONAL)Host description, visible to PrivX administrator.This server will be obsolete in future.
userMessagestring (OPTIONAL)Host description, visible to end users.Web server, RHEL 8.
tagsstring (OPTIONAL)Comma separated host tags. Useful for auditing.env=prod,cluster=123,test tag
accessGroupIdstring (OPTIONAL)PrivX access group ID. Use empty value for default access group. See Host-Specific Management Permissions for more information.c3ce0d74-c528-480d-8d5e-598f705484a5
SSHHostPublicKeysstring (OPTIONAL)Comma separated list of known host public keys for new servers.Can be used to pre-populate new hosts with valid SSH host keys.ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBPr3ouRuMvGtOO13TvNVi/3k4JTvYQWITiChnWGgTs0ER2nOv0JMk+wkQzn1ZoMlnAkd2z8C/aHyP70x7XAedVo=
tofuboolean (OPTIONAL)Trust On First Use. If set to false, administrator needs to accept all missing and changed host keys for new SSH connections. If set to true, any user can accept it once.true
auditEnabledboolean (OPTIONAL)Enable/disable session recording for the host.true
servicesstring (OPTIONAL)Comma separated list for enabling services for the host. Syntax: : Supports SSH,RDP,WEB and VNC protocols.SSH:22,RDP:3389,VNC:5900
principalsstring (OPTIONAL)List of host’s principals. Enter role name to enable DIRECTORY logins and =, to enable shared user account logins for the role. NOTE: Use ':' for separator.
Roles which do not exist but are defined by the host will be created on PrivX automatically, if “Create roles” –checkbox is enabled in PrivX SCIM directory config.
Host cannot be automatically assigned to use system roles (privx-admin) via SCIM connector. If you need to assign admin permissions for SCIM hosts, create a new role for the purpose.		developers:root=adminrole1,adminrole2:directoryrole1:directoryrole2
organizationstring (OPTIONAL)Customer specific host organization.ACME Inc.
organizationalUnitstring (OPTIONAL)Customer specific host organizational unit.Human Resources
zonestring (OPTIONAL)Customer specific host zone.us-east-1a
hostTypestring (OPTIONAL)Customer specific host type.Linux RHEL8
classificationstring (OPTIONAL)Customer specific host classification.prod
  1. After importing the users, see that your user attributes are mapped correctly. You can also change the PrivX user field contents by specifying Attribute mapping parameters in SCIM directory configuration.
    For example, forcing SSH and RDP to use user's email as account name for Directory logins:

1956

  1. If you are importing users via SCIM and want to use them to log into PrivX, enable and configure OIDC settings for the SCIM directory.

2570

For successful logging in as SCIM user, the OIDC server userInfo endpoint (or ID token) needs to return the subject (sub) field that matches the externalId of the user imported via SCIM. If externalId is not defined, SCIM userName attribute is used instead by default.

To specify a different SCIM attribute for matching the user's subject, define an attribute mappings under Advanced directory settings. The example below maps SCIM user data mail field to external_id. Note that external_id needs to be unique within the SCIM directory.

mail=external_id

PrivX supports SCIM protocol v2 and the following SCIM operations:

  • Create

  • Read

  • Replace

  • Delete

  • Search is partially supported (eq -filter only).

  • Patch and Bulk operations are not supported yet.
    Multi-value attributes are currently supported only for user's groups. See supported attributes above.
    "Group" resource type is currently not supported.
    For user's group memberships, see "groups" and "title" attributes above. If your SCIM client does not support multi-value attributes, use "title" field instead.

Supported authentication types:

  • Basic credential authentication
  • OAuth2 authentication (grant_type=client_credentials)
  • Access token authentication

Multiple simultaneous SCIM directories are supported, which could be used for bringing in hosts from different sources.

Was this page helpful?