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.
  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.
  1. Create a new SCIM directory. Select "API Client" authentication type to use OAuth2.
    If you wish to automatically to create missing roles for hosts imported via SCIM connector, leave "Create roles" enabled. If you rather manage the roles manually, disable it.
    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 SCIM ROLE CLEANUP INTERVAL in Administration/Settings/Role Store).
  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.
  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)

Attribute

Type

Description

Example

userName

string (REQUIRED)

User principal. Usually the same as unix_username.

johndoe

externalId

string (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

displayName

string (OPTIONAL)

User’s full name. Used in connection logs and PrivX UI.

John Doe

mail

string (OPTIONAL)

User's email address

[email protected]

title

string (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

groups

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

Attribute

Type

Description

Example

externalId

string (REQUIRED)

IDM identifier (_id) for the host object. Needs to be unique within the SCIM directory.

ff558e65-cc83-5edb-6de7-c8cf6e2c8098

commonName

string (REQUIRED)

Name for the host. Shown to user in host listings.

Web server dev-1

contactAddress

string (REQUIRED)

Host connection address. Domain name or IP address.

targethost.test.internal

description

string (OPTIONAL)

Host description, visible to PrivX administrator.

This server will be obsolete in future.

userMessage

string (OPTIONAL)

Host description, visible to end users.

Web server, RHEL 8.

tags

string (OPTIONAL)

Comma separated host tags. Useful for auditing.

env=prod,cluster=123,test tag

accessGroupId

string (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

SSHHostPublicKeys

string (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=

tofu

boolean (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

auditEnabled

boolean (OPTIONAL)

Enable/disable session recording for the host.

true

services

string (OPTIONAL)

Comma separated list for enabling services for the host. Syntax: : Supports SSH,RDP,WEB and VNC protocols.

SSH:22,RDP:3389,VNC:5900

principals

string (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

organization

string (OPTIONAL)

Customer specific host organization.

ACME Inc.

organizationalUnit

string (OPTIONAL)

Customer specific host organizational unit.

Human Resources

zone

string (OPTIONAL)

Customer specific host zone.

us-east-1a

hostType

string (OPTIONAL)

Customer specific host type.

Linux RHEL8

classification

string (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:
  1. If you are importing users via SCIM and want to use them to log in to PrivX, you also need to configure OIDC settings for SCIM directory.
    Fill in your OIDC provider attributes.

For logging in as SCIM user, the OIDC server userInfo endpoint (or ID token) needs to return subject (sub) field which matches the externalId of the user imported via SCIM. If the user ID matching the sub cannot be found, the login will fail.
If externalId is not defined, SCIM userName attribute is used instead by default.
To change which SCIM attribute to use for matching the user's subject, you can define attribute mapping for it. 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.


Did this page help you?