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 and unregister-user messages manage tag to user mappings (registered-user objects):

 1<uid-message>
 2  <type>update</type>
 3  <payload>
 4    <register-user>
 5      <entry user="user1">
 6        <tag>
 7          <member>tag01</member>
 8          <member timeout="0">tag02</member>
 9          <member timeout="3600">tag03</member>
10        </tag>
11      </entry>
12      <entry user="domain\user2">
13        <tag>
14          <member>tag01</member>
15        </tag>
16      </entry>
17    </register-user>
18  </payload>
19</uid-message>

 1<uid-message>
 2  <type>update</type>
 3  <payload>
 4    <unregister-user>
 5      <entry user="user1">
 6        <tag>
 7          <member>tag01</member>
 8        </tag>
 9      </entry>
10    </unregister-user>
11  </payload>
12</uid-message>

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:

  1. single quote

  2. double quote

  3. 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 can be combined in a single XML document:

 1<uid-message>
 2  <type>update</type>
 3  <payload>
 4    <unregister-user>
 5      <entry user="user1">
 6        <tag>
 7          <member>tag02</member>
 8          <member>tag03</member>
 9        </tag>
10      </entry>
11    </unregister-user>
12    <register-user>
13      <entry user="domain\user2">
14        <tag>
15          <member>tag02</member>
16        </tag>
17      </entry>
18      <entry user="user3">
19        <tag>
20          <member>tag01</member>
21          <member>tag02</member>
22        </tag>
23      </entry>
24    </register-user>
25  </payload>
26</uid-message>

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 message removes all user tag mappings. This is equivalent to the CLI command debug object registered-user clear all.

 1<uid-message>
 2  <type>update</type>
 3  <payload>
 4    <clear>
 5      <registered-user>
 6        <all/>
 7      </registered-user>
 8    </clear>
 9  </payload>
10</uid-message>

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

  1. Clear all registered-user mappings using the CLI.

  2. Use panxapi.py to perform a register-user request.

  3. Verify registered-user mappings using the CLI.

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

  5. Verify mappings using panxapi.py -o.

  6. View dynamic user group members for group dug1 using the CLI.

  7. View userid logs using the CLI.

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

  9. Verify registered-user mappings using the CLI.

  10. 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.

Solution

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