PRD - Standardized Accounts

Overview

Background

People share information via e-mail, text, chat, phone calls or other applications. Once trust is established between two people (whether given lackadaisically or with caution) information sharing can begin after exchanging phone numbers, addresses, or profiles. Theoretically, in this one-on-one communication between two people, you know who you are sending data to, and they know who they are receiving data from. However, if trust is given too freely without validation, one or both actors may not be who they say they are.

In a world where data is shared between systems, the systems are the ones doing the sharing, not people.

The system trust factor is similar to people where if systems want to talk with each other to share information, they must first trust each other and prove who they say they are. As is the case with people, if trust is too easily given, a “bad actor” could cause irreparable damage.

To help protect systems from “bad actors” or mistakes, the trust factor is built into each communication and must contain the following two aspects:

  1. Some form of security handshake

  2. A system-based identifier for “who is who”

Objective

To help fulfill Unified Compliance’s mission statement to be THE authoritative platform for regulatory content, control frameworks, and policy guidance, one of the initiatives is to build products and functionality that extend the usage beyond professional lexicographers and glossarists to include many additional users to allow them to contribute to UC’s content repository.

To facilitate information sharing while ensuring each contributors true identity, we will establish, publicize, share, and use a standardized account definition.

Personas

Note: personas are in process of being built. Once in place, the links will be provided to those personas.

  • UC Mapper (linguist, English major, attention to detail …)

  • UC Mapper Approver (linguist, subject matter experts, …)

  • Partner Contributor (expert in their software and processes, not a linguist, busy with other tasks …)

  • Customer Contributor (institutional organization knowledge, domain expert, not a linguist, likely minimal compliance knowledge …)

Success Metrics

List project goals and the metrics we’ll use to judge success

Goal

Metric

Goal

Metric

Establish and document a standardized account schema and publish it in grcschema.org

Review and attain sign-off from the GRC schema governing body

Establish a set of APIs that utilize the standardized account schema

A UC-written application can interact with the API Gateway to establish trust and then share information

Build a frontend application that utilizes the standardized account via a set of APIs

Mapper / UCH 2.0 can establish trust and share PlantUML data which updates the federated database

and / or

Compliance Dictionary can establish trust and share term definitions that update the compliance dictionary database or federated dictionary database (TBD)

Current Challenges / Limitations

There is no established standardized account definition and interaction for SaaS applications in general or for GRC solutions in particular. Nor does UC publish or use a standardized account mechanism for any of its existing applications including Mapper, Dictionary, or the UCF. With no agreed upon standardized account definition and interaction, it makes it unnecessarily complicated for systems and applications to easily communicate and share information with one another. In particular, third-party partner applications like AuditBoard and ServiceNow have limited direct integration with UCF. In addition, without a clear understanding and agreement on what a “standardized account” is, it is leads to confusion within UC and our messaging outside our organization.

Benefits

Establishing and utilizing a standardized account definition and interaction will:

  • Prove Unified Compliance as a thought leader in the GRC space in particular and knowledge sharing in general

  • Make it easier for third-party applications to integrate with UC applications and will meet or beat third-party trust requirements

  • Set a standard for all future UC applications on how to establish trust in order to facilitate contribution

Subscription / Pricing / Billing Impacts

There is no direct monetization component tied to Standardized Accounts; however, content contributed by third parties to the public federated database and federated dictionary will need to be attributed to the person or organization that contributed the content for potential monetization. In addition, data usage will need to be tracked, specifically to users and accounts for billing purposes. Standardized accounts are an integral part of establishing who will be charged for usage and given credit for contribution.

Beta and Early Access

Alpha and Beta access must be made available to selected members of the UC mapping team as they are actively using existing UC applications. Testers can validate both the API Gateway as well as the Mapper / UC 2.0 application.

Partners such as AuditBoard and Service Now will be good candidates to test integration with their applications; however, until content is made available, the value for establishing trust with no actual sharing is minimal.

Risks and Assumptions

The requirements detailed below describe interaction with the UCF, but mostly does not mention how (through a UC frontend or via an API). By the time we move forward with implementation if this PRD and others, the decision must be made as to where governance is put in place else, we risk allowing bad content to enter the federated database, duplication or work, or unnecessary complications delaying the projects.

