xreporter security model

Intro

Understanding why a new report doesn't show up on the site is one of the most challenging things for the novice report-designer. For various reasons xReporter's security model is quite elaborate and flexible. The bonus of that flexibility is that it covers most - if not all - of your future growth needs; the downside however is that for the simple case (and that's how we all start) the full system might be overwhelming.
Actually, since this touches upon a lot of aspects of the xReporter design, you can find all the information presented here on different other locations of the documentation. By presenting things together, focussing on the security aspects, this should serve as an additional (and visual) guide to wisely setup your security as well as to troubleshoot possible misconfigurations.

The static model

Characters in the play

The big question we want to solve 'who can run which report?' naturally offers the main entities involved:

users	Authenticated end-users of the system. They are stored in the xreporter-admin database, in the table 'users'.
reports	The available reports you've created. They are stored as separate reportXYZ.xml files in the 'reports' directory of your xreporter-project (i.e. where you ran 'xreporter seed')

The xReporter's security model offers 2 roads connecting both:

the role-connection (counter-clockwise on the schema)
the data-connection (clockwise on the schema)

Only the reports that are reachable by both roads (or active on the cross-roads if you like) will be available to the end-user.

The role-connection: which report-procedures can I run

roles

Roles are to be seen as 'types' of users. There is no single table listing them all, yet they are implied by a distinct select of the 'role' column in the 'roles' table of the 'xreporter-admin' database.
In the same table you will find the connection to the users. The relation is many-to-many: one user can have many roles, of course one role can be assigned to many users.

In corporate settings these roles mostly fit to something related to 'function' or 'level' of the employees.

This part of the design causes very little questions for most people. It however only solves one aspect: can I run a certain report-procedure (blocking them might be caused by reasons of performance on the full system). It does however NOT cover the aspect of having (view-)access to actual data-records in data-stores.

The data-connection: which records can I see

datasources

Datasources are the actual physical locations where the records are stored.
They are configured into the xReporter realm through the datasources.xml which, among other things, essentially holds the connection-parameters (url and passwords) to the database.
(see the "Data Sources" section)

authorization-codes

Authorization codes are there to control the access-rights to the datasources.
They're hooked up to the datasources resp. the users through

authorizationcodes.xml which lists all the authorization codes in the system, listing to which datasources they are the unlocking key (see also "configuring DAC's" in the "Data Sources" section).
the 'authcodes' table in the xreporter-admin database which lists the authorizationcode for each user.

One way to think about these is as a key-lockset for managing who can enter which rooms in a way that allows you to handout only one actual key to any person: The datasources are the 'rooms' that will only open for certain 'keys'. Every user only gets one key, but multiple users will be handed out (copies of) the same key.

schema-types

Finally the Schema-types are a purely technically matter in this matching and relationship story. They assure as much as possible reuse of any single report (thus leveraging the effort put into writing those).

Important to note at this stage is that the xReporter design assumes that there (can) will be more then one datasource that 'supports' the same schema, and thus allowing one single report-procedure to be ran against all of those. Think about a 'sales' schema that is supported by both the sales_US and sales_EMEA data-sources.

Catering for this approach XReporter introduces a more abstract dependency-connection between report and datasource through this notion of 'schema-types'. These are nowhere explicitely listed, but are implied in the configuration of both sides:

each reportXYZ.xml will declare it's dependency (one!) in the element:

    <required-datasource-type>president</required-datasource-type>

the datasources.xml on the other hand will describe all (many!) the supported schema-types of each datasource in the element:
```
    <supported-types>
        <type>president</type>
    </supported-types>
```

The full picture

Putting everything in one schema we can visualize like this:

xreporter security model

A dynamic role play

Finally we show how all this comes to play in a typical flow through the XReporter application.

Step1: Who are you

By authenticating one actually pins down the user, and thus directly connects up the 'roles' and the (one) authorizationcode attached to it.

xreporter security model :: step 1

Step2: Alice, which way do you want to go?

The user's authentication-code 'opens the door' to more then one datasource, the standard XReporter flow will require the end-user to pick against which datasource he/she wants to run the reports. Chosing for one, blocks the others.

xreporter security model

Intro

The static model

Characters in the play

The role-connection: which report-procedures can I run

The data-connection: which records can I see

The full picture

A dynamic role play

Step1: Who are you

Step2: Alice, which way do you want to go?

Step3: Presenting the list of available reports