Example: Add members to the portal

This example takes an input text file with information about users and adds them to your portal in bulk. Define and grant the role for each user in your portal.

Enter the following required information when running the script:

• Path to the text file containing the user information, for example, /home/admin/documents/users.txt.
• Type of users you want to add to the portal, for example, built-in or enterprise. To learn more about user types, see Managing access to your portal.
• Fully-qualified domain name of the machine hosting your portal, for example, myportal.acme.com. The script accesses your portal over HTTPS on port 7443, bypassing the ArcGIS Web Adaptor. In this manner, the script does not need to handle web tier authentication if your portal is configured to use it.
• User name and password of an account that has administrative privileges to the portal. If you're adding built-in accounts, provide the credentials of any member of the portal with administrative privileges. If you're adding organization-specific accounts, use the initial administrator account created after installing Portal for ArcGIS.

Note:

Demonstrating how to make Python scripts handle web-tier authentication is beyond the scope of this example.

Registering enterprise accounts

When registering enterprise accounts, the format for each entry in the text file is as follows:

<login>|<email address>|<name>|<role>|<description>|<Idp UserName>

• login—The enterprise login to register.

  • If using Active Directory, this login is in the form of sAMAccountName@DOMAIN. The domain name must be in all capital letters.
  • If using LDAP, the login matches the value of the userNameAttribute you specified when configuring the identity store.
  • If using SAML-based enterprise logins, the login value specified matches the NameID attribute in the SAML identity provider.

• email address—The email associated with the login and matches the value in the identity store. If the user account does not have an email address, provide a false or generic value.

• name—The alias for the login used in your ArcGIS organization. Most identity stores use the user's full name as the default alias. When the user connects to the portal website, this name appears at the top of the website.

• user type—The name of the user type to which the user will be assigned. Select any available user type from the drop-down list. You can click the compatible roles and compatible add-on licenses count to find out more about what is compatible with the selected user type. For more information, see User types, roles, and privileges.

• role—This is the role the enterprise login will have in the ArcGIS organization. Valid role values are user, publisher, admin, or <custom_role_name>, where <custom_role_name> is the name of the custom role (for example, hostedservicepublisher).

  Legacy:

  In Portal for ArcGIS 10.3 and earlier versions, the accepted values for non-custom roles were org_user, org_publisher, and org_admin. At 10.3.1, these values have been deprecated and replaced with the values listed above. You can continue to use the legacy values at 10.3.1, but note that the values may not be accepted in a future release.

• description—Optionally, include text to describe the account. This value does not correspond to any attribute in the identity store. Descriptions cannot exceed 250 characters.

• Idp UserName—Optionally, specify the user name of the enterprise account in the identity provider. If this value is not provided, the value specified for the login parameter is used instead.

You're required to provide a value for the login, email address, name, and role. The description and Idp UserName are optional. For each account listed in the file, verify the values you entered for the login, email address, and name exactly match the values in your identity store. The portal will not connect to your identity store to validate these values.

The following is an example of an entry to register an Active Directory enterprise account for login jcho111, with an email address of [e-mail] and a full name of Jon Cho. The login is placed in the user role (user) and Viewer user type, and is described as a user in department b.

jcho111@DOMAIN|[e-mail]|Jon Cho|Viewer|user|department b

The following is an example of an entry to register an enterprise account from a SAML identity provider. The user's login is [e-mail], with an email address of [e-mail] and a full name of Robert Smith. The login is placed in the publisher role (publisher) and Creator user type, with an Idp UserName of [e-mail].

[e-mail]|[e-mail]|Robert Smith|Creator|publisher||[e-mail]

The following is an example of an entry to register an LDAP enterprise account for login sjames4513, with an email address of [e-mail] and a full name of Sara James. The login is placed in the user role (admin) and GIS Professional user type, and a description is provided.

sjames4513@DOMAIN|[e-mail]|Sara James|GISProfessional|admin|Department Lead and GIS Manager

The following is an example of an entry to register an enterprise account for login srajhandas, with an email address of [e-mail] and a full name of Satish Rajhandas. The login is placed in the user role (user) and Viewer user type.

srajhandas@DOMAIN|[e-mail]|Satish Rajhandas|Viewer|user

The following is an example of an entry to register an enterprise account from a SAML identity provider. The user's login is djohnson308, with an email address of [e-mail] and a full name of Daisha Johnson. The login is placed in the user role (user) and Creator user type, a description is provided, and the Idp UserName is defined as [e-mail].

djohnson308@DOMAIN|[e-mail]|Daisha Johnson|Creator|user|Account Specialist|[e-mail]