It assumed that third-party applications will have similar enough account requirements that they will be able to setup accounts (using organizations, accounts, and users) that they can integrate directly with UC applications.

There must be a governance process around who can sign up, who can contribute, what can be contributed, and revocation of those rights otherwise we risk losing credibility as the authoritative source.

It is assumed that we put in place role-based access control (RBAC) for both the API Gateway and the Mapper/UCH 2.0 application to control who is allowed to perform various functions.

One risk is that the establishment of organizations, accounts, and users may create a confusing onboarding and log in experience driving prospects and customers away. The onboarding and log in user experience must be made easy yet thorough to establish trust.

Milestones and Phases

List the project milestones along with how that milestone can be successfully measured.

Number

Description

Success Measurement

Number

Description

Success Measurement

 

TBD

 

 

 

 

Product Requirements

Use Cases

Happy Day Scenarios

As a content contributor, I am able to quickly set up my organization that I work for, the account that I wish to start using the software with, and my specific user details that will perform tasks such as researching terms and contributing content.

Rainy Day Scenarios

  1. After I setup my organization, I realize I made some mistakes and want to change pretty much everything including the legal name, name, description, primary e-mail address, founded date, primary phone number, and primary address.

  2. After I setup my organization, I realize I should have used a different domain and want to start over or swap out to a different domain. If I can’t change domains, then I need the existing organization to be deleted so that no one can mistakenly use it

  3. After I setup my first account, I realize I made some mistakes and want to change pretty much everything including the name, logo, primary phone number, and primary address

  4. After I setup my basic user information, I realize I made some mistakes and want to change pretty much everything including the first name, middle name, last name, and how I want to contribute.

  5. After I setup my user details so that I can contribute content, I realize I made some mistakes and want to change pretty much everything including my name prefix, suffix, middle initial, phone number, address, social accounts, languages, and membership in groups, teams, and initiatives.

  6. Someone in my organization was given authority to contribute content, but they have proven they are too junior, and I must immediately take away their privileges.

Definitions

The following term definitions must be agreed upon to ensure all stakeholders have the same understanding and will use common descriptions when discussing / using these terms.

Term

Alternative Term

Definition

Examples

GRC Schema

Comments

Term

Alternative Term

Definition

Examples

GRC Schema

Comments

Organizations

 

An entity, such as a company, an institution, or an association, comprising of one or more Person.

ServiceNow, IBM, ATT, NIST, YMCA

Organization

 

Accounts

Organizational Accounts

An organizational subcomponent for the purpose of encapsulating collections of users, data, billing, etc.

“Mapper Account”

“Research Account”

Account

Smaller organizations will likely only have one account. However, enterprises will require many accounts to ensure appropriate departments / business units are billed appropriately

Users

User Accounts

The unique identifier of a user / person for the purpose of authorization

dsmith@ibm.com

janev@att.com

User and Person

 

Requirements

Requirement

User Story

Importance

Jira Issue

Comments

Requirement

User Story

Importance

Jira Issue

Comments

Organizations - Own

 

 

 

Reference to the GRCschema definition => GRCschema - Organization

“Own” Organizations are specifically referencing a customer or partner wants to setup their own organization and update it

Ability to create and setup a new Organization with all required information as identified in the standardized account schema definition

As a customer or partner of UC I want to create a new organization so that I can start the process of onboarding new users

p1

 

Includes: legal name, name, description, domain, phone number, email address, founded year, phone number, address, social address, and classifications (e.g., NAICS Code, SIC Code …)

Ability to update my Organization for all relevant information identified in the standardized account schema definition

As a customer or partner of UC I want to update the organization I created to ensure the information is correct

p1

 

Note that currently Mapper 2.0 functionality does not allow an organization to be changed since once it is created it is now part of the published set of organizations and falls under the same discussion of governance on who has permission to make changes to an organization if in the federated database.

Ability to upload and change my Organization’s logo

As a customer or partner of UC I want to customize the look and feel of my organization by updating the logo so that it looks and feels like my organization

p3

 

 

Ability to delete my Organization

