External Role Sample

The following section provides administrators with information on how to configure the roles policy in a way that an external role manager could be used. For simplicity, the sample code in this section either generates the values or makes the decisions inline.

There are two main parts included in this sample: configuration and code. The code also unit tests and are run as part of the OTIS unit test framework.

Configuration

The following sample configuration is a simplified configuration that shows how you can invoke an external role manager. The sample creates and configures a test role manager object in the shared !javascript. The JSSharedScope objects are evaluated at the time that the configuration is read, so the object is instantiated one time and then shared among many policy invocations. To see an alternate way of instantiating the object, see the htf:singleton and htf:instance sections of XML File Configuration Format.

                <Setting Name="Roles" Type="htf:map">
                <!-- Root most role configuration element, should be located under the OtisConfiguration element -->
                        <Setting Name="JSSharedScope" Type="htf:jscriptscope">
                                importPackage(Packages.org.bandit.otis.impl);
                                importPackage(Packages.org.bandit.otis.api);
                                importPackage(Packages.org.bandit.otis.test.junit);
                                
                                // create a global external role manager object
                                var externalRoleManager = new Packages.org.bandit.otis.test.junit.ExternalRoleManagerSample();
                                
                                // configure settings for the global role manager
                                externalRoleManager.configure(new java.net.URI("http://example.com/settings"));
                                
                        </Setting>      
                   ................................

Now that the shared object has been created, it can be used in various rules, such as Assumable Roles and Activate Roles. When computing the list of assumable roles, the following configuration and code result in four roles being returned, as shown below. The code and configuration are fairly straightforward.

Sample Assumable Roles Configuration

The following example contains only one rule. Remember that it is possible to have multiple rules, with some being additive and others subtractive. The external role manager can be combined with several other data sources to make the final role list.

                        <Setting Name="Assumable Roles" Type="htf:map">
                                <Setting Name="Role Rule 1" Type="htf:map">
                                        <Setting Name="Enabled" Type="xsd:boolean">true</Setting>
                                        <Setting Name="JSSharedScope" Type="htf:ref">/Roles/JSSharedScope</Setting>
                                        <Setting Name="TokenRule" Type="htf:jscriptexec">
                                                RESULT = externalRoleManager.getAssumableRoles(authSession, authMethod);
                                        </Setting>
                                </Setting>
                        </Setting> <!-- End Assumable Roles -->

Sample Assumable Roles Code

Read the comments for explanations of the following hardcoded sample.

        // Allowable return types are single role, array of roles, or iterable<iRole>
        public IRole []  getAssumableRoles(IAuthSession session, IAuthMethod authMethod) throws AuthSessionException
        {
                // In practice, you would examine the authentication method here
                try
                {
                        authMethod.getAuthEntityId();
                        // Build some kind of request using the authMethod.getAuthEntityId();
                        // Send request to the endpoint
                        // Parse the response
                        // Return a list of roles from the external service.
                        
                        
                        // Make a dummy list of three roles and configure some properties on them
                        // so we can detect what type of role they are and use that in later rules.
                        final CommonRole[] roles = {
                                new CommonRole("ExtR1", "Super Neat Role", "Allows access to everything and is unaudited, only for use by unethical executives", null, null),
                                new CommonRole("ExtR2", "OK Role", "Allows access to 80% of what is needed to do your job, the auditing will blame you for everything.", null, null),
                                new CommonRole("ExtR3", "Your Role", "What you really got assigned to, only alllows for menial tasks, requires two signatures for 3 sheets of toliet paper.", null, null),
                                new CommonRole("ExclusiveRole1", "Auditing Role", "May not be active with any other roles", null, null),
                        };
                        
                        return roles;
                        
                }
                catch (AuthSessionException e)
                {
                }
                return null;
        }

Sample Activate Role Configuration

                        <Setting Name="Activate Role" Type="htf:map">
                                <Setting Name="Role Rule 1" Type="htf:map">
                                        <Setting Name="Enabled" Type="xsd:boolean">true</Setting>
                                        <Setting Name="JSSharedScope" Type="htf:ref">/Roles/JSSharedScope</Setting>
                                        <Setting Name="Evaluate" Type="htf:jscriptexec">
                                                        externalRoleManager.Activation(authSession, role);
                                        </Setting>
                                </Setting>
                        </Setting> <!-- End Assumable Roles -->

Sample Activate Role Code

public void  Activation(IAuthSession session, IRole role) throws ActivationException, AuthSessionException
        {
                // This is your chance to log, audit, or allow/deny the activation of a role
                // You can use any data present on the Role, session, or user objects, as well
                // as information returned from external sources
                
                // Sample checks could include: Dynamic Separation of Duty, or 
                // Role Activation constraints, such as temporal or spacial constraints
                
                
                // The end result of your evaluation can be any action!
                // This can do anything you want: perform auditing, add or remove properties on the session, and so forth
                
                
                
                // In this simplistic sample we hard code a check for one role that can't be active with any other roles. 
                if (role.getRoleId().equals("ExclusiveRole1"))
                {
                        Iterator<IRole> active = session.getActiveRoles();

                        if (active != null && active.hasNext())
                                throw new ActivationException("Unable to Activate :" + role.getRoleId() + ", other roles already active.", 
                                        "Release all other roles before attempting to activate this role");
                }
                else if (session.isInRole("ExclusiveRole1"))
                {
                        throw new ActivationException("Unable to Activate :" + role.getRoleId() + ",  already active roles prevent exclusitivity.", 
                        "Release" +  "ExclusiveRole1" + " before attempting to activate this role");
                }