Administration Tool User's Guide

Current version of Triplesec is bundled with a technology preview of Triplesec Administration Tool (or AdminTool shortly). This guide serves as a step by step tutorial to explain and show you

• basic concepts of Application Policy Management within the context of the AdminTool,
• how to start the AdminTool and connect to Triplesec Server,
• how to use Groups for Administrative Authority Management and
• how to use the AdminTool for Application Policy Management.

Introduction and Basic Concepts

The AdminTool can be used to manage the following entities within your Realm:

Users
  Applications
  Permissions
  Roles
  Profiles
and
  Groups
Users, Applications (Application Policies), Permissions, Roles and Profiles are essential elements of an Application Policy Management system, so you are expected to be somewhat familiar with them. For an overview of these entities and the relationships among them refer to Guardian API User's Guide. Triplesec and the AdminTool specific extentions to the concept of Application Policy Management will be mentioned as needed in this guide.

"Groups" entities are used to manage administrative authorization in Triplesec Server. Working with Groups affects most of other operations that can be performed via the AdminTool. Administrative Authority Management may be considered as the most important and advanced topic among others. It is going to be introduced under its own title, #Using Groups for Administrative Authority Management, but we will also continue to explore it in various latter sections for its association to several Application Policy Management tasks.

A Realm can be considered as an independent Application Policy Store which can live with its counterparts within the Server. Triplesec Server currently supports only one (which is really enough for most cases) Realm per server instance. So we will always be talking about this single Realm which is supposed to be configured successfully during the First Start Configuration just after the server installation. (Support for multiple Realms will be added in the next major version of Triplesec Server.) Kerberos configurations should also be done properly to be able to complete all steps in this guide successfully.

Starting the AdminTool and Connecting to Triplesec Server

After installing Triplesec Server successfully you also get the AdminTool ready installed on your system. If you have used one of the graphical installers you have options for creating shortcuts and links to launch the admin tool on all platforms. The following icon is used for the admin tool on all platforms: . The AdminTool application itself is an executable jar file. If you have not used a graphical installer or if you prefer from command line in any case, you launch the AdminTool like so:

$JAVA_HOME/bin/java -jar $TRIPLESEC_HOME/bin/triplesec-admin.jar

After launching the application you need to provide it sufficient information to connect to a Triplesec Server. The needed information can be provided to the AdminTool via three methods:

• #Triplesec Server Configuration File
• #AdminTool Connection Settings and Authentication Information Dialogs
• #AdminTool Connection Settings and Authentication Information File

Triplesec Server Configuration File

Triplesec Server configuration file which by default resides at $TRIPLESEC_HOME/conf/server.xml includes sufficient information to connect to Triplesec Server via admin credentials. Just to get started load this file via File->Load menu item and then click Connection->Connect menu item. An initial view of the AdminTool after successfully connection and authenticating will be something like so:

(Congrats! But this is the very beginning of the story..)
The admin user is the super user for the server and is not restricted in any ways. So managing the server with a principal whose rights are beyond your requirements is generally not considered to be a good idea. However, you should start with this mode in order to be able to manage administrative authorization and give users different levels of administrative privileges.

AdminTool Connection Settings and Authentication Information Dialogs

Using the AdminTool you can connect to a remote Triplesec Server and manage it as we have just done for locally installed server. Now let's first connect to our server without the Triplesec Server Configuration file but with setting connection parameters and authentication information by hand to the GUI dialogs. For this task:

AdminTool Connection Settings and Authentication Information File

You will probably not want to enter all the information for connection and authentication each time you need to use the AdminTool. The AdminTool provides you a mechanism to create a AdminTool Settings file in your home directory of your system. To do this follow the steps below.

• Start a new instance of the AdminTool.
• Click on Settings->Edit.
• You will see a frame with four tabbed panels: General, Connection, Sms, Mail.
• What matter for now are General and Connection tabs. You can enter some randon information to other tabs. (You may be prompted for some mandatory fields of those tabs.)
• Fill in the fields with appropriate information as shown in the screenshots below:

  

  

• What is new here is the passphrase in the first tab. It is required to store and later retrieve your settings in a secure way. You will be prompted for it when you want to load your settings from the AdminTool personal settings file created.
• Your file should be created at $HOME/.tsecAdminToolSettings.

Now let's use our settings file for a quicker access to the server. To do this follow the simple steps below.

• Start a new instance of the AdminTool.
• Click on Settings->Load.
• You will be prompted for a passphrase which you know what to enter.
• You will be asked for one more information about a passcode. You can safely ignore it just pressing the OK button.
• Now your settings are loaded and you can click on Connection->Connect to get into the server! As you see again the same view is in front of you as in the previous attempts.

Using Groups for Administrative Authority Management

We logged in to the server as only admin user till now and we can continue with this user till the end of the guide to perform all tasks. However as stated before this is not the desired way of doing management for Triplesec Server. So we need to define users for specific administration aspects. Groups are used for finer grained Adminitration Authority Management in Triplesec Server.