As a customer or partner of UC I want delete an organization I created by mistake and start over so that I don’t get confused as to which organization is the right one

p1

 

If users can’t delete on their own, it is fine if UC deletes on their behalf and/or puts the organization into an inactive state for later deletion or archiving.

When a user onboards their account and initial user, they create an organization (if not existing), then link the account to that org, and user to the account. The organization cannot be deleted unless the account is deleted or reassigned to a different organization.

Organizations - Federated

 

 

 

This section is about the federated aspect of Organizations where any authorized user can make changes

Ability for researchers to submit a new Organization for approval

As a content contributor I want to submit a new Organization that I want added to the Federated Database so that the Federated Database is more complete

TBD

 

Who should be able to add Organizations to the Federated Database?

Will need some governance

Ability for researchers to search for existing Organizations (including by status)

As a content contributor I want to search for existing Organizations including by status (submitted, approved …) so that I am aware of its status and can take further actions

TBD

 

 

Ability for researchers to view, edit, and delete existing Organizations

As a content contributor I want to view, edit, and delete existing Organizations so that the Federated Database is more complete

TBD

 

 

Ability for reviewer(s) to validate and approve creation, updates, or deletes of Organizations

As a reviewer I want to review and approve the Organization details to ensure it has all the pertinent information

TBD

 

As is case in AD requests and Dictionary terms, need ability to set 0 to N number of reviewers in the business rules

 

Ability to check for duplicates

As a content contributor I want the system to automatically check for duplicates to ensure the Federated Database isn’t populated with overlapping redundant data

TBD

 

 

Ability to create a new Organization as private and maintain it as private

As a content contributor I want the Organization to be visible only to users in my organization so that no other organizations are able to access our private and/or proprietary content

TBD

 

 

Ability to submit a private Organization to the public

As a content contributor I want to make a private Organization public to help keep the Federated Database more complete

 

 

 

Ability to submit an updated Organization definition and keep the version and history

As a content contributor I want to submit a subsequent version of the Organization to go through the Organization Request process so that any changes can be tracked

TBD

 

If we allow changes, we’ll want to keep track of history. This seems a bit more straight forward than other areas.

Review Workflow

 

 

 

 

Ability for account administrators to setup business rules for validation of an Organization

As an account administrator I want to manage the submission and review workflow to best match the structure of my team so that we can submit Organizations as efficiently as possible

TBD

 

For some contributors, they might not want any review since the person submitting the Organization is the domain expert. Other accounts may want one level of approval

Ability to setup task owners as a person, role or group

As an account administrator I want to flexibly manage the assignment of tasks in the Organization definition workflow process to control the queue of work so that I can best manage the workload of my team

TBD

 

Above requirement was for the number of steps. This one is for who is assigned to those steps.

Indirect assignments like roles and groups makes it much easier to maintain and quickens onboarding / offboarding efforts.

Large clients need to have many people

Ability to submit unvalidated Organization Requests

As a content contributor I want to contribute Organizations that are automatically approved with no need for validation so that my Organizations can be quickly added to the Federated Database for use

TBD

 

These Organizations must be marked as “unvalidated” to help end-users know that those Organizations should be used with caution

Accounts

 

 

 

Reference to the GRCschema definition => GRCschema - Account

along with

GRCschema - Group

GRCschema - Team

GRCschema - Initiative

Ability to create and setup a new Account with all required information as identified in the standardized account definition

 

p1

 

Includes: name, phone number, and address

Ability to update an existing Account for all relevant information identified in the standardized account definition

 

p1

 

 

Ability to upload and change the Account logo

 

p3

 

 

Ability to delete an Account

 

p1

 

If users can’t delete on their own, it is fine if UC deletes on their behalf

Ability to invite additional users to an account

 

p1

 

 

Ability to deactivate users assigned to an account

 

p2

 

 

Ability to delete users from an account

 

p2

 

If users can’t delete on their own, it is fine if UC deletes on their behalf

Ability to create, update, and delete Groups and add/remove users to those Groups

 

p2

 

 

Ability to create, update, and delete Teams and add/remove users to those Teams

 

p2

 

 

