You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by sm...@apache.org on 2022/07/25 21:08:36 UTC
[directory-site] 02/02: + code samples
This is an automated email from the ASF dual-hosted git repository.
smckinney pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/directory-site.git
commit e21544f1347bfaefee49e731a06a5415b33bf78d
Author: Shawn McKinney <sm...@symas.com>
AuthorDate: Mon Jul 25 16:08:02 2022 -0500
+ code samples
---
source/fortress/user-guide-advanced.md | 1 -
source/fortress/user-guide.md | 8 ++++
source/fortress/user-guide/3-configuration.md | 4 ++
.../fortress/user-guide/4-fortress-code-samples.md | 20 ++++++++
source/fortress/user-guide/4.1-create-session.md | 53 +++++++++++++++++++++
source/fortress/user-guide/4.2-check-access.md | 54 ++++++++++++++++++++++
.../fortress/user-guide/4.3-session-permissions.md | 54 ++++++++++++++++++++++
source/fortress/user-guide/4.4-activate-role.md | 53 +++++++++++++++++++++
source/fortress/user-guide/4.5-deactivate-role.md | 45 ++++++++++++++++++
source/fortress/user-guide/4.6-authorized-roles.md | 50 ++++++++++++++++++++
10 files changed, 341 insertions(+), 1 deletion(-)
diff --git a/source/fortress/user-guide-advanced.md b/source/fortress/user-guide-advanced.md
index e8fdd6a5..3b2c6887 100644
--- a/source/fortress/user-guide-advanced.md
+++ b/source/fortress/user-guide-advanced.md
@@ -9,7 +9,6 @@ Advanced topics when deploying Fortress.
## Table of contents
* [Command Line Interface](cli.html)
-* [Configuration](user-guide/3-configuration.html)
* [Exception Handling](exception-handling.html)
* [Load Testing](load-testing.html)
* [Load Utility](load-utility.html)
diff --git a/source/fortress/user-guide.md b/source/fortress/user-guide.md
index a78b3a13..ae8219f0 100644
--- a/source/fortress/user-guide.md
+++ b/source/fortress/user-guide.md
@@ -19,3 +19,11 @@ This guide is primarily for people new to Fortress.
* [2.1 - Fortress Multitenancy](user-guide/2.1-fortress-multitenancy.html)
* [2.2 - Traditional Multi-Instances architecture](user-guide/2.2-tradi-multi-instances.html)
* [2.3 - Multitenancy under the covers](user-guide/2.3-multitenancy-under-covers.html)
+* [Configuration](user-guide/3-configuration.html)
+* [Code Samples](user-guide/4-fortress-code-samples.html)
+ * [4.1 - Create Session](user-guide/4.1-create-session.html)
+ * [4.2 - Check Access](user-guide/4.2-check-access.html)
+ * [4.3 - Session Permissions](user-guide/4.3-session-permissions.html)
+ * [4.4 - Add Active Role](user-guide/4.4-activate-role.html)
+ * [4.5 - Drop Active Role](user-guide/4.5-deactivate-role.html)
+ * [4.6 - Authorized Roles](user-guide/4.6-authorized-roles.html)
diff --git a/source/fortress/user-guide/3-configuration.md b/source/fortress/user-guide/3-configuration.md
index ec87a2f1..dee9da9f 100644
--- a/source/fortress/user-guide/3-configuration.md
+++ b/source/fortress/user-guide/3-configuration.md
@@ -1,7 +1,11 @@
---
title: 3 - Fortress Configuration
+navPrev: 2.3-multitenancy-under-covers.html
+navPrevText: 2.3 - Multitenancy under the covers
navUp: ../user-guide.html
navUpText: User Guide
+navNext: 4-fortress-code-samples.html
+navNextText: 4 - Fortress Code Samples
---
# Fortress Configuration
diff --git a/source/fortress/user-guide/4-fortress-code-samples.md b/source/fortress/user-guide/4-fortress-code-samples.md
index e69de29b..40824e13 100644
--- a/source/fortress/user-guide/4-fortress-code-samples.md
+++ b/source/fortress/user-guide/4-fortress-code-samples.md
@@ -0,0 +1,20 @@
+---
+title: 4 - Fortress Code Samples
+navPrev: 3-configuration.html
+navPrevText: 3 - Fortress Configuration
+navUp: ../user-guide.html
+navUpText: User Guide
+navNext: 4.1-create-session.html
+navNextText: 4.1 - Example Creating RBAC Session
+---
+
+# 4 - Apache Fortress Code Samples
+
+## Table of content
+
+* [4.1 - Create Session](4.1-create-session.html)
+* [4.2 - Check Access](4.2-check-access.html)
+* [4.3 - Session Permissions](4.3-session-permissions.html)
+* [4.4 - Add Active Role](4.4-activate-role.html)
+* [4.5 - Drop Active Role](4.5-deactivate-role.html)
+* [4.6 - Get Authorized Roles](4.6-authorized-roles.html)
diff --git a/source/fortress/user-guide/4.1-create-session.md b/source/fortress/user-guide/4.1-create-session.md
index e69de29b..5d5e0f50 100644
--- a/source/fortress/user-guide/4.1-create-session.md
+++ b/source/fortress/user-guide/4.1-create-session.md
@@ -0,0 +1,53 @@
+---
+title: 4.1 - Create Session
+navPrev: 4-fortress-code-samples.html
+navPrevText: 4 - Fortress Code Samples
+navUp: 4-fortress-code-samples.html
+navUpText: 4 - Fortress Code Samples
+navNext: 4.2-check-access.html
+navNextText: 4.2 - Check Access
+---
+
+# 4.1 - CreateSession
+
+```java
+Session createSession(User user, boolean isTrusted) throws SecurityException
+```
+
+Perform user authentication and role activations in one method.
+This method must be called once per user prior to calling other methods within this class. The successful result is Session that contains target user's RBAC roles.
+In addition to checking user password validity it will apply configured password policy checks.
+
+Parameters:
+user - Contains User.userId, User.password (optional if isTrusted is 'true'), optional User.roles, optional User.adminRoles
+isTrusted - if true password is not required.
+Returns:
+Session object will contain authentication result code Session.errorId, RBAC role activations Session.getRoles(), Admin Role activations Session.getAdminRoles(), Password policy codes Session.warnings, Session.expirationSeconds, Session.graceLogins and more.
+Throws:
+SecurityException - in the event of data validation failure, security policy violation or DAO error.
+
+## Simple createSession
+
+```java
+@test
+public void createSessionTest(String userId, String password, int expectedRoles)
+{
+ String szLocation = ".createSession";
+ try
+ {
+ // Instantiate the AccessMgr implementation which perform runtime RBAC operations.
+ AccessMgr accessMgr = AccessMgrFactory.createInstance();
+
+ // The User entity is used to pass data into the createSession API.
+ User user = new User(userId, password);
+
+ // This API will return a Session object that contains the User's activated Roles and other info.
+ Session session = accessMgr.createSession(user, false);
+ }
+ catch (SecurityException ex)
+ {
+ LOG.error(szLocation + " userId [" + userId + "] caught SecurityException rc=" + ex.getErrorId() + ", msg=" + ex.getMessage(), ex);
+ fail(ex.getMessage());
+ }
+}
+```
diff --git a/source/fortress/user-guide/4.2-check-access.md b/source/fortress/user-guide/4.2-check-access.md
index e69de29b..7d280be7 100644
--- a/source/fortress/user-guide/4.2-check-access.md
+++ b/source/fortress/user-guide/4.2-check-access.md
@@ -0,0 +1,54 @@
+---
+title: 4.2 - Check Access
+navPrev: 4.1-create-session.html
+navPrevText: 4.1 - Create Session
+navUp: 4-fortress-code-samples.html
+navUpText: 4 - Fortress Code Samples
+navNext: 4.3-session-permissions.html
+navNextText: 4.3 - Session Permissions
+---
+
+# 4.2 - Check Access
+
+```java
+boolean checkAccess(Session session, Permission perm) throws SecurityException
+```
+
+Perform user RBAC authorization. This function returns a Boolean value meaning whether the subject of a given session is allowed
+not to perform a given operation on a given object. The function is valid if and only if the session is a valid Fortress session,
+the object is a member of the OBJS data set, and the operation is a member of the OPS data set. The session's subject has the permission
+to perform the operation on that object if and only if that permission is assigned to (at least) one of the session's active roles.
+This implementation will verify the roles or userId correspond to the subject's active roles are registered in the object's access control list.
+
+Parameters:
+perm - must contain the object, Permission.objName, and operation, Permission.opName, of permission User is trying to access.
+session - This object must be instantiated by calling createSession(org.apache.directory.fortress.core.model.User, boolean) method before passing into the method. No variables need to be set by client after returned from createSession.
+Returns:
+True if user has access, false otherwise.
+Throws:
+SecurityException - in the event of data validation failure, security policy violation or DAO error.
+
+## checkAccess
+
+```java
+@test
+public static void testCheckAccess( Session session, String objectName, String operationName )
+{
+ String szLocation = ".testCheckAccess";
+ try
+ {
+ // Instantiate the AccessMgr implementation.
+ AccessMgr accessMgr = AccessMgrFactory.createInstance();
+ Permission inPerm = new Permission( objectName, operationName );
+
+ // Using Session object returned from createSession
+ boolean result = accessMgr.checkAccess( session, inPerm );
+ assertTrue( szLocation, result );
+ }
+ catch ( SecurityException ex )
+ {
+ LOG.error( szLocation + " caught SecurityException rc=" + ex.getErrorId() + ", msg=" + ex.getMessage(), ex );
+ fail( ex.getMessage() );
+ }
+}
+```
diff --git a/source/fortress/user-guide/4.3-session-permissions.md b/source/fortress/user-guide/4.3-session-permissions.md
index e69de29b..b371bed0 100644
--- a/source/fortress/user-guide/4.3-session-permissions.md
+++ b/source/fortress/user-guide/4.3-session-permissions.md
@@ -0,0 +1,54 @@
+---
+title: 4.3 - Session Permissions
+navPrev: 4.2-check-access.html
+navPrevText: 4.2 - Check Access
+navUp: 4-fortress-code-samples.html
+navUpText: 4 - Fortress Code Samples
+navNext: 4.4-activate-role.html
+navNextText: 4.4 - Add Active Role
+---
+
+# 4.3 - Session Permissions
+
+```java
+List<Permission> sessionPermissions( Session session ) throws SecurityException
+```
+
+This function returns the permissions of the session, i.e., the permissions assigned to its authorized roles. The function is valid if and only if the session is a valid Fortress session.
+
+Parameters:
+session - This object must be instantiated by calling createSession(org.apache.directory.fortress.core.model.User, boolean) method before passing into the method. No variables need to be set by client after returned from createSession.
+Returns:
+List<Permission> containing permissions (op, obj) active for user's session.
+Throws:
+SecurityException - is thrown if runtime error occurs with system.
+
+## sessionPermissions
+
+```java
+@test
+public static void testSessionPermissions( Session session )
+{
+ String szLocation = ".testSessionPermissions";
+ try
+ {
+ // Instantiate the AccessMgr implementation.
+ AccessMgr accessMgr = AccessMgrFactory.createInstance();
+
+ // Using Session object returned from createSession
+ List<Permission> perms = accessMgr.sessionPermissions( session );
+ assertNotNull( perms );
+ for ( Permission perm : perms )
+ {
+ // A Permission consists of an object name and operation name.
+ LOG.info( szLocation + " user [" + session.getUserId() + "] permission object ["
+ + perm.getObjName() + "] operation name [" + perm.getOpName() + "]" );
+ }
+ }
+ catch ( SecurityException ex )
+ {
+ LOG.error( szLocation + " caught SecurityException rc=" + ex.getErrorId() + ", msg=" + ex.getMessage(), ex );
+ fail( ex.getMessage() );
+ }
+}
+```
diff --git a/source/fortress/user-guide/4.4-activate-role.md b/source/fortress/user-guide/4.4-activate-role.md
index e69de29b..fa990510 100644
--- a/source/fortress/user-guide/4.4-activate-role.md
+++ b/source/fortress/user-guide/4.4-activate-role.md
@@ -0,0 +1,53 @@
+---
+title: 4.4 - Add Active Role
+navPrev: 4.3-session-permissions.html
+navPrevText: 4.3 - Session Permissions
+navUp: 4-fortress-code-samples.html
+navUpText: 4 - Fortress Code Samples
+navNext: 4.5-deactivate-role.html
+navNextText: 4.5 - Drop Active Role
+---
+
+# 4.4 - Add Active Role
+
+```java
+void addActiveRole(Session session, UserRole role) throws SecurityException
+```
+
+This function adds a role as an active role of a session whose owner is a given user.
+
+The function is valid if and only if:
+ the user is a member of the USERS data set
+ the role is a member of the ROLES data set
+ the role inclusion does not violate Dynamic Separation of Duty Relationships
+ the session is a valid Fortress session
+ the user is authorized to that role
+ the session is owned by that user.
+
+Parameters:
+ session - object contains the user's returned RBAC session from the createSession method.
+ role - object contains the role name, UserRole.name, to be activated into session.
+Throws:
+ SecurityException - is thrown if user is not allowed to activate or runtime error occurs with system.
+
+## addActiveRole
+
+```java
+@test
+public static void testAddActiveRole( Session session, String roleName )
+{
+ String szLocation = ".testAddActiveRole";
+ try
+ {
+ // Instantiate the AccessMgr implementation.
+ AccessMgr accessMgr = AccessMgrFactory.createInstance();
+ UserRole userRole = new UserRole( session.getUserId(), roleName );
+ accessMgr.addActiveRole( session, userRole );
+ }
+ catch ( SecurityException ex )
+ {
+ LOG.error( szLocation + " caught SecurityException rc=" + ex.getErrorId() + ", msg=" + ex.getMessage(), ex );
+ fail( ex.getMessage() );
+ }
+}
+```
diff --git a/source/fortress/user-guide/4.5-deactivate-role.md b/source/fortress/user-guide/4.5-deactivate-role.md
index e69de29b..63754a4b 100644
--- a/source/fortress/user-guide/4.5-deactivate-role.md
+++ b/source/fortress/user-guide/4.5-deactivate-role.md
@@ -0,0 +1,45 @@
+---
+title: 4.5 - Drop Active Role
+navPrev: 4.4-activate-role.html
+navPrevText: 4.4 - Add Active Role
+navUp: 4-fortress-code-samples.html
+navUpText: 4 - Fortress Code Samples
+navNext: 4.6-authorized-roles.html
+navNextText: 4.6 - Authorized Roles
+---
+
+# 4.5 - Drop Active Role
+
+```java
+void dropActiveRole(Session session, UserRole role) throws SecurityException
+```
+
+This function deletes a role from the active role set of a session owned by a given user. The function is valid if and only if the user is a member of the USERS data set, the session object contains a valid Fortress session, the session is owned by the user, and the role is an active role of that session.
+
+Parameters:
+session - object contains the user's returned RBAC session from the createSession method.
+role - object contains the role name, UserRole.name, to be deactivated.
+Throws:
+SecurityException - is thrown if user is not allowed to deactivate or runtime error occurs with system.
+
+## dropActiveRole
+
+```java
+@test
+public static void testDropActiveRole( Session session, String roleName )
+{
+ String szLocation = ".testDropActiveRole";
+ try
+ {
+ // Instantiate the AccessMgr implementation.
+ AccessMgr accessMgr = AccessMgrFactory.createInstance();
+ UserRole userRole = new UserRole( session.getUserId(), roleName );
+ accessMgr.dropActiveRole( session, userRole );
+ }
+ catch ( SecurityException ex )
+ {
+ LOG.error( szLocation + " caught SecurityException rc=" + ex.getErrorId() + ", msg=" + ex.getMessage(), ex );
+ fail( ex.getMessage() );
+ }
+}
+```
diff --git a/source/fortress/user-guide/4.6-authorized-roles.md b/source/fortress/user-guide/4.6-authorized-roles.md
index e69de29b..41036daa 100644
--- a/source/fortress/user-guide/4.6-authorized-roles.md
+++ b/source/fortress/user-guide/4.6-authorized-roles.md
@@ -0,0 +1,50 @@
+---
+title: 4.6 - Authorized Roles
+navPrev: 4.5-deactivate-role.html
+navPrevText: 4.5 - Drop Active Role
+navUp: 4-fortress-code-samples.html
+navUpText: 4 - Fortress Code Samples
+---
+
+# 4.6 - Authorized Roles
+
+```java
+Set<String> authorizedRoles(Session session) throws SecurityException
+```
+
+This function returns the authorized roles associated with a session based on hierarchical relationships. The function is valid if and only if the session is a valid Fortress session.
+
+Parameters:
+ session - object contains the user's returned RBAC session from the createSession method.
+Returns:
+ Set<String> containing all roles active in user's session. This will contain inherited roles.
+Throws:
+ SecurityException - is thrown if session invalid or system. error.
+
+## authorizedRoles
+
+```java
+@test
+public static void testAuthorizedRoles( Session session )
+{
+ String szLocation = ".testAuthorizedRoles";
+ try
+ {
+ // Instantiate the AccessMgr implementation.
+ AccessMgr accessMgr = AccessMgrFactory.createInstance();
+
+ // Using Session object returned from createSession
+ Set<String> roles = accessMgr.authorizedRoles( session );
+ assertNotNull( roles );
+ for ( String roleName : roles )
+ {
+ LOG.info( szLocation + "user [" + session.getUserId() + "] role [" + roleName + "]" );
+ }
+ }
+ catch ( SecurityException ex )
+ {
+ LOG.error( szLocation + " caught SecurityException rc=" + ex.getErrorId() + ", msg=" + ex.getMessage(), ex );
+ fail( ex.getMessage() );
+ }
+}
+```