.. _dug_objects:

Register-user and Unregister-user - *DUG* Objects
=================================================

PAN-OS 9.1 introduced the Dynamic User Groups (DUGs) feature.  A
*Dynamic User Groups* object is created containing match criteria to
define the members in the user group using the **and** and **or**
operators to match ``registered-user`` object tags and populate the
DUG, which can be used in the source user of a security policy.

`register-user <_static/uid-register-user.xml>`_
and
`unregister-user <_static/uid-unregister-user.xml>`_
messages manage tag to user mappings (``registered-user``
objects):

.. literalinclude:: _static/uid-register-user.xml
   :language: xml
   :linenos:

.. literalinclude:: _static/uid-unregister-user.xml
   :language: xml
   :linenos:

Tags
----

 Up to 32 tags can be specified for each user.

 The maximum length of a tag is 127.

 The tag name cannot contain the following:

 #. single quote
 #. double quote
 #. greater than one consecutive space

 And cannot be the case insensitive words:

 - **and**, **or**, **not**

Persistency
-----------

 A registered-user mapping is persistent; the mappings are preserved
 across device reboots.

Timeout Attribute
-----------------

 A tag can contain an optional ``timeout`` attribute in the
 ``<member>`` element.

 The default is ``"0"`` (never expires) or a timeout value in seconds
 for the tag.  The maximum timeout is 2592000 (30 days).

`register-user and unregister-user <_static/uid-unregister-register-user.xml>`_
can be combined in a single XML document:

.. literalinclude:: _static/uid-unregister-register-user.xml
   :language: xml
   :linenos:

.. note:: When register-user and unregister-user are combined in a single
	  document, the entries are processed in the order: unregister-user,
	  register-user; only a single ``<register-user/>`` and
	  ``<unregister-user/>`` section should be specified.

A
`clear registered-user <_static/uid-clear-registered-user.xml>`_
message removes all user tag mappings.
This is equivalent to the CLI command
``debug object registered-user clear all``.

.. literalinclude:: _static/uid-clear-registered-user.xml
   :language: xml
   :linenos:

.. note:: The dynamic user group ``dug1`` exists in the
	  lab config with match criteria: ``"tag01" or "tag02"``.

	  The CLI command ``show user group list dynamic`` can
	  be used to list all dynamic user groups configured.

Example: Add Tag to User Mappings (register-user)
-------------------------------------------------
::

  $ cat uid-register-user.xml
  <uid-message>
    <type>update</type>
    <payload>
      <register-user>
        <entry user="user1">
          <tag>
            <member>tag01</member>
            <member timeout="0">tag02</member>
            <member timeout="3600">tag03</member>
          </tag>
        </entry>
        <entry user="domain\user2">
          <tag>
            <member>tag01</member>
          </tag>
        </entry>
      </register-user>
    </payload>
  </uid-message>
  
  $ panxapi.py -xU uid-register-user.xml
  dynamic-update: success
  <response status="success"><result><uid-response>
    <version>2.0</version>
    <payload>
      <register-user>
      </register-user>
    </payload>
  </uid-response>
  </result></response>
  
  admin@PA-VM> show object registered-user all
  
  Registered User                           Tags
  ----------------------------------------  -----------------
  
  domain\user2
                                           "tag01"
  
  user1
                                           "tag01"
                                           "tag02"
                                           "tag03"
  
  Total: 2 registered users
  *: received from user-id agent
  
  $ panxapi.py -Xro 'show object registered-user all'
  op: success
  <entry user="domain\user2">
  <tag>
  <member>tag01</member>
  </tag>
  </entry>
  <entry user="user1">
  <tag>
  <member>tag01</member>
  <member>tag02</member>
  <member>tag03</member>
  </tag>
  </entry>
  <count>2</count>
  
  admin@PA-VM> show user group name dug1
  
  
  source type: xmlapi
  Group type: Dynamic
  
  [1     ] user1
  [2     ] domain\user2

Lab 15
------

#. Clear all ``registered-user`` mappings using the CLI.

#. Use **panxapi.py** to perform a *register-user* request.

#. Verify ``registered-user`` mappings using the CLI.

#. Use **panxapi.py** to perform *unregister-user* and *register-user*
   requests in a single message.

#. Verify mappings using **panxapi.py** **-o**.

#. View dynamic user group members for group ``dug1`` using the CLI.

#. View *userid* logs using the CLI.

#. Use **panxapi.py** to perform a *clear* request to remove all
   user tag mappings.

#. Verify ``registered-user`` mappings using the CLI.

#. View dynamic user group members for group ``dug1`` using the CLI.

.. hint:: The links to the ``<uid-message/>`` XML documents above can be
	  retrieved using **curl** or **wget**.