There are two types of Groups. First one is static, second one is dynamic. There are four static groups in Triplesec Server and they are: userAdmins, groupAdmins, applicationAdmins and superAdmins. Dynamic groups are created per Application (Policy) for even finer grained management for specific Applications. A User can be made a member of one or more (a combination of) of these Groups to make him/her have desired administrative capabilities.

userAdmins

userAdmins can only view/add/remove/modify Users within a Realm.

groupAdmins

groupAdmins can view/remove already added Users only within Dynamic Application Admin Groups. If you want to allow a userAdmin to add other Users to a Dynamic Application Admin Group you need to make him/her also a member of userAdmins Group.

applicationAdmins

applicationAdmins can administer all Applications within a Realm. However they can administer neither Users nor Groups. They can only view/add/remove Permissions/Roles and view/delete/modify existing Profiles. Using this Group with userAdmins make more sense because without userAdmins rights a Profile's associated User can be neither viewed nor changed.

superAdmins

superAdmins are like the admin User where their privileges are limited to the Realms they are in (so not the whole Server). superUsers do not need to be a member of previos Groups while they can do everything others can do and more.

Dynamic Application Admin Groups

When you create a new Application its Dynamic Admin Group is created automatically. Dynamic Application Admins are like applicationAdmins but they are privileges are limited with the the Application they are associated with. So can only do everything aplicationAdmin can do but only for a single Application. Also consider making a member of this Group also a member of userAdmins Group for the reasons explained before.

Connecting to the Server as a non-admin User

To be able to see how these different Groups affect the way Users administer the Server we should make at least one non-admin User capable of using the AdminTool. To do this we need to add a new Profile for a User to the AdminTool's Application Policy without any Permissions granted or denied. We have not yet seen how to do this but this is a simple task so let's do it now before we go on:

• Be sure you are connected to the Server via AdminTool as the admin user.
• Expand SAFEHAUS.ORG->Applications->tsecAdminTool->Profiles. (The name of the Realm may be different depending on your configuration.)
• Add a new Profile for User mcurie as shown below.
• If you have any problems with this step refer to #View/Add/Remove Profiles within an Application Policy section.
• Leave this instance of AdminTool running. Start a new instance and click on Settings->Load and Settings->Edit to apply new parameters for connecting as mcurie User.

  The AdminTool currently does not support more the one profile stored in the local settings file. So you need to alter it for new connections or you need to enter connection and authentication information each time you connect as a different User.