Adding built-in portal accounts

When adding built-in portal accounts, the format for each entry in the text file is as follows:

<username>|<password>|<email address>|<name>|<user type>|<role>|<description>

• username—The user name used for the built-in account. User names must be unique; no two members can have the same user name.
• password—The password assigned to the account. Users can use this password the first time they sign in to the portal, then they can change their password by editing their profile.
• email address—Provide an email address for this account. This parameter is required; therefore, you must provide a value for the email address even if it is not a valid address.
• name—The alias for the account used in your ArcGIS organization. When the user connects to the portal website, this name appears at the top of the portal website.
• user type—The name of the user type to which the user will be assigned. Select any available user type from the drop-down list. You can click the compatible roles and compatible add-on licenses count to find out more about what is compatible with the selected user type. For more information, see User types, roles, and privileges.
• role—The role the account has in the ArcGIS organization. Valid role values are user, publisher, admin, or <custom_role_name>, where <custom_role_name> is the name of the custom role (for example, hostedservicepublisher).
• description—Optionally, include text to describe the account. Descriptions cannot exceed 250 characters.

The following is an example of an entry that adds a built-in portal account with the user name pub1 for Barbara Williams and an email account of [e-mail]. It also adds pub1 to the publisher role:

pub1|changepasswordlater|[e-mail]|Barbara Williams|Creator|publisher

The following is an example of an entry that adds a built-in portal account with the user name jcho for Jon Cho and an email account of [e-mail]. It also adds jcho to the administrator role and describes it as the GIS manager:

jcho|changepasswordlater|[e-mail]|Jon Cho|GISProfessional|admin|GIS Manager

#!/usr/bin/env python
# Requires Python 2.7+

# Demonstrates how to add users to the ArcGIS Enterprise portal in bulk

# For Http calls
import urllib2, urllib, json
# For system tools
import sys, os
# For reading passwords without echoing
import getpass
# Other utilities
import Queue

# Defines the entry point into the script
def main(argv):

    print "This script adds users in bulk into a portal. \n"

    #Get parameters
    parameters = getParametersFromUser ()

    portalURL = parameters['portalURL']
    provider = parameters['provider']
    userName = parameters['userName']
    password = parameters['password']
    inUserFile = parameters['inUserFile']


    #Get user data from file
    usersData = getUserDataFromFile(inUserFile,provider)

    #Create users
    createUsers (userName,password, portalURL,provider, usersData)

    raw_input('Press ENTER to close the script.')

    return


# This function loads all the user data in the input text file into a Python Queue.
# This usersQueue can be later passed to the createUsers function
def getUserDataFromFile(inUserFile,provider):

    usersQ = Queue.Queue()
    inFileHandle = open(inUserFile, 'r')
    userCount = 0
    print '...Processing input users file at: ' + inUserFile
    entryCount = 1
    roleID = {'admin':'org_admin', 'publisher':'org_publisher', 'user':'org_user', 'viewer':'iAAAAAAAAAAAAAAA'}
    for line in inFileHandle.readlines():
        userParams = line.strip('\n').split('|')
        userParamDict = {}
        if provider=="enterprise":
            keyParams = ['username', 'email', 'fullname', 'role', 'userLicenseTypeId', 'description', 'idpUsername', 'firstname', 'lastname']
            if len(userParams) == len(keyParams):
                for i, param in enumerate(keyParams):
                    userParamDict[param] = userParams[i]
                if userParamDict['role'] in roleID.keys():
                    userParamDict['role'] = roleID[userParamDict['role']]
                else:
                    print('The value for the user role "{}" in users text file is invalid.'.format(userParamDict['role']))
                    print('Accepted values are viewer, user, publisher, or admin.')
                    raise SystemExit('Invalid user role')
                usersQ.put(userParamDict)
                userCount = userCount + 1
            else:
                print('The format for entry "{}" is invalid.\nThe format for enterprise accounts is:'.format(line.strip('\n')))
                print(' <login>|<email address>|<full name>|<role>|<user type id>|<description>|<idp username>|<first name>|<last name>')
                raise SystemExit('Invalid format')
        elif provider=="arcgis":
            keyParams = ['username', 'password', 'email', 'fullname', 'role', 'userLicenseTypeId', 'description', 'firstname', 'lastname']
            if len(userParams) == len(keyParams):
                for i, param in enumerate(keyParams):
                    userParamDict[param] = userParams[i]
                if userParamDict['role'] in roleID.keys():
                    userParamDict['role'] = roleID[userParamDict['role']]
                else:
                    print('The value for the user role "{}" in users text file is invalid.'.format(userParamDict['role']))
                    print('Accepted values are viewer, user, publisher, or admin.')
                    raise SystemExit('Invalid user role')
                usersQ.put (userParamDict)
                userCount = userCount + 1
            else:
                print('The format for entry "{}" is invalid.\nThe format for built-in accounts is:'.format(line.strip('\n')))
                print(' <account>|<password>|<email address>|<full name>|<role>|<description>|<first name>|<last name>|<level>')
                raise SystemExit('Invalid format')
        else:
            raise SystemExit( 'The value for the user type is invalid. ')
        entryCount = entryCount +1
    inFileHandle.close()
    # Create users and report results
    print '...Total members to be added: ' + str(userCount)

    return usersQ


