# Templates Classes for constructing an OAA JSON payload (Custom "Application" or "IdP"). Copyright 2022 Veza Technologies Inc. Use of this source code is governed by the MIT license that can be found in the LICENSE file or at . **Global Variables** *** * **PROPERTY\_NAME\_REGEX** *** ## function `append_helper` ```python append_helper(base, addition) ``` Helper function to simplify appending. Handles multiple cases: * base is None: starts a list * addition is list: extends base with list * addition is anything else: append element to list **Args:** * `base` (List or None): base list to append to, can be None * `addition` (\*): What to append to the list **Returns:** * `list`: will always return a list *** ## function `unique_strs` ```python unique_strs(input: 'list') → list ``` Returns a list of unique strings from input list case insensitive Returns the unique list of strings from input list in a case insensitive manner. For duplicate strings with different cast (e.g. "STRING" and "string") the case of the first occurrence is returned. **Args:** * `input` (list): list of strings **Returns:** * `list`: list of unique strings *** ## class `OAATemplateException` General exception used for violations of the template schema. ### method `__init__` ```python __init__(message) ``` *** ## class `OAAPermission` Canonical permissions used by Veza Authorization Framework. Used to describe the raw data or metadata permissions granted by `CustomPermission` *** ## class `OAAIdentityType` Types of identities for permission mapping. *** ## class `Provider` Base class for CustomProvider. ### method `__init__` ```python __init__(name, custom_template) ``` *** ### method `serialize` ```python serialize() ``` *** ## class `Application` Base class for CustomApplication. ### method `__init__` ```python __init__(name, application_type, description=None) ``` *** ## class `CustomApplication` Class for modeling application authorization using the OAA Application template. CustomApplication class consists of identities, resources and permissions and produces the OAA JSON payload for the custom application template. Class uses dictionaries to track most entities that can be referenced after creation. Dictionaries keys are case insensitive of the entity identifier (name or id). This applies to `local_users`, `local_groups`, `local_roles`, `idp_identities`, `resources` and `custom_permissions`. **Args:** * `name` (str): Name of custom application * `application_type` (str): Searchable property, can be unique or shared across multiple applications * `description` (str, optional): Description for application. Defaults to None. **Attributes:** * `application_type` (str): Searchable application type * `custom_permissions` (dict\[OAAPermission]): Dictionary of class instances * `description` (str): Description for application * `identity_to_permissions` (dict): Mapping of authorizations for identities to resources * `idp_identities` (dict\[IdPIdentity]): Contains federated identities without a corresponding local account * `local_groups` (dict\[LocalGroup]): Contains application groups (collections of users) * `local_roles` (dict\[LocalRole]): Contains application roles (collections of permissions) * `local_users` (dict\[LocalUser]): Contains users local to the application and their properties * `name` (str): Name of custom application * `properties` (dict): key value pairs of property values, property keys must be defined as part of the property\_definitions * `property_definitions` (ApplicationPropertyDefinitions): Custom property names and types for the application * `resources` (dict\[CustomResource]): Contains data resources and subresources within the application ### method `__init__` ```python __init__(name: 'str', application_type: 'str', description: 'str' = None) → None ``` *** ### method `add_access` ```python add_access(identity, identity_type, permission, resource=None) ``` Legacy method for backwards compatibility. .. deprecated: ````access --- ### method `add_access_cred` ```python add_access_cred(unique_id: 'str', name: 'str') → AccessCred ```` Create an Access Credential Access creds can be used to represent alternative access methods such as API keys or application integrations. Access creds can be assigned roles and permissions similar to local users. Access credentials can exist independently for use cases such as administratively created integrations or can be assigned to a local user for use cases like personal access tokens. **Args:** * `unique_id` (str): unique identifier for access cred * `name` (str): name for access cred **Raises:** * `OAATemplateException`: Access credential with unique ID already exists **Returns:** * `AccessCred`: New access cred *** ### method `add_custom_permission` ```python add_custom_permission( name: 'str', permissions: 'List[OAAPermission]', apply_to_sub_resources: 'bool' = False, resource_types: 'List[str]' = None ) → CustomPermission ``` Create a new custom permission. Creates a new `CustomPermission` object for the application that can be used to authorize identities to the application, resources/sub-resource or as part of a role. **Args:** * `name` (str): Name of the permission * `permissions` (list\[OAAPermission]): Canonical permissions the custom permission represents * `apply_to_sub_resources` (bool, optional): If true, when permission is applied to the application or resource, identity also has permission to all children of application/resource. Defaults to False. * `resource_types` (list, optional): List of resource types as strings that the permission relates to. Defaults to empty list. **Returns:** CustomPermission *** ### method `add_idp_identity` ```python add_idp_identity(name: 'str') → IdPIdentity ``` Create an IdP principal identity. IdP users and groups can be authorized directly to applications and resources by associating custom application permissions and roles with an IdP identity's name or email. **Args:** * `name` (str): IdP unique identifier for user or group. **Returns:** IdPIdentity *** ### method `add_local_group` ```python add_local_group( name: 'str', identities: 'List[str]' = None, unique_id: 'str' = None ) → LocalGroup ``` Create a new local group. Groups can be associated to resources via permissions or roles. All users in the local group are granted the group's authorization. Local groups will be identified by `name` by default, if `unique_id` is provided it will be used as the identifier instead Local groups can be referenced after creation using `.local_groups` dictionary attribute. Dictionary is case insensitive keyed by unique\_id or name if not using unique\_id. **Args:** * `name` (str): Display name for group * `identities` (list): List of IdP identities to associate group with. * `unique_id` (str, optional): Unique identifier for group for reference by ID **Returns:** LocalGroup *** ### method `add_local_role` ```python add_local_role( name: 'str', permissions: 'List[str]' = None, unique_id: 'str' = None ) → LocalRole ``` Create a new local role. * A local role represents a collection of permissions. * Identities (local user, group, idp user) can be assigned a role to the application or resource, granting the role's permissions. * Local roles will be identified by `name` by default, if `unique_id` is provided it will be used as the identifier instead. * Local roles can be referenced after creation if needed through `.local_roles` case insensitive dictionary attribute. * When a permission that has `resource_types` is added to a role, it will only apply to resources with a matching `resource_type` **Args:** * `name` (str): Display name for role * `permissions` (list): List of Custom Permission names to include in role. `CustomPermission` must be created separately. * `unique_id` (str, optional): Unique identifier for role for reference by ID **Returns:** LocalRole *** ### method `add_local_user` ```python add_local_user( name: 'str', identities: 'List[str]' = None, groups: 'List[str]' = None, unique_id: 'str' = None ) → LocalUser ``` Create a new local user for application. Local users can be assigned to groups and associated with resources via permissions or roles. Groups and identities can be provided at creation or added later. See `Identity` and `LocalUser` class for operations. Local users will be identified by `name` by default, if `unique_id` is provided it will be used as the identifier instead. Local users can be referenced after creation using the `.local_users` dictionary attribute. Dictionary is case insensitivekeyed by unique\_id or name if not using unique\_id. Use `unique_id` when name is not guaranteed to be unique. All permission, group and role assignments will be referenced by unique\_id. **Args:** * `name` (str): Display name for user * `identities` (list): List of identities as strings (usually email) for local user. Used to map local user to discovered IdP identities. * `groups` (list\[LocalGroup]): List of group names (as string) to add user to * `unique_id` (str, optional): Unique identifier for user for reference by ID **Returns:** LocalUser *** ### method `add_resource` ```python add_resource( name: 'str', resource_type: 'str', description: 'str' = None, unique_id: 'str' = None ) → CustomResource ``` Create a new resource under the application. Resource type is used to group and filter application resources. It should be consistent for all common resources of an application. Returns new resource object. Resource is identified by `name` by default unless `unique_id` is provided. `name` must be unique if not using `unique_id`. Resources can be referenced after creation using the `.resources` dictionary attribute. Dictionary is keyed by unique\_id or name if not using unique\_id. Use `unique_id` when name is not guaranteed to be unique. **Args:** * `name` (str): Name of resources * `resource_type` (str): Type for resource * `description` (str, optional): Description of resources. Defaults to None. * `unique_id` (str, optional): Unique identifier for resource. defaults to None. **Returns:** CustomResource *** ### method `add_tag` ```python add_tag(key: 'str', value: 'str' = '') → None ``` Add a tag to the Application **Args:** * `key` (str): Key for tag, aka name. Must be present and must be letters, numbers or \_ (underscore) only. * `value` (str, optional): Value for Tag, will appear in Veza as `key:value`. Must be letters, numbers, whitespace and the special characters @,.\_- only. Defaults to "". *** ### method `app_dict` ```python app_dict() → dict ``` Return the 'applications' section of the payload as serializable dictionary. *** ### method `define_custom_permission` ```python define_custom_permission( custom_permission: 'CustomPermission' ) → CustomPermission ``` Add a custom permission to the application. .. deprecated: \`\`\` See `CustomApplication.add_custom_permission()` ```` **Args:** - `custom_permission` (CustomPermission): CustomPermission class **Raises:** - `Exception`: Duplicate Keys **Returns:** - `CustomPermission`: The defined custom Permission --- ### method `get_identity_to_permissions` ```python get_identity_to_permissions() → list ```` Collect authorizations for all identities into a single list. *** ### method `get_payload` ```python get_payload() → dict ``` Get the OAA payload. Returns the complete OAA template payload for application as serializable dictionary **Returns:** * `dict`: OAA payload as dictionary *** ### method `permissions_dict` ```python permissions_dict() → dict ``` Return the 'permissions' section of the payload as serializable dictionary. *** ### method `set_property` ```python set_property( property_name: 'str', property_value: 'any', ignore_none: 'bool' = False ) → None ``` Set a custom property value for the application. Property name must be defined for `CustomApplication` before calling set\_property. See example below and `ApplicationPropertyDefinitions.define_application_property` for more information on defining properties. **Args:** * `property_name` (str): Name of property to set value for, property names must be defined as part of the application property\_definitions * `property_value` (Any): Value for property, type should match OAAPropertyType for property definition * `ignore_none` (bool, optional): Do not set property if value is None. Defaults to False. **Raises:** * `OAATemplateException`: If property name is not defined **Example:** `app = CustomApplication("App", application_type="example")` >>> app.property\_definitions.define\_application\_property(name="my\_property", property\_type=OAAPropertyType.STRING) >>> app.set\_property("my\_property", "property value") *** ## class `CustomResource` Class for resources and sub-resources. Should be used for representing components of the application to which authorization is granted. Each resource has a name and a type. The type can be used for grouping and filtering. **Arguments:** * `name` (str): display name for resource, must be unique to parent application or resource unless using unique\_id * `resource_type` (str): type for resource * `description` (str): description for resource * `application_name` (str): name of parent application * `resource_key` (str, optional): for sub-resources the full unique identifier required for `identity_to_permissions` section. Defaults to name or unique\_id if not provided. * `property_definitions` (ApplicationPropertyDefinitions, optional): Property definitions structure for the resource * `unique_id` (str, optional): Optional unique identifier for the resource. Defaults to None. **Attributes:** * `name` (str): display name for resource, must be unique to parent application or resource * `unique_id` (str): resource's unique identifier if provided. * `resource_type` (str): type for resource * `application_name` (str): name of parent application * `resource_key` (str): for sub-resources represents the sub-resource's parent path * `sub_resources` (dict): dictionary of sub-resources keyed by name * `properties` (dict): dictionary of properties set for resource * `tags` (list\[Tag]): list of tags ### method `__init__` ```python __init__( name: 'str', resource_type: 'str', description: 'str', application_name: 'str', resource_key: 'str' = None, property_definitions: 'ApplicationPropertyDefinitions' = None, unique_id: 'str' = None ) → None ``` *** ### method `add_access` ```python add_access(identity, identity_type, permission) ``` No longer supported, access should be added through identity (local\_user, local\_group, idp) *** ### method `add_resource_connection` ```python add_resource_connection(id: 'str', node_type: 'str') → None ``` Add an external connection to the resource. Used to add a relationship to another entity discovered by Veza such as a service account or AWS IAM role. **Args:** * `id` (str): Unique identifier for connection entity * `node_type` (str): Veza type for connecting node *** ### method `add_sub_resource` ```python add_sub_resource( name: 'str', resource_type: 'str', description: 'str' = None, unique_id: 'str' = None ) → CustomResource ``` Create a new sub-resource under current resource **Args:** * `name` (str): display name for resource * `resource_type` (str): type for resource * `description` (str, optional): String description. Defaults to None. * `unique_id` (str, optional): Unique identifier for new subresource, Defaults to `name`. **Returns:** CustomResource *** ### method `add_tag` ```python add_tag(key: 'str', value: 'str' = '') → None ``` Add a new tag to resource. **Args:** * `key` (str): Key for tag, aka name. Must be present and must be letters, numbers or \_ (underscore) only. * `value` (str, optional): Value for Tag, will appear in Veza as `key:value`. Must be letters, numbers, whitespace and the special characters @,.\_- only. Defaults to "". *** ### method `set_property` ```python set_property( property_name: 'str', property_value: 'any', ignore_none: 'bool' = False ) → None ``` Set the value for a custom property on a resource or sub-resource. Property name must be defined for resource type before calling `set_property()`. See example below and `ApplicationPropertyDefinitions.define_resource_property` for more information on defining properties. **Args:** * `property_name` (str): Name of property to set value for * `property_value` (Any): Value for property, type should match OAAPropertyType for property definition * `ignore_none` (bool, optional): Do not set property if value is None. Defaults to False. **Raises:** * `OAATemplateException`: If `property_name` is not defined **Example:** `app = CustomApplication("App", application_type="example")` >>> app.property\_definitions.define\_resource\_property(resource\_type="cog", name="my\_property", property\_type=OAAPropertyType.STRING) >>> cog1 = app.add\_resource(name="cog1", resource\_type="cog") >>> cog1.set\_property("my\_property", "this value") *** ### method `to_dict` ```python to_dict() → dict ``` Return the dictionary representation of resource. *** ## class `Identity` Base class for deriving all identity types (should not be used directly). **Args:** * `name` (str): name of identity * `identity_type` (OAAIdentityType): Veza Identity Type (local\_user, local\_group, idp) * `unique_id` (str, optional): ID of entity for reference by ID **Attributes:** * `name` (str): name of identity * `identity_type` (OAAIdentityType): Veza Identity Type (local\_user, local\_group, idp) * `application_permissions` (list\[CustomPermission]): List of permissions identity has directly to custom application * `resource_permissions` (dict): Dictionary of custom permissions associated with resources and sub-resources. Key is permission, value is list of resource keys * `application_roles` (LocalRole): List of roles identity has directly to custom application * `resource_roles` (dict): Dictionary of local\_roles for resources and sub-resources. Key is roles, value is list of resource keys * `properties` (dict): Dictionary of properties for identity, allowed values will vary by identity type * `tags` (list\[Tag]): List of tags ### method `__init__` ```python __init__( name: 'str', identity_type: 'OAAIdentityType', unique_id: 'str' = None, property_definitions: 'ApplicationPropertyDefinitions' = None ) → None ``` *** ### method `add_permission` ```python add_permission( permission: 'str', resources: 'List[CustomResource]' = None, apply_to_application: 'bool' = False ) → None ``` Add a permission to an identity. Permission can apply to either the application or application resource/sub-resources **Args:** * `permissions` (\[str]): List of strings representing the permission names * `resource` (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None. * `apply_to_application` (bool): Apply permission to application when True, defaults to False *** ### method `add_role` ```python add_role( role: 'str', resources: 'List[CustomResource]' = None, apply_to_application: 'Optional[bool]' = None, assignment_properties: 'Optional[dict]' = None ) → None ``` Add a role to an identity. Role to authorize identity to either the application or application resource/sub-resource based on role's permissions. Role assignment properties can be set with the `assignment_properties` dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting. **Args:** * `role` (str): Name of role as string * `resources` (List\[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None. * `apply_to_application` (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any * `assignment_properties` (dict, optional): Custom properties for the role assignment. Defaults to no properties. *** ### method `add_tag` ```python add_tag(key: 'str', value: 'str' = '') → None ``` Add a new tag to identity. **Args:** * `key` (str): Key for tag, aka name. Must be present and must be letters, numbers or \_ (underscore) only. * `value` (str, optional): Value for Tag, will appear in Veza as `key:value`. Must be letters, numbers, whitespace and the special characters @,.\_- only. Defaults to "". *** ### method `get_identity_to_permissions` ```python get_identity_to_permissions(application_name: 'str') → dict ``` Get a JSON serializable dictionary of all the identity's permissions and roles. Formats the identity's permissions and roles for the Custom Application template payload **Returns:** * `dict`: JSON serializable dictionary of all the identity's permissions and roles *** ### method `set_property` ```python set_property( property_name: 'str', property_value: 'any', ignore_none: 'bool' = False ) → None ``` Set a custom defined property to a specific value on an identity. Property name must be defined for identity type before calling `set_property()`. See example below for `LocalUser` and `ApplicationPropertyDefinitions.define_local_user_property` for more information on defining properties. Property must be defined for the correct `Identity` type (`LocalUser` or `LocalGroup`, `IdPIdentity` does not support custom properties). **Args:** * `property_name` (str): Name of property to set value for * `property_value` (Any): Value for property, type should match `OAAPropertyType` for property definition * `ignore_none` (bool, optional): Do not set property if value is None. Defaults to False. **Raises:** * `OAATemplateException`: If property with `property_name` is not defined. **Example:** `app = CustomApplication("App", application_type="example")` >>> app.property\_definitions.define\_local\_user\_property(name="my\_property", property\_type=OAAPropertyType.STRING) >>> user1 = app.add\_local\_user(name="user1") >>> user1.set\_property("my\_property", "value for user1") *** ## class `LocalUserType` Enum for *** ## class `LocalUser` LocalUser identity, derived from Identity base class. Used to model an application user. Can be associated with an external IdP user, or represent a local account. **Args:** * `name` (str): name of identity * `identities` (list): list of strings for IdP identity association * `groups` (list\[LocalGroup]): list of group names as strings to add user too * `unique_id` (string, optional): For reference by ID **Attributes:** * `name` (str): name of identity * `id` (str): ID of entity for ID based reference * `email` (string): Users email address * `identities` (list): list of strings for IdP identity association * `groups` (list\[LocalGroup]): list of group names as strings to add user too * `identity_type` (OAAIdentityType): Veza Identity Type (local\_user) * `application_permissions` (list\[CustomPermission]): Permissions identity has directly to custom application * `resource_permissions` (dict): Dictionary of custom permissions associated with resources and sub-resources. Key is permission, value is list of resource keys * `application_roles` (list\[LocalRole]): Custom application roles assigned directly to the identity * `resource_roles` (dict): Dictionary of local\_roles for resources and sub-resources. Key is roles, value is list of resource keys * `properties` (dict): Dictionary of properties for identity, allowed values will vary by identity type * `tags` (list\[Tag]): List of tags * `is_active` (bool): Defaults to None for unset * `created_at` (str): RFC3339 time stamp for user creation * `last_login_at` (str): RFC3339 time stamp for last login * `deactivated_at` (str): RFC3339 for user deactivate time * `password_last_changed_at` (str): RFC3339 time stamp for last password change * `user_type` (LocalUserType): Set the local user account type ### method `__init__` ```python __init__( name: 'str', identities: 'List[str]' = None, groups: 'List[str]' = None, unique_id: 'str' = None, property_definitions: 'ApplicationPropertyDefinitions' = None ) → None ``` *** ### method `add_access_cred` ```python add_access_cred(access_cred: 'str') → None ``` Add access cred to user (access cred must be created separately) **Args:** * `access_cred` (str): unique identifier of access cred *** ### method `add_group` ```python add_group(group: 'str') → None ``` Add user to local group (group must be created separately). **Args:** * `group` (str): identifier of local group *** ### method `add_identities` ```python add_identities(identities: 'List[str]') → None ``` Add multiple identities to a local user from a list. **Args:** * `identities` (list\[str]): list of identities to add to user *** ### method `add_identity` ```python add_identity(identity: 'str') → None ``` Add an identity to user. Identity should match the email address or another principal identifier for an IdP user (Okta, Azure, ect). Veza will create a connection from the application local user to IdP identity. **Args:** * `identity` (str): email or identifier for IdP user *** ### method `add_permission` ```python add_permission( permission: 'str', resources: 'List[CustomResource]' = None, apply_to_application: 'bool' = False ) → None ``` Add a permission to an identity. Permission can apply to either the application or application resource/sub-resources **Args:** * `permissions` (\[str]): List of strings representing the permission names * `resource` (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None. * `apply_to_application` (bool): Apply permission to application when True, defaults to False *** ### method `add_role` ```python add_role( role: 'str', resources: 'List[CustomResource]' = None, apply_to_application: 'Optional[bool]' = None, assignment_properties: 'Optional[dict]' = None ) → None ``` Add a role to an identity. Role to authorize identity to either the application or application resource/sub-resource based on role's permissions. Role assignment properties can be set with the `assignment_properties` dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting. **Args:** * `role` (str): Name of role as string * `resources` (List\[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None. * `apply_to_application` (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any * `assignment_properties` (dict, optional): Custom properties for the role assignment. Defaults to no properties. *** ### method `add_tag` ```python add_tag(key: 'str', value: 'str' = '') → None ``` Add a new tag to identity. **Args:** * `key` (str): Key for tag, aka name. Must be present and must be letters, numbers or \_ (underscore) only. * `value` (str, optional): Value for Tag, will appear in Veza as `key:value`. Must be letters, numbers, whitespace and the special characters @,.\_- only. Defaults to "". *** ### method `get_identity_to_permissions` ```python get_identity_to_permissions(application_name: 'str') → dict ``` Get a JSON serializable dictionary of all the identity's permissions and roles. Formats the identity's permissions and roles for the Custom Application template payload **Returns:** * `dict`: JSON serializable dictionary of all the identity's permissions and roles *** ### method `set_property` ```python set_property( property_name: 'str', property_value: 'any', ignore_none: 'bool' = False ) → None ``` Set a custom defined property to a specific value on an identity. Property name must be defined for identity type before calling `set_property()`. See example below for `LocalUser` and `ApplicationPropertyDefinitions.define_local_user_property` for more information on defining properties. Property must be defined for the correct `Identity` type (`LocalUser` or `LocalGroup`, `IdPIdentity` does not support custom properties). **Args:** * `property_name` (str): Name of property to set value for * `property_value` (Any): Value for property, type should match `OAAPropertyType` for property definition * `ignore_none` (bool, optional): Do not set property if value is None. Defaults to False. **Raises:** * `OAATemplateException`: If property with `property_name` is not defined. **Example:** `app = CustomApplication("App", application_type="example")` >>> app.property\_definitions.define\_local\_user\_property(name="my\_property", property\_type=OAAPropertyType.STRING) >>> user1 = app.add\_local\_user(name="user1") >>> user1.set\_property("my\_property", "value for user1") *** ### method `to_dict` ```python to_dict() → dict ``` Output user to dictionary for payload. *** ## class `LocalGroup` LocalGroup identity. Derived from Identity base class. Used to represent groups of local users for application. **Args:** * `name` (str): name of group * `identities` (list): list of strings for IdP identity association * `unique_id` (string, optional): Unique identifier for group **Attributes:** * `name` (str): name of identity * `identities` (list): list of strings for IdP identity association * `groups` (list\[LocalGroup]): list of group names as strings that group is member of for nested groups * `identity_type` (OAAIdentityType): Veza Identity Type, local\_group * `application_permissions` (list\[CustomPermission]): permissions identity has directly to custom application * `resource_permissions` (dict): Dictionary of custom permissions associated with resources and sub-resources. Key is permission, value is list of resource keys * `application_roles` (list\[LocalRole]): list of roles identity has directly to custom application * `resource_roles` (dict): Dictionary of local\_roles for resources and sub-resources. Key is roles, value is list of resource keys * `properties` (dict): Dictionary of properties for identity, allowed values will vary by identity type * `tags` (list\[Tag]): List of tags * `created_at` (str): RFC3339 time stamp for group creation time ### method `__init__` ```python __init__( name, identities=None, unique_id: 'str' = None, property_definitions: 'ApplicationPropertyDefinitions' = None ) ``` *** ### method `add_group` ```python add_group(group: 'str') → None ``` Add a nested group to local group (group must be created separately). **Args:** * `group` (str): identifier of local group *** ### method `add_identity` ```python add_identity(identity: 'str') → None ``` Add an identity to group. The email address or another valid identifier should match that of an IdP principal (Okta, Azure, ect). Veza will create a connection from the application local group to IdP identity. **Args:** * `identity` (str): primary IdP identifier for group to associate *** ### method `add_permission` ```python add_permission( permission: 'str', resources: 'List[CustomResource]' = None, apply_to_application: 'bool' = False ) → None ``` Add a permission to an identity. Permission can apply to either the application or application resource/sub-resources **Args:** * `permissions` (\[str]): List of strings representing the permission names * `resource` (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None. * `apply_to_application` (bool): Apply permission to application when True, defaults to False *** ### method `add_role` ```python add_role( role: 'str', resources: 'List[CustomResource]' = None, apply_to_application: 'Optional[bool]' = None, assignment_properties: 'Optional[dict]' = None ) → None ``` Add a role to an identity. Role to authorize identity to either the application or application resource/sub-resource based on role's permissions. Role assignment properties can be set with the `assignment_properties` dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting. **Args:** * `role` (str): Name of role as string * `resources` (List\[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None. * `apply_to_application` (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any * `assignment_properties` (dict, optional): Custom properties for the role assignment. Defaults to no properties. *** ### method `add_tag` ```python add_tag(key: 'str', value: 'str' = '') → None ``` Add a new tag to identity. **Args:** * `key` (str): Key for tag, aka name. Must be present and must be letters, numbers or \_ (underscore) only. * `value` (str, optional): Value for Tag, will appear in Veza as `key:value`. Must be letters, numbers, whitespace and the special characters @,.\_- only. Defaults to "". *** ### method `get_identity_to_permissions` ```python get_identity_to_permissions(application_name: 'str') → dict ``` Get a JSON serializable dictionary of all the identity's permissions and roles. Formats the identity's permissions and roles for the Custom Application template payload **Returns:** * `dict`: JSON serializable dictionary of all the identity's permissions and roles *** ### method `set_property` ```python set_property( property_name: 'str', property_value: 'any', ignore_none: 'bool' = False ) → None ``` Set a custom defined property to a specific value on an identity. Property name must be defined for identity type before calling `set_property()`. See example below for `LocalUser` and `ApplicationPropertyDefinitions.define_local_user_property` for more information on defining properties. Property must be defined for the correct `Identity` type (`LocalUser` or `LocalGroup`, `IdPIdentity` does not support custom properties). **Args:** * `property_name` (str): Name of property to set value for * `property_value` (Any): Value for property, type should match `OAAPropertyType` for property definition * `ignore_none` (bool, optional): Do not set property if value is None. Defaults to False. **Raises:** * `OAATemplateException`: If property with `property_name` is not defined. **Example:** `app = CustomApplication("App", application_type="example")` >>> app.property\_definitions.define\_local\_user\_property(name="my\_property", property\_type=OAAPropertyType.STRING) >>> user1 = app.add\_local\_user(name="user1") >>> user1.set\_property("my\_property", "value for user1") *** ### method `to_dict` ```python to_dict() → dict ``` Output group to dictionary for payload. *** ## class `IdPIdentity` IdP identity derived from Identity base class. Used to associate IdP identities (users or groups) directly to resource where concept of local users/groups doesn't apply to application. **Args:** * `name` (str): Primary IdP identifier for identity (email, group name, etc) **Attributes:** * `name` (str): name of identity * `identity_type` (OAAIdentityType): Veza Identity Type, (idp) * `application_permissions` (list\[CustomPermission]): permissions identity has directly to custom application * `resource_permissions` (dict): Dictionary of custom permissions associated with resources and sub-resources. Key is permission, value is list of resource keys * `application_roles` (list\[LocalRole]): roles identity has directly to custom application * `resource_roles` (dict): Dictionary of local\_roles for resources and sub-resources. Key is roles, value is list of resource keys * `properties` (dict): Dictionary of properties for identity, allowed values will vary by identity type * `tags` (list\[Tag]): List of tags ### method `__init__` ```python __init__(name: 'str') → None ``` *** ### method `add_permission` ```python add_permission( permission: 'str', resources: 'List[CustomResource]' = None, apply_to_application: 'bool' = False ) → None ``` Add a permission to an identity. Permission can apply to either the application or application resource/sub-resources **Args:** * `permissions` (\[str]): List of strings representing the permission names * `resource` (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None. * `apply_to_application` (bool): Apply permission to application when True, defaults to False *** ### method `add_role` ```python add_role( role: 'str', resources: 'List[CustomResource]' = None, apply_to_application: 'Optional[bool]' = None, assignment_properties: 'Optional[dict]' = None ) → None ``` Add a role to an identity. Role to authorize identity to either the application or application resource/sub-resource based on role's permissions. Role assignment properties can be set with the `assignment_properties` dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting. **Args:** * `role` (str): Name of role as string * `resources` (List\[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None. * `apply_to_application` (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any * `assignment_properties` (dict, optional): Custom properties for the role assignment. Defaults to no properties. *** ### method `add_tag` ```python add_tag(key: 'str', value: 'str' = '') → None ``` Add a new tag to identity. **Args:** * `key` (str): Key for tag, aka name. Must be present and must be letters, numbers or \_ (underscore) only. * `value` (str, optional): Value for Tag, will appear in Veza as `key:value`. Must be letters, numbers, whitespace and the special characters @,.\_- only. Defaults to "". *** ### method `get_identity_to_permissions` ```python get_identity_to_permissions(application_name: 'str') → dict ``` Get a JSON serializable dictionary of all the identity's permissions and roles. Formats the identity's permissions and roles for the Custom Application template payload **Returns:** * `dict`: JSON serializable dictionary of all the identity's permissions and roles *** ### method `set_property` ```python set_property( property_name: 'str', property_value: 'any', ignore_none: 'bool' = False ) → None ``` Set custom IdP property (no functionality). IdP identities do not support custom properties since the identity is discovered through the provider (Okta, Azure, etc) *** ## class `AccessCred` Access Credential derived from Identity base class. Access Creds can be used to represent non-user based methods that grant access such as API keys or integrations. AccessCreds can be assigned roles or permissions to an application or resource. An AccessCred can stand-alone or be associated to a local user. **Args:** * `unique_id` (str): Unique identifier for access cred * `name` (str): Name for access cred, does not need to be unique **Attributes:** * `unique_id` (str): Unique identifier for access cred * `name` (str): Name for access cred, does not need to be unique * `is_active` (bool): Indicate if credential is active, defaults to True * `created_at` (str): Time access cred was created at as RFC3339 timestampe, defaults to empty * `expires_at` (str): Time access cred was created at as RFC3339 timestampe, defaults to empty * `last_used_at` (str): Time access cred was created at as RFC3339 timestampe, defaults to empty * `can_expire` (bool): Boolean to indicate if credential type can exipre, defaults to unset ### method `__init__` ```python __init__( unique_id: 'str', name: 'str', property_definitions: 'ApplicationPropertyDefinitions' = None ) → None ``` *** ### method `add_permission` ```python add_permission( permission: 'str', resources: 'List[CustomResource]' = None, apply_to_application: 'bool' = False ) → None ``` Add a permission to an identity. Permission can apply to either the application or application resource/sub-resources **Args:** * `permissions` (\[str]): List of strings representing the permission names * `resource` (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None. * `apply_to_application` (bool): Apply permission to application when True, defaults to False *** ### method `add_role` ```python add_role( role: 'str', resources: 'List[CustomResource]' = None, apply_to_application: 'Optional[bool]' = None, assignment_properties: 'Optional[dict]' = None ) → None ``` Add a role to an identity. Role to authorize identity to either the application or application resource/sub-resource based on role's permissions. Role assignment properties can be set with the `assignment_properties` dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting. **Args:** * `role` (str): Name of role as string * `resources` (List\[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None. * `apply_to_application` (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any * `assignment_properties` (dict, optional): Custom properties for the role assignment. Defaults to no properties. *** ### method `add_tag` ```python add_tag(key: 'str', value: 'str' = '') → None ``` Add a new tag to identity. **Args:** * `key` (str): Key for tag, aka name. Must be present and must be letters, numbers or \_ (underscore) only. * `value` (str, optional): Value for Tag, will appear in Veza as `key:value`. Must be letters, numbers, whitespace and the special characters @,.\_- only. Defaults to "". *** ### method `get_identity_to_permissions` ```python get_identity_to_permissions(application_name: 'str') → dict ``` Get a JSON serializable dictionary of all the identity's permissions and roles. Formats the identity's permissions and roles for the Custom Application template payload **Returns:** * `dict`: JSON serializable dictionary of all the identity's permissions and roles *** ### method `set_property` ```python set_property( property_name: 'str', property_value: 'any', ignore_none: 'bool' = False ) → None ``` Set a custom defined property to a specific value on an access credential. Property name must be defined for access credentials before calling `set_property()`. See example below and `ApplicationPropertyDefinitions.define_access_cred_property` for more information on defining properties. **Args:** * `property_name` (str): Name of property to set value for * `property_value` (Any): Value for property, type should match `OAAPropertyType` for property definition * `ignore_none` (bool, optional): Do not set property if value is None. Defaults to False. **Raises:** * `OAATemplateException`: If property with `property_name` is not defined. **Example:** `app = CustomApplication("App", application_type="example")` >>> app.property\_definitions.define\_access\_cred\_property(name="my\_property", property\_type=OAAPropertyType.STRING) >>> cred1 = app.add\_access\_cred(unique\_id="cred001", name="Cred 001") >>> cred1.set\_property("my\_property", "value for cred001") *** ### method `to_dict` ```python to_dict() → dict ``` Output Access credential dictionary for payload *** ## class `LocalRole` Represent a Custom Application Local Role. Local Roles are a collection of permissions (as `CustomPermission`). Roles can be used to associate a local user, group or IdP identity to an application, resource or sub-resource. Permissions can either be assigned at creation and/or added later. If the `CustomPermission` definition includes resource types in the `resource_types` list, the permission will only be assigned to resources/sub-resources that match that type as part of an assignment. **Args:** * `name` (str): name of local role * `permissions` (list\[CustomPermission], optional): List of custom permission names (strings) to associate with the role. Defaults to empty list. * `unique_id` (string, optional): Unique identifier for role for identification by ID **Attributes:** * `name` (str): name of local role * `unique_id` (str): Unique identifier for role for identification by ID * `permissions` (list\[CustomPermission]): list of custom permission names (strings) to associate with the role * `roles` (list\[LocalRole]): list of roles nested inside the role * `tags` (list\[Tag]): list of Tags instances ### method `__init__` ```python __init__( name: 'str', permissions: 'List[str]' = None, unique_id: 'str' = None, property_definitions: 'ApplicationPropertyDefinitions' = None ) → None ``` *** ### method `add_permissions` ```python add_permissions(permissions: 'List[str]') → None ``` Add a permission to the role. **Args:** * `permissions` (list): List of permission names (strings) to add to role *** ### method `add_role` ```python add_role(role: 'str') → None ``` Add a nested sub-role to the role (nested role must be created separately) **Args:** * `role` (str): identifier of the local role to nest inside this role *** ### method `add_tag` ```python add_tag(key: 'str', value: 'str' = '') → None ``` Add a new tag to role. **Args:** * `key` (str): Key for tag, aka name. Must be present and must be letters, numbers or \_ (underscore) only. * `value` (str, optional): Value for Tag, will appear in Veza as `key:value`. Must be letters, numbers, whitespace and the special characters @,.\_- only. Defaults to "". *** ### method `set_property` ```python set_property( property_name: 'str', property_value: 'any', ignore_none: 'bool' = False ) → None ``` Set the value for custom property on a local role. Property name must be defined for local roles before calling `set_property()`. See example below and `ApplicationPropertyDefinitions.define_local_role_property` for more information on defining properties. **Args:** * `property_name` (str): Name of property to set value for * `property_value` (Any): Value for property, type should match OAAPropertyType for property definition * `ignore_none` (bool, optional): Do not set property if value is None. Defaults to False. **Raises:** * `OAATemplateException`: If property name is not defined. **Example:** `app = CustomApplication("App", application_type="example")` >>> app.property\_definitions.define\_local\_role\_property(name="my\_property", property\_type=OAAPropertyType.STRING) >>> role1 = app.add\_local\_role(name="role1") >>> role1.set\_property(property\_name="my\_property", property\_value="role1s value") *** ### method `to_dict` ```python to_dict() → dict ``` Convert role to dictionary for inclusion in JSON payload. **Returns:** * `dict`: serializable dictionary of role *** ## class `CustomPermission` CustomPermission class for defining `CustomApplication` permissions. * Custom permissions represent the named permissions for the application in its terms (e.g. "Admin" or "PUSH") and define the Veza canonical mapping (e.g. DataRead, MetadataRead, DataWrite). * A permission can either be applied directly to an application or resource or assigned as part of a role. * Optionally, when permissions are used as part of a role, if the `resource_types` list is populated the permission will only be applied to resources who's type is in the `resource_types` list when the role is applied to a resource. **Args:** * `name` (str): Display name for permission * `permissions` (list): List of OAAPermission enums that represent the canonical permissions * `apply_to_sub_resources` (bool, optional): If true, when permission is applied to the application or resource, identity also has permission to all children of application/resource. Defaults to `False`. * `resource_types` (list, optional): List of resource types as strings that the permission relates to. Defaults to empty list. **Attributes:** * `name` (str): Display name for permission * `permissions` (list\[OAAPermission]): List of OAAPermission enums that represent the canonical permissions * `apply_to_sub_resources` (bool): If true, when permission is applied to the application or resource, identity also has permission to all children of application/resource. * `resource_types` (list): List of resource types as strings that the permission relates to. ### method `__init__` ```python __init__( name: 'str', permissions: 'List[OAAPermission]', apply_to_sub_resources: 'bool' = False, resource_types: 'list' = None ) → None ``` *** ### method `add_resource_type` ```python add_resource_type(resource_type: 'str') → None ``` Add a resource type to the resource\_types list. Extends the list of resource types permission applies to when used in role assignment. **Args:** * `resource_type` (str): The resource type string value *** ### method `to_dict` ```python to_dict() → dict ``` Returns dictionary representation for payload. *** ## class `OAAPropertyType` Supported types for custom properties on OAA entities such as application, resource, and identity. *** ## class `ApplicationPropertyDefinitions` Model for defining custom properties for application and its entities (users, groups, roles, resources). Property definitions define the names for additional entity properties and the expected type. **Args:** * `application_type` (str): type of custom application property definitions apply to **Attributes:** * `application_properties` (dict): property definitions for application * `local_user_properties` (dict): property definitions for local users * `local_group_properties` (dict): property definitions for local groups * `local_role_properties` (dict): property definitions for local roles * `resources` (dict): property definitions for resources keyed by resource type ### method `__init__` ```python __init__(application_type: 'str') → None ``` *** ### method `define_access_cred_property` ```python define_access_cred_property( name: 'str', property_type: 'OAAPropertyType' ) → None ``` Define an access cred property. **Args:** * `name` (str): name for property * `property_type` (OAAPropertyType): type for property *** ### method `define_application_property` ```python define_application_property( name: 'str', property_type: 'OAAPropertyType' ) → None ``` Define an application property. **Args:** * `name` (str): name for property * `property_type` (OAAPropertyType): type for property *** ### method `define_local_group_property` ```python define_local_group_property( name: 'str', property_type: 'OAAPropertyType' ) → None ``` Define a local group property. **Args:** * `name` (str): name for property * `property_type` (OAAPropertyType): type for property *** ### method `define_local_role_property` ```python define_local_role_property(name: 'str', property_type: 'OAAPropertyType') → None ``` Define a local role property. **Args:** * `name` (str): name for property * `property_type` (OAAPropertyType): type for property *** ### method `define_local_user_property` ```python define_local_user_property(name: 'str', property_type: 'OAAPropertyType') → None ``` Define a local user property. **Args:** * `name` (str): name for property * `property_type` (OAAPropertyType): type for property *** ### method `define_resource_property` ```python define_resource_property( resource_type: 'str', name: 'str', property_type: 'OAAPropertyType' ) → None ``` Define a property for a resource by type of resource. **Args:** * `resource_type` (str): type of resource property definition is for * `name` (str): property name * `property_type` (OAAPropertyType): type for property *** ### method `define_role_assignment_property` ```python define_role_assignment_property( name: 'str', property_type: 'OAAPropertyType' ) → None ``` *** ### method `to_dict` ```python to_dict() → dict ``` Return property definitions as dictionary ready for OAA payload *** ### method `validate_name` ```python validate_name(name: 'str') → None ``` Check property name for valid characters Raises an exception if the name string does not match required pattern. Name must start with a character and can only contain letters and \_ character. **Args:** * `name` (str): name of property to validate **Raises:** * `OAATemplateException`: Name is not a string * `OAATemplateException`: Name contains invalid characters or does not start with a letter *** ### method `validate_property_name` ```python validate_property_name( property_name: 'str', entity_type: 'str', resource_type: 'str' = None ) → bool ``` Validate that a property name has been defined for given resource type. **Args:** * `property_name` (str): name of property to validate * `entity_type` (str): type of entity custom property is for (application, local\_user, local\_group, local\_role, resource) * `resource_type` (str): (optional) type for validating resource property names, only applicable to entity\_type resource **Raises:** * `OAATemplateException`: If property name has not been previously defined for entity *** ## class `IdPEntityType` IdP entity types. *** ## class `IdPProviderType` Veza supported IdP provider types. *** ## class `CustomIdPProvider` CustomIdPProvider class for modeling Identity Providers (IdP) using OAA Custom Identity Provider Template. CustomIdPProvider class consists of IdP domain information, user, group and external associations for identities like AWS Roles. Classes uses dictionaries to track most components, dictionaries are all keyed by string of the entity name **Args:** * `name` (str): Name of IdP * `idp_type` (str): Type descriptor for IdP, can be unique or share across multiple IdP e.g. ldap, IPA * `domain` (str): IdP domain name * `description` (str, optional): Description for IdP. Defaults to None. **Attributes:** * `name` (str): Name of custom IdP * `idp_type` (str): Type for IdP * `description` (str): Description for IdP * `domain` (CustomIdPDomain): Domain model, created with domain name at init * `users` (dict\[CustomIdPUser]): Dictionary of CustomIdPUser class instances * `groups` (dict\[CustomIdPGroup]): Dictionary of CustomIdPGroup class instances * `property_definitions` (IdPPropertyDefinitions): Custom Property definitions for IdP instance ### method `__init__` ```python __init__( name: 'str', idp_type: 'str', domain: 'str', description: 'str' = None ) → None ``` *** ### method `add_app` ```python add_app(id: 'str', name: 'str') → CustomIdPApp ``` *summary* **Args:** * `id` (str): *description* * `name` (str): *description* **Raises:** **Returns:** * `CustomIdPApp`: *description* *** ### method `add_group` ```python add_group( name: 'str', full_name: 'str' = None, identity: 'str' = None ) → CustomIdPGroup ``` Add group to IdP. **Arguments:** * `name` (str): primary ID for group * `full_name` (str): optional display name for group * `identity` (str): optional unique identifier for group, if None name is used as identity *** ### method `add_user` ```python add_user( name: 'str', full_name: 'str' = None, email: 'str' = None, identity: 'str' = None ) → CustomIdPUser ``` Add user to IdP if no identity is set name will be used as identity **Arguments:** * `name` (str): primary ID for user * `full_name` (str): optional full name for display * `email` (str): optional email for user * `identity` (str): optional unique identifier for user, if None name is used as identity **Returns:** CustomIdPUser *** ### method `get_payload` ```python get_payload() → dict ``` Return formatted payload as dictionary for JSON conversion and upload *** ## class `CustomIdPDomain` Domain model for Custom IdP provider. **Args:** * `name` (str): domain name **Attributes:** * `name` (str): domain name ### method `__init__` ```python __init__( name: 'str', property_definitions: 'IdPPropertyDefinitions' = None ) → None ``` *** ### method `add_tag` ```python add_tag(key: 'str', value: 'str' = '') → None ``` Add a new tag to IdP Domain. **Args:** * `key` (str): Key for tag, aka name. Must be present and must be letters, numbers or \_ (underscore) only. * `value` (str, optional): Value for Tag, will appear in Veza as `key:value`. Must be letters, numbers, whitespace and the special characters @,.\_- only. Defaults to "". *** ### method `set_property` ```python set_property( property_name: 'str', property_value: 'any', ignore_none: 'bool' = False ) → None ``` Set custom property value for domain. Property name must be defined for domain before calling `set_property()`. See example below and `IdPPropertyDefinitions.define_domain_property` for more information. **Args:** * `property_name` (str): Name of property * `property_value` (Any): Value for property, type should match OAAPropertyType for property definition * `ignore_none` (bool, optional): Do not set property if value is None. Defaults to False. **Raises:** * `OAATemplateException`: If property with `property_name` is not defined. **Example:** `idp = CustomIdPProvider(name="Example IdP", idp_type="example", domain="example.com")` >>> idp.property\_definitions.define\_domain\_property(name="my\_property", property\_type=OAAPropertyType.STRING) >>> idp.domain.set\_property(property\_name="my\_property", property\_value="domain property value") *** ### method `to_dict` ```python to_dict() → dict ``` Output function for payload. *** ## class `CustomIdPUser` User model for CustomIdPProvider. **Args:** * `name` (str): username for identity * `email` (str): primary email for user * `full_name` (str): Display name for user * `identity` (str): unique identifier for user (may be same as username or email, or another unique ID like employee number) **Attributes:** * `name` (str): username for identity * `email` (str): primary email for user * `full_name` (str): display name for user * `identity` (str): unique identifier for user (may be same as username or email, or another unique ID like employee number) * `department` (str): department name for user * `is_active` (bool): if user is active, defaults to None * `is_guest` (bool): if user is a guest type user, defaults to None * `manager_id` (str, optional): CustomIdPUser.identity of manager, defaults to None ### method `__init__` ```python __init__( name: 'str', email: 'str' = None, full_name: 'str' = None, identity: 'str' = None, property_definitions: 'IdPPropertyDefinitions' = None ) → None ``` *** ### method `add_app_assignment` ```python add_app_assignment( id: 'str', name: 'str', app_id: 'str', assignment_properties: 'Optional[dict]' = None ) → None ``` Create App assignment for user **Args:** * `id` (str): ID of App assignment, must be unique for user * `name` (str): Name of assignment * `app_id` (str): App ID, must exist in list of Apps for IDP * `assignment_properties` (Optional\[dict], optional): Optional custom properties to set. Property names must be defined first. Defaults to None. **Raises:** * `OAATemplateException`: Duplicate assignment ID * `OAATemplateException`: Unknown assignment property name *** ### method `add_assumed_role_arns` ```python add_assumed_role_arns(arns: 'List[str]') → None ``` Add AWS Roles to list of roles user can assume by ARN. **Args:** * `arns` (list): list of role ARNs as strings that the user is allowed to assume *** ### method `add_groups` ```python add_groups(group_identities: 'List[str]') → None ``` Add user to group(s) by group name **Args:** * `group_identities` (list): list of strings for group identities to add user to *** ### method `add_tag` ```python add_tag(key: 'str', value: 'str' = '') → None ``` Add a new tag to IdP User. **Args:** * `key` (str): Key for tag, aka name. Must be present and must be letters, numbers or \_ (underscore) only. * `value` (str, optional): Value for Tag, will appear in Veza as `key:value`. Must be letters, numbers, whitespace and the special characters @,.\_- only. Defaults to "". *** ### method `set_property` ```python set_property( property_name: 'str', property_value: 'any', ignore_none: 'bool' = False ) → None ``` Set custom property value for user. Property name must be defined for users before calling `set_property()`. See example below and `IdPPropertyDefinitions.define_user_property` for more information. **Args:** * `property_name` (str): Name of property * `property_value` (Any): Value for property, type should match OAAPropertyType for property definition * `ignore_none` (bool, optional): Do not set property if value is None. Defaults to False. **Raises:** * `OAATemplateException`: If property with `property_name` is not defined. **Example:** `idp = CustomIdPProvider(name="Example IdP", idp_type="example", domain="example.com")` >>> idp.property\_definitions.define\_user\_property(name="my\_property", property\_type=OAAPropertyType.STRING) >>> user1 = idp.add\_user(name="User 1") >>> user1.set\_property("my\_property", "user1 value") *** ### method `set_source_identity` ```python set_source_identity(identity: 'str', provider_type: 'IdPProviderType') → None ``` Set an source external identity for user. * `source_identity` will connect CustomIdP user to a Veza graph IdP user. * `provider_type` limits scope for finding matching IdP identities * search all providers with `IdPProviderType.ANY`. **Args:** * `identity` (str): Unique Identity of the source identity * `provider_type` (IdPProviderType): Type for provider to match source identity from *** ### method `to_dict` ```python to_dict() → dict ``` Function to prepare user entity for payload *** ## class `CustomIdPGroup` Group model for CustomIdPProvider. **Args:** * `name` (str): name of group * `full_name` (str): optional full name for group * `identity` (str): optional identifier for group if name is not reference identifier **Parameters:** * `name` (str): name of group * `full_name` (str): optional full name for group * `identity` (str): optional identifier for group, if None name is used as identity * `is_security_group` (bool): Property for group, defaults to None (unset) ### method `__init__` ```python __init__( name: 'str', full_name: 'str' = None, identity: 'str' = None, property_definitions: 'IdPPropertyDefinitions' = None ) → None ``` *** ### method `add_app_assignment` ```python add_app_assignment( id: 'str', name: 'str', app_id: 'str', assignment_properties: 'Optional[dict]' = None ) → None ``` Create App assignment for group **Args:** * `id` (str): ID of App assignment, must be unique for group * `name` (str): Name of assignment * `app_id` (str): App ID, must exist in list of Apps for IDP * `assignment_properties` (Optional\[dict], optional): Optional custom properties to set. Property names must be defined first. Defaults to None. **Raises:** * `OAATemplateException`: Duplicate assignment ID * `OAATemplateException`: Unknown assignment property name *** ### method `add_assumed_role_arns` ```python add_assumed_role_arns(arns: 'List[str]') → None ``` Add AWS Roles to list of roles group members can assume by ARN. **Args:** * `arns` (list): list of role ARNs as strings that the group members are allowed to assume *** ### method `add_groups` ```python add_groups(group_identities: 'List[str]') → None ``` Add group to group(s) by group name Adds current group to another parent group by the group identifier **Args:** * `group_identities` (list): list of strings for group identities to add group to *** ### method `add_tag` ```python add_tag(key: 'str', value: 'str' = '') → None ``` Add a new tag to IdP Group. **Args:** * `key` (str): Key for tag, aka name. Must be present and must be letters, numbers or \_ (underscore) only. * `value` (str, optional): Value for Tag, will appear in Veza as `key:value`. Must be letters, numbers, whitespace and the special characters @,.\_- only. Defaults to "". *** ### method `set_property` ```python set_property( property_name: 'str', property_value: 'any', ignore_none: 'bool' = False ) → None ``` Set custom property value for group. Property name must be defined for groups before calling `set_property()`. See example below and `IdPPropertyDefinitions.define_group_property` for more information. **Args:** * `property_name` (str): Name of property * `property_value` (Any): Value for property, type should match OAAPropertyType for property definition * `ignore_none` (bool, optional): Do not set property if value is None. Defaults to False. **Raises:** * `OAATemplateException`: If property with `property_name` is not defined. **Example:** `idp = CustomIdPProvider(name="Example IdP", idp_type="example", domain="example.com")` >>> idp.property\_definitions.define\_group\_property(name="my\_property", property\_type=OAAPropertyType.STRING) >>> group1 = idp.add\_group(name="Group 1") >>> group1.set\_property("my\_property", "group1 value") *** ### method `to_dict` ```python to_dict() → None ``` Function to prepare user entity for payload. *** ## class `CustomIdPApp` App model for CustomIdPProvider **Args:** * `id` (str): ID for App, must be unique * `name` (str): Name for App * `property_definitions` (IdPPropertyDefinitions, optional): Custom property definitions, required to set custom properties. Defaults to None. **Attributes:** * `id` (str): ID for App, must be unique * `name` (str): Name for App * `description` (str): Description property for App ### method `__init__` ```python __init__( id: 'str', name: 'str', property_definitions: 'IdPPropertyDefinitions' = None ) → None ``` *** ### method `add_assumed_role_arns` ```python add_assumed_role_arns(arns: 'List[str]') → None ``` Add AWS Roles to list of roles App can assume by ARN. Any Users or Groups assigned to the App are represented as being able to assume the roles. **Args:** * `arns` (list): list of role ARNs as strings that the user is allowed to assume *** ### method `add_tag` ```python add_tag(key: 'str', value: 'str' = '') → None ``` Add a new tag to IdP User. **Args:** * `key` (str): Key for tag, aka name. Must be present and must be letters, numbers or \_ (underscore) only. * `value` (str, optional): Value for Tag, will appear in Veza as `key:value`. Must be letters, numbers, whitespace and the special characters @,.\_- only. Defaults to "". *** ### method `set_property` ```python set_property( property_name: 'str', property_value: 'any', ignore_none: 'bool' = False ) → None ``` Set custom property value for app. Property name must be defined for app before calling `set_property()`. See example below and `IdPPropertyDefinitions.define_app_property` for more information. **Args:** * `property_name` (str): Name of property * `property_value` (Any): Value for property, type should match OAAPropertyType for property definition * `ignore_none` (bool, optional): Do not set property if value is None. Defaults to False. **Raises:** * `OAATemplateException`: If property with `property_name` is not defined. **Example:** `idp = CustomIdPProvider(name="Example IdP", idp_type="example", domain="example.com")` >>> idp.property\_definitions.define\_app\_property(name="my\_property", property\_type=OAAPropertyType.STRING) >>> app1 = idp.add\_app(id="app1", ="App 1") >>> app1.set\_property("my\_property", "app1 value") *** ### method `to_dict` ```python to_dict() → dict ``` *** ## class `IdPPropertyDefinitions` Model for defining custom properties for CustomIdPProvider and its entities (users, groups, domain). Property definitions define the names for additional entity properties and the expected type. **Attributes:** * `domain_properties` (dict): property definitions for IdP Domain * `user_properties` (dict): property definitions for IdP users * `group_properties` (dict): property definitions for IdP groups ### method `__init__` ```python __init__() → None ``` *** ### method `define_app_assignment_property` ```python define_app_assignment_property( name: 'str', property_type: 'OAAPropertyType' ) → None ``` Define an app assignment custom property **Args:** * `name` (str): name of property * `property_type` (OAAPropertyType): type for property *** ### method `define_app_property` ```python define_app_property(name: 'str', property_type: 'OAAPropertyType') → None ``` Define an app custom property **Args:** * `name` (str): name of property * `property_type` (OAAPropertyType): type for property *** ### method `define_domain_property` ```python define_domain_property(name: 'str', property_type: 'OAAPropertyType') → None ``` Define a domain custom property. **Args:** * `name` (str): name of property * `property_type` (OAAPropertyType): type for property *** ### method `define_group_property` ```python define_group_property(name: 'str', property_type: 'OAAPropertyType') → None ``` Define a group custom property. **Args:** * `name` (str): name of property * `property_type` (OAAPropertyType): type for property *** ### method `define_user_property` ```python define_user_property(name: 'str', property_type: 'OAAPropertyType') → None ``` Define a user custom property. **Args:** * `name` (str): name of property * `property_type` (OAAPropertyType): type for property *** ### method `to_dict` ```python to_dict() → dict ``` Returns custom IdP property definitions. *** ### method `validate_property_name` ```python validate_property_name(property_name: 'str', entity_type: 'str') → None ``` Validate that a property name has been defined for a given IdP entity. Raises exception if property name has not been previously defined for entity **Args:** * `property_name` (str): name of property to validate * `entity_type` (str): type of entity custom property is for (domain, users, groups) **Raises:** * `OAATemplateException`: If property name is not defined *** ## class `Tag` Veza Tag data model. **Args:** * `key` (str): key for tag, aka name. Must be present and must be letters, numbers or \_ (underscore) only. * `value` (str, optional): Value for tag, will appear in Veza as `key:value`. Must be letters, numbers, whitespace and the special characters @,.\_- only. **Attributes:** * `key` (str): key for tag, aka name. Must be present and must be letters, numbers or \_ (underscore) only. * `value` (str): Value for tag, will appear in Veza as `key:value`. Must be letters, numbers and the special characters @,.\_ only. ### method `__init__` ```python __init__(key: 'str', value: 'str' = '') → None ``` *** ## class `HRISProvider` Class for modeling Human Resource Information Systems (HRIS) Template HRIS template consists of base information about the HRIS instance, Employees and Groups. Employees and Groups are tracked in case insensitive dictionaries that can be used to reference entities after creation. **Args:** * `name` (str): Name for HRIS Instance * `hris_type` (str): Type for HRIS. Typically the vendor or product name. * `url` (str): Instance URL for HRIS. **Attributes:** * `employees` (dict\[string]): Dictionary of HRISEmployee instances keyed by Employee ID * `groups` (dict\[string]): Dictionary of HRISGroup instances keyed by Group ID ### method `__init__` ```python __init__(name: 'str', hris_type: 'str', url: 'str') ``` *** ### method `add_employee` ```python add_employee( unique_id: 'str', name: 'str', employee_number: 'str', first_name: 'str', last_name: 'str', is_active: 'bool', employment_status: 'str' ) → HRISEmployee ``` Add a new Employee Function creates a new HRISEmployee instance and adds it to the `HRISProvider.employees` keyed by the `unique_id` **Args:** * `unique_id` (str): Unique Identifier for Employee * `name` (str): Display name for employee * `employee_number` (str): The employee's number that appears in the third-party integration. * `first_name` (str): Employee first name * `last_name` (str): Employee last name (family name) * `is_active` (bool): Boolean for employee active status * `employment_status` (str): String representation of employee status, e.g. "ACTIVE", "TERMINATE", "PENDING" **Raises:** * `OAATemplateException`: Employee with ID already exists **Returns:** * `HRISEmployee`: Entity for new employee *** ### method `add_group` ```python add_group(unique_id: 'str', name: 'str', group_type: 'str') → HRISGroup ``` Add a new Group Used to represent any subset of employees, such as PayGroup or Team. Employees can be in multiple Groups. Groups can also be members of other groups to create hierarchy. Some properties of HRISEmployee such as `department` must reference an existing HRISGroup by its ID. **Args:** * `unique_id` (str): Unique ID for group * `name` (str): Display name * `group_type` (str): Type for group such as "Team", "Department", "Cost Center" **Returns:** * `HRISGroup`: Entity for new group *** ### method `get_payload` ```python get_payload() → dict ``` Get the OAA payload. Returns the complete OAA template payload for HRIS as serializable dictionary **Returns:** * `dict`: OAA payload as dictionary *** ## class `HRISSystem` HRISSystem information Representation for HRISSystem information. The system information is used to represent additional details for the HRIS Instance. **Args:** * `name` (str): Name for system Instance * `url` (str, optional): URL for instance . Defaults to "". TODO: Is this right? ### method `__init__` ```python __init__(name: 'str', url: 'str' = '') ``` *** ### method `add_idp_type` ```python add_idp_type(provider_type: 'IdPProviderType') → list[IdPProviderType] ``` Link HRIS to External IdP of given type Sets the IdP types (Okta, AzureAD, ect) for Veza to link employee identities too. **Args:** * `provider_type` (IdPProviderType): Type of IdP for source identities **Raises:** * `ValueError`: provider\_type must be IdPProviderType enum **Returns:** * `list[IdPProviderType]`: List of configured IdP types *** ### method `to_dict` ```python to_dict() → dict ``` *** ## class `HRISEmployee` HRIS Employee Entity Represents an employee record in the HRIS system. Each employee must have a unique ID to identify it in the payload. This ID is also used to reference one employee to the other for manager hierarchy. Init variables are all required and must not be empty such as `""` **Args:** * `unique_id` (str): Unique Identifier for Employee * `name` (str): Name for employee record. * `employee_number` (str): The employee's number that appears in the third-party integration. * `first_name` (str): Employee first name * `last_name` (str): Employee last name (family name) * `is_active` (bool): Boolean for employee active status * `employment_status` (str): String representation of employee status, e.g. "ACTIVE", "TERMINATE", "PENDING" **Parameters:** * `company` (str): The company (or subsidiary) the employee works for. * `preferred_name` (str): The employee's preferred first name. * `display_full_name` (str): The employee's full name, to use for display purposes. * `canonical_name` (str): The employee's canonical name. * `username` (str): The employee's username that appears in the integration UI. * `email` (str): The employee's work email. * `idpid` (str): The ID for this employee on the destination IDP provider used to automatically connect to it, if not supplied email is used. * `personal_email` (str): The employee's personal email. * `home_location` (str): The employee's home location. * `work_location` (str): The employee's work location. * `cost_center` (str): The cost center ID (Group ID) that the employee is in. * `department` (str): The department ID (Group ID) that the employee is in. * `managers` (str): The employee IDs of the employee's managers. * `groups` (str): The IDs of groups this user is in * `start_date` (str): The date that the employee started working. RFC3339 timestamp. * `termination_date` (str): The employee's termination date. RFC3339 timestamp. * `job_title` (str): The title of the employee. * `employment_typ` (str): The employee's type of employment. For example: FULL\_TIME, PART\_TIME, INTERN, CONTRACTOR, FREELANCE. * `primary_time_zone` (str): The time zone which the employee primarily lives. **Raises:** * `ValueError`: Any of the required arguments are empty. ### method `__init__` ```python __init__( unique_id: 'str', name: 'str', employee_number: 'str', first_name: 'str', last_name: 'str', is_active: 'bool', employment_status: 'str' ) ``` *** ### method `add_group` ```python add_group(group_id: 'str') → None ``` Add employee to group Adds employee to a group by the group ID. Group must also be defined for HRISInstance with `HRISProvider.add_group()` **Args:** * `group_id` (str): Unique ID of HRISGroup to add employee too *** ### method `add_manager` ```python add_manager(manager_id: 'str') → None ``` Add manager to Employee Adds a manager to the employee by the manager's HRISEmployee instance unique ID. Manger employee record must also exist. **Args:** * `manager_id` (str): Unique ID for manager HRISEmployee instance *** ### method `set_property` ```python set_property( property_name: 'str', property_value: 'any', ignore_none: 'bool' = False ) → None ``` Set Employee custom property value Property name must be defined for employee before calling `set_property` **Args:** * `property_name` (str): Name of property * `property_value` (any): Value for property, type should match OAAPropertyType for property definition * `ignore_none` (bool, optional): Do not set property if value is None. Defaults to False.. Defaults to False. **Raises:** * `OAATemplateException`: If property with `property_name` is not defined. *** ### method `to_dict` ```python to_dict() → dict ``` Output employee to dictionary for payload. *** ## class `HRISGroup` HRIS Group Represents any group of employees in the HRIS system. HRISGroups can be used to represent teams, departments, cost centers or any organizational unit. Each group has a type to make searching and grouping easier. Group's Unique ID must be unique across all group types. **Args:** * `unique_id` (str): Unique ID for group * `name` (str): Display name * `group_type` (str): Type for group such as "Team", "Department", "Cost Center" ### method `__init__` ```python __init__(unique_id: 'str', name: 'str', group_type: 'str') ``` *** ### method `set_property` ```python set_property( property_name: 'str', property_value: 'any', ignore_none: 'bool' = False ) → None ``` Set HRIS Group custom property value Property name must be defined for group before calling `set_property` **Args:** * `property_name` (str): Name of property * `property_value` (any): Value for property, type should match OAAPropertyType for property definition * `ignore_none` (bool, optional): Do not set property if value is None. Defaults to False.. Defaults to False. **Raises:** * `OAATemplateException`: If property with `property_name` is not defined. *** ### method `to_dict` ```python to_dict() → dict ``` Dictionary output for inclusion in payload *** ## class `HRISPropertyDefinitions` ### method `__init__` ```python __init__() ``` *** ### method `define_employee_property` ```python define_employee_property(name: 'str', property_type: 'OAAPropertyType') → None ``` *** ### method `define_group_property` ```python define_group_property(name: 'str', property_type: 'OAAPropertyType') → None ``` *** ### method `define_system_property` ```python define_system_property(name: 'str', property_type: 'OAAPropertyType') → None ``` *** ### method `to_dict` ```python to_dict() → dict ``` *** ### method `validate_name` ```python validate_name(name: 'str') → None ``` Check property name for valid characters Raises an exception if the name string does not match required pattern. Name must start with a character and can only contain letters and \_ character. **Args:** * `name` (str): name of property to validate **Raises:** * `OAATemplateException`: Name is not a string * `OAATemplateException`: Name contains invalid characters or does not start with a letter ***