Ability to create, update, and delete Initiatives and add/remove users to those Initiatives

 

p3

 

 

Users / Persons

 

 

 

Reference to the GRCschema definition => GRCschema - User and GRCschema - Person

Ability to register as a new user with all required information as identified in the standardized account definition

 

p1

 

Includes all the basic user information defined on the User object includes first name, last name, middle name, and e-mail address

Ability to register a user as a Contributor by supplying additional trust information

 

p1

 

Includes how to contribute as (org, person, or both), two social addresses, and phone number.

Ability to supply additional optional information to help further identify the user

 

p1

 

Includes alternative names, aliases, additional email addresses, additional phone numbers, additional social addresses, postal addresses,

Contribution Managment and API Protection

 

 

 

There needs to be a workflow in place to manage who can contribute, what they can contribute, and guardrails if broken to revoke rights

Ability for UC to allow or revoke rights for an account to approve own users for contribution

As a UC Administrator I want to allow or revoke the ability of an account to determine who can contribute to the federated database so that UC can control the quality of the federated database

TBD

 

It could become burdensome on UC to do all the approving. Initially we can keep it simple where UC must always approve. In later releases, we introduce the toggle to allow customers to decide who on their teams can contribute

Ability for an Account administrator to request that a user be allowed to contribute

As a UC Administrator I want to allow or revoke the ability of any user to contribute to the federated database so that UC can control who can contribute

TBD

 

If UC doesn’t allow an account to decide on their own, then there must be a request process

Ability for an Account administrator to revoke or allow users to publish to the federated database

As an account Administrator I want to allow or revoke the ability of a user to contribute to the federated database so that I can control who on my team can contribute

TBD

 

If we allow an account, then account administrators should be in control. Some users will only be researchers and not need to contribute

Ability for UC to revoke or allow users to publish to the federated database

As a UC Administrator I want to allow or revoke the ability of any user to contribute to the federated database so that UC can control who can contribute

TBD

 

Even if allow accounts or third-party application to control who on their team can contribute, UC must be able to revoke the rights of a bad actor

Role Based Access Control

 

 

 

Not everyone can be an admin

There are two areas we need to control:

  1. permissions to perform functions like delete users

  2. control contribution workflows

The first is an obvious candidate for RBAC. But controlling contribution workflows initially “feels” like a set of toggles with a bit more meaning that purely a permission.

Ability for UC to create, update, and delete a set of default / global roles

 

 

 

 

Ability for UC to turn on / off permissions within global roles

 

 

 

 

Ability for UC to add new permissions and include them in default roles

 

 

 

 

Ability for UC to designate which role is assigned to the initial user of an organization

 

 

 

 

Ability for UC to designate which role is assigned to subsequent users in an organization

 

 

 

 

Ability for account administrators to create, update, and delete a set of custom roles

 

 

 

 

Ability for account administrators to turn on / off permissions within custom roles

 

 

 

 

Ability for account administrators to assign roles to users

 

 

 

 

Ability for account administrator to determine which role is automatically assigned to new users

 

 

 

 

Open Questions

List any open questions that come to mind throughout the lifecycle of this project

Question

Answer

Date Answered

Question

Answer

Date Answered

Both the API gateway and the Mapper 2.0 application need RBAC. How can standardize on one implementation in two different products with two different tech stacks?

 

 

 

 

 

Out of Scope / Future Functionality

List the known features that are out of scope for this project or might be revisited at a later time.

As is case with the assumptions, it is important to list these out so that architects and engineers can plan accordingly for these later updates.

Impacted Product Components

If this project is a component to other areas or an update to an existing product, specifically call out where this product will interact with other areas.

User Interaction and Design

GRCschema - Organization

GRCschema - Account

GRCschema - User

GRCschema - Person

GRCschema - Group

GRCschema - Team

GRCschema - Initiative

 

Process Flow Diagrams

Links to user journeys, process flow, or other diagrams related to the requirements.

Guides

If there are UI components to this requirement, list the main areas where interactive user guides would be needed.

Additional References

Account Standardization - Readme

The importance of Federated Linked Data to Compliance as Code - Compliance as Code

The interpretations of Compliance as Code - Compliance as Code