# This function connects to the portal and adds members to it from a collection
def createUsers(username,password, portalUrl, provider,userParamsQ):

    print '...Connecting to ' + portalUrl
    token = generateToken(username,password, portalUrl)
    print '...Adding users '
    usersLeftInQueue = True
    while usersLeftInQueue:
        try:
            userDict = userParamsQ.get(False)
            userDict['f'] = 'json'
            userDict['token'] = token
            userDict['provider'] = provider
            params = urllib.urlencode(userDict)

            request = urllib2.Request(portalUrl + '/portaladmin/security/users/createUser?',params, { 'Referer' : portalUrl })

            # POST the create request
            response = urllib2.urlopen(request).read()
            responseJSON = json.loads(response)

            # Log results
            if responseJSON.has_key('error'):
                errDict = responseJSON['error']
                if int(errDict['code'])==498:
                    message = 'Token Expired. Getting new token... Username: ' + userDict['username'] + ' will be added later'
                    token = generateToken(username,password, portalUrl)
                    userParamsQ.put(userDict)
                else:
                    message =  'Error Code: %s \n Message: %s' % (errDict['code'], errDict['message'])
                print '\n' + message
            else:
                # Success
                if responseJSON.has_key('status'):
                    resultStatus = responseJSON['status']
                    print 'User: %s account created' % (userDict['username'])
        except Queue.Empty:
              usersLeftInQueue = False

# This function gets a token from the portal
def generateToken(username, password, portalUrl):
    parameters = urllib.urlencode({'username' : username,
                                   'password' : password,
                                   'client' : 'referer',
                                   'referer': portalUrl,
                                   'expiration': 60,
                                   'f' : 'json'})
    try:
        response = urllib.urlopen(portalUrl + '/sharing/rest/generateToken?',
                              parameters).read()
    except Exception as e:
        raise SystemExit( 'Unable to open the url %s/sharing/rest/generateToken' % (portalUrl))
    responseJSON =  json.loads(response.strip(' \t\n\r'))
    # Log results
    if responseJSON.has_key('error'):
        errDict = responseJSON['error']
        if int(errDict['code'])==498:
            message = 'Token Expired. Getting new token... '
            token = generateToken(username,password, portalUrl)
        else:
            message =  'Error Code: %s \n Message: %s' % (errDict['code'],
            errDict['message'])
            raise SystemExit(message)
    token = responseJSON.get('token')
    return token

# This function gets gets parameters from the user in interactive mode
def getParametersFromUser():

    parameters = {}
    # Get Location of users file
    inUserFile = raw_input ("Enter path to users text file: ")
    if not os.path.exists(inUserFile):
        raise SystemExit( 'Input file: %s does not exist' % (inUserFile))
    parameters['inUserFile'] = inUserFile

    # Enteprise logins or built-in accounts?
    userInput = raw_input ("What type of users do you want to add to the portal?  Accepted values are built-in or enterprise: ")
    if userInput.lower()=="built-in":
        parameters['provider'] = 'arcgis'
        print '   Built-in accounts will be added to the portal. \n'
    elif userInput.lower()=="enterprise":
        parameters['provider'] = 'enterprise'
        print '   Enterprise accounts will be added to the portal. \n'
    else:
        raise SystemExit( 'The value entered for the user type %s is invalid.  Accepted values are built-in or enterprise. ' % (userInput))

    # Get Portal URL
    hostname = raw_input("Enter the fully qualified portal hostname (for example myportal.acme.com): ")
    parameters['portalURL'] = 'https://' + hostname + ':7443/arcgis'
    print '   Users will be added to portal at: ' + parameters['portalURL'] + '\n'

    # Get a username and password with portal administrative privileges
    parameters['userName'] = raw_input("Enter a built-in user name with portal administrative privileges: ")

    parameters['password'] = getpass.getpass("Enter password: ")
    print '\n'

    return  parameters

# Script start
if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))