• Replace the essential information, which are particularly the principal and password fields, to be able to connect and authenticate as the User mcurie. (If you have not changed mcurie's password is also 'secret'.)
• Click on Connection->Connect and you should see something like so:
• The user does not seem to able to do much! Right?

As stated before the following sections will explore more about Administrative Authority Management while making progress in Application Policy Management. We will follow a path where we will try to do all Application Policy Management task with minimum privileges possible. So although the following sections are primarily about Application Policy Management several important aspects of Administrative Authority Management will also be explained and practiced.

Using the AdminTool for Application Policy Management

Using the AdminTool you can perform the following tasks:

• #View/Add/Remove/Modify Users within a Realm
  • #View/Edit Provisioning information and HOTP Settings for a HausKeys User
  • #View/Edit External Link URL for an External User
• #View/Add/Remove Application Policies within a Realm
  • #View/Add/Remove Permissions within an Application Policy
  • #View/Add/Remove Roles within an Application Policy
    • #View/Add/Remove Permission Grants within a Role
  • #View/Add/Remove Profiles within an Application Policy
    • #View/Add/Remove Permission Grants and Denials within a Profile
    • #View/Add/Remove Roles within a Profile

View/Add/Remove/Modify Users within a Realm

For performing tasks on Users our AdminTool User should first have suffient privileges to do them. So we will make her a userAdmin. To do this follow the steps below.

• By the instance of AdminTool which you have connected as the admin User add the User mcurie to userAdmins group as shown below.
• Reconnect to the Server with the AdminTool instance which you were connected as the User mcurie.
• Now mcurie has more options for managing the Server as shown below.
  A User can exist for two purposes in a Realm:

1. A regular User for Application Policy queries (via Guardian).
2. A User (administrator) for Administrative Authority Management.

A regular User can be made an administrator at any time adding him/her to a predefined admin group.

Now we can view/add/remove/modify Users within the Realm as a userAdmin. To view/delete/modify a User select the User entity below the Users node. You can view various attributes of the User by browsing different tabs. General tab gives only read only meta information about the Entity. User Info tab has User attributes which can be set by a priviliged User (our userAdmin in this case). Dependents tab shows the dependent Profiles which are associated with the User. Notice that currently you do not see any Profiles even if there are some. Because a userAdmin is not allowed to see information other than Users' attributes. You can make any changes to the attributes and then save them by pressing the Save button at the bottom. While a userAdmin cannot see the dependents of the User Entity be careful about removing a User. (The AdminTool will warn you about this if you attempt to do so.) Otherwise some of the Entities in the store may turn into garbage data.

Adding a regular local user to the Realm is an easy task as you just need to provide a few attributes. Adding non-local users will be explained in the following sections. Too add a User select the Users node of the Realm. On the right hand of the window you will see information grid of the current Users and some field you can fill in to add a new User. To add a local User select the local User option and add a User as shown below. (For this example the password is assigned to be 'topsecret'.)

View/Edit Provisioning information and HOTP Settings for a HausKeys User

A User can be a HausKeys User, meaning he/she uses OTPs to authenticate to the Server. To create such a User just follow similar steps as in the previous section and fill in the required information specific to HausKeys Users. Details of HausKeys related tasks are not covered in this document.

View/Edit External Link URL for an External User

Triplesec Server can also authenticate External Users (like an Active Directory User). An External User's information are not hold within Triplsec Server, so you just need to enter the User's access link. An example link can be like "ldap://ad.example.com/uid=pdirac,ou=Users,dc=example,dc=com".

View/Add/Remove Application Policies within a Realm

To add a new Application only a simple step is enough. Just move on the Applications node and fill in the required fields (Application name and password) and press the Create button. If you create an Application named MyApp the final view in the AdminTool will be like so:
As you might have expected the Application has been created without any Permissions, Roles and Profiles but empty Nodes for them.

View/Add/Remove Permissions within an Application Policy

Permissions under an Application applies only to that Application. So to work with an Application's Permissions we do not need to be an administrator of all Applications. Starting with this step we will work on only our existing MyApp Application, so being a member of MyApp's Dynamic Admin Group is enough.

What we need to do now is to make mcurie or another User a member of MyAppAdminGroup (which has been automatically created for us). We can do it as the admin user. But we have had a principle to do things with the least possible privileges. Here is where groupAdmins make sense. groupAdmins can view/remove Users within existing Dynamic Application Groups. To also allow our User to add new Users to Dynamic Application Admin Groups we will also make him/her a member of userAdmins. So let's do this by defining a new User instead of using mcurie. Here are the steps:

• As a member of userAdmins create a new User with Id guAdmin (meaning Groups and Users Admin).
• As a member of superUsers or as the admin User make guAdmin a member of groupAdmins and userAdmins.

  Note that a member of superUsers and the admin User have the same level of privileges while we only have one Realm in the Server. With this step we have also mentioned the superUsers group. All operations done in this guide can be performed both as a member of superUsers or as admin User. However if we had more than one Realm then things would be different.

• Create a Profile for guAdmin with the tsecAdminTool Application as we have done before.
• Connect to the server as guAdmin.
• guAdmin will see something like shown in the screenshot below.
• As you see he can see all Dynamic Application Admin Groups and all Users within the Realm.

Why had we done this all?! We were going to add a User to MyAppAdminGroup so he/she can administer (or particularly work with Permissions for this step) with the least possible privileges. And to do this we again tried to use the same principle. (Well, should we have added the Profile as the admin User or as a member of superAdmins?.. This is left as an exercise for you.. ) Now guAdmin can add a User, for example mcurie, to the Dynamic Admin Group of MyApp Application. And that User can do Permission related operations (and also Role and some of Profile related operations) for MyApp Application.

Now let's complete the remanining steps. Follow the steps below to allow mcurie to add Permissions to MyApp Application.

• As guAdmin User add mcurie to MyAppAdminGroup.
• As a member of superUsers or as the admin User cancel mcurie's membership for any other Groups.
• Connect as mcurie and you will see something like so (also after adding a Permission named perm1):
  As you see she can only manage Entities within MyApp Application. The screenshot also shows a Permission added. Adding a Permission is probably the simplest task you can do with the AdminTool. Just give it a name and create it. Of course you may want to name you Permissions better to reflect your Application's semantics.

View/Add/Remove Roles within an Application Policy

A Role is an Application Entity and it depends on existing Permissions. So Roles can be managed by the Application Admins or any other more priviliged Users. For this step there is no need to be a member of any Group other than the Application's own Dynamic Admin Group.

To add a Role just go to the Roles node within the Application and enter the name of the new Role and click on Create button.

View/Add/Remove Permission Grants within a Role

A Role makes sense with added Permission Grants to it. Again the same level of administrative priviliges are enough to perform this task as the previos one. To add new Permission Grants to a Role, select the Role and choose Available Grants to add to Role Grants. Really simple task.

View/Add/Remove Profiles to an Application Policy

Working with Profiles may require more priviliges than the Application Admin Group if you want to view or modify the User association. While an Application Admin cannot see the Users of the Realm he/she cannot view/modify the User of the Profile. So before working with Profiles it's better to make the administrator (maybe mcurie in our case) also a member of the userAdmins Group. So adding a Profile is also a simple task: select the Profiles node within an Application and add new Profile's Id and select its associated User, then click on Create button to complete the task.

View/Add/Remove Roles within a Profile

Profiles make sense with added Roles (and Permission Grants and Denials) to it. You can add available Roles to a Profile as just adding available Permissions to a Role.

View/Add/Remove Permission Grants and Denials within a Profile

With addition of Permission Grants and Denials a Profile can be customized for finer grained access control. You can add Available Grants and Denials to a Profile as just adding Roles to it. One important point is that if you add a Permission as both a Grant and a Denial than the Denial dominates.