.. admonition:: Solution
   :class: toggle

   ::

     admin@PA-VM> debug object registered-user clear all 

     done!

     $ panxapi.py -U uid-register-user.xml
     dynamic-update: success

     admin@PA-VM> show object registered-user all

     Registered User                           Tags
     ----------------------------------------  -----------------

     domain\user2
                                              "tag01"

     user1
                                              "tag01"
                                              "tag02"
                                              "tag03"

     Total: 2 registered users
     *: received from user-id agent

     $ panxapi.py -U uid-unregister-register-user.xml
     dynamic-update: success

     admin@PA-VM> show object registered-user all

     Registered User                           Tags
     ----------------------------------------  -----------------

     domain\user2
                                              "tag01"
                                              "tag02"

     user1
                                              "tag01"

     user3
                                              "tag01"
                                              "tag02"

     Total: 3 registered users
     *: received from user-id agent

     $ panxapi.py -Xro 'show object registered-user all'
     op: success
     <entry user="domain\user2">
     <tag>
     <member>tag01</member>
     <member>tag02</member>
     </tag>
     </entry>
     <entry user="user1">
     <tag>
     <member>tag01</member>
     </tag>
     </entry>
     <entry user="user3">
     <tag>
     <member>tag01</member>
     <member>tag02</member>
     </tag>
     </entry>
     <count>3</count>

     admin@PA-VM> show user group name dug1


     source type: xmlapi
     Group type: Dynamic

     [1     ] user1
     [2     ] domain\user2
     [3     ] user3

     admin@PA-VM> show log userid direction equal backward receive_time in last-hour
     Domain,Receive Time,Serial #,Type,Threat/Content Type,Config Version,Generate Time,Virtual System,Source IP,User,Data Source Name,Event ID,Repeat Count,timeout,beginport,endport,Data Source,Data Source Type,Sequence Number,Action Flags,DG Hierarchy Level 1,DG Hierarchy Level 2,DG Hierarchy Level 3,DG Hierarchy Level 4,Virtual System Name,Device Name,Virtual System ID,Factor Type,Factor Completion Time,Factor Number,ugflags,userbysource
     1,2020/03/04 08:49:47,015351000006388,USERID,register-tag,2305,2020/03/04 08:49:47,vsys1,0.0.0.0,user3,,0,1,0,0,0,xml-api,,605,0x0,0,0,0,0,,PA-VM,1,,1969/12/31 16:00:00,0,0x0,user3
     1,2020/03/04 08:49:47,015351000006388,USERID,register-tag,2305,2020/03/04 08:49:47,vsys1,0.0.0.0,user3,,0,1,0,0,0,xml-api,,604,0x0,0,0,0,0,,PA-VM,1,,1969/12/31 16:00:00,0,0x0,user3
     1,2020/03/04 08:49:47,015351000006388,USERID,register-tag,2305,2020/03/04 08:49:47,vsys1,0.0.0.0,domain\user2,,0,1,0,0,0,xml-api,,603,0x0,0,0,0,0,,PA-VM,1,,1969/12/31 16:00:00,0,0x0,domain\user2
     1,2020/03/04 08:49:47,015351000006388,USERID,unregister-tag,2305,2020/03/04 08:49:47,vsys1,0.0.0.0,user1,,0,1,0,0,0,xml-api,,602,0x0,0,0,0,0,,PA-VM,1,,1969/12/31 16:00:00,0,0x0,user1
     1,2020/03/04 08:49:47,015351000006388,USERID,unregister-tag,2305,2020/03/04 08:49:47,vsys1,0.0.0.0,user1,,0,1,0,0,0,xml-api,,601,0x0,0,0,0,0,,PA-VM,1,,1969/12/31 16:00:00,0,0x0,user1
     1,2020/03/04 08:49:20,015351000006388,USERID,register-tag,2305,2020/03/04 08:49:20,vsys1,0.0.0.0,domain\user2,,0,1,0,0,0,xml-api,,600,0x0,0,0,0,0,,PA-VM,1,,1969/12/31 16:00:00,0,0x0,domain\user2
     1,2020/03/04 08:49:20,015351000006388,USERID,register-tag,2305,2020/03/04 08:49:20,vsys1,0.0.0.0,user1,,0,1,3600,0,0,xml-api,,599,0x0,0,0,0,0,,PA-VM,1,,1969/12/31 16:00:00,0,0x0,user1
     1,2020/03/04 08:49:20,015351000006388,USERID,register-tag,2305,2020/03/04 08:49:20,vsys1,0.0.0.0,user1,,0,1,0,0,0,xml-api,,598,0x0,0,0,0,0,,PA-VM,1,,1969/12/31 16:00:00,0,0x0,user1
     1,2020/03/04 08:49:20,015351000006388,USERID,register-tag,2305,2020/03/04 08:49:20,vsys1,0.0.0.0,user1,,0,1,0,0,0,xml-api,,597,0x0,0,0,0,0,,PA-VM,1,,1969/12/31 16:00:00,0,0x0,user1

     $ panxapi.py -U uid-clear-registered-user.xml
     dynamic-update: success

     admin@PA-VM> show object registered-user all

     Registered User                           Tags
     ----------------------------------------  -----------------

     Total: 0 registered users
     *: received from user-id agent

     admin@PA-VM> show user group name dug1


     source type: xmlapi
     Group type: Dynamic