-
Notifications
You must be signed in to change notification settings - Fork 2
Concepts
The Core BB defines several key concepts that have important implications across the Rokwire ecosystem.
Services are web-hosted applications that expose the REST APIs which make up the back-end of the Rokwire ecosystem. There are several different types of Service that are supported.
First-party services developed and maintained within the Rokwire open-source are called Building Blocks. The Building Blocks are modules which each define and implement the functionality necessary to enable a specific feature. Building Blocks may communicate with each other to perform operations which take advantage of each other's features. For example, all Building Blocks rely on the Core BB to handle authorization. Building Blocks must be hosted and managed by the same administrative organization so that user data can be shared between them freely and securely.
First-party services which are managed and hosted by the same administrative organization as the rest of the Rokwire ecosystem (ie. Building Blocks), but are not maintained within the Rokwire open-source can still be given the same level of access within the system as long as their behavior related to user data is well known and controlled. Such services may include utilities developed by the administrative organization for internal use, or even services which will someday be contributed to the Rokwire project as a Building Block, but have not yet undergone the review process.
The Rokwire ecosystem also provides support for services developed by third-parties outside of the Rokwire open-source. These services may contain proprietary technology, be offered or managed by other organizations, or provide integrations with other external systems. In any of these cases, the assumption is that the use of the user's data cannot be fully known or controlled. This means that the user must explicitly authorize these services to access the specific data necessary for them to provide their functionality. This can be done through the use of Scoped Tokens.
Warning: User data MUST NEVER be shared with a third-party service without the explicit consent of the user. This also means that User Tokens MUST NEVER be shared with these services.
The Core BB defines the concept of an Organization (Org) as an independent tenant within the Rokwire ecosystem (eg. University of Illinois Urbana-Champaign). The data for each organization will be isolated so that the Rokwire platform may be used in multi-tenant environments. All Rokwire services are required to understand and preserve isolation between organizations within the system.
An Application (App) represents a client application within the Rokwire ecosystem (eg. the Illinois app). Each Application has an associated API Key that is used to verify that traffic is coming from a valid client.
An Application may have multiple Application Types (ApplicationType, AppType), each of which represents a specific client. For example, an application may be distributed to multiple platforms (eg. Android, iOS, web...), each of which would need an associated Application Type.
An Application Type has an ID (unique, system generated), name (human readable, eg. Illinois Android App), identifier, and version.
Identifiers are unique IDs that are associated with each Application client. This ID is dependent on the distribution platform:
- Android: Application ID
- iOS: Bundle ID
- Web: Public hostname
Versions follow a <major>.<minor>.<patch> Semantic Versioning format. Each new release of a client should have an associated new Version.
Standard Applications are Applications which deliver content and services to standard end-users. These applications can be thought of as the "product" and will most likely be distributed publicly through a mobile app store or public website. While authentication may be required, no specific privileges need to be granted for users to access or use these applications.
Admin Applications are Applications intended for use by Organization Admins and System Admins who manage components of the system that extend across applications. Depending on the Permissions and Roles granted, Admin Applications display tools that can be used to manage the authorized resources. These Applications should not be distributed publicly, and should only be accessible to approved Admins. Additional authentication layers (eg. MFA) should be required to protect accounts in these Applications.
Application/Organizations (ApplicationOrganization, AppOrg) contain the configurations which join each application with the relevant organizations. Each Application/Organization is associated with one Application and one Organization, however each Application can have multiple Application/Organization associating it with different organizations (a multi-tenant application), and each Organization can have multiple Application/Organization associating it with different applications (multiple client applications within an organization).
An Application Config (ApplicationConfig, AppConfig) contains the information necessary for a client Application to send requests to the services and any other settings that the app depends on. Application Configs are associated with a specific Application Type, so that the configurations can be modified independently for each client or platform. These configs are stored and managed in the Core BB, and may be edited at any time.
The Core BB also provides a versioning system for these configs. Each Application Config record is associated with a specific Application Type Version. When the client sends a request to the /services/application/configs endpoint to retrieve these configs, it should specify its current Version. The Core BB will then find and return the Application Config document with the highest version below or equal to the specified version. This system enables admins to define a new set of configs for any release, but does not necessitate this for each release if nothing needs to be changed since the previous release.
Accounts are the main structures that define users within the system. Each account is associated with a specific Application/Organization. Accounts contain basic information about the user, including their Authentication Types, their Profile, and Preferences.
The Account ID is the primary identifier for the user throughout the system. This ID MUST be associated with all of each user's data across all services. This ID will appear in the Subject Claim of each user's Access Token for verification of access to existing user data or storage with new data.
External IDs are identifiers used by systems external to Rokwire. These IDs MUST ONLY be used when communicating with these external systems. If data is retrieved from one of these external systems using this external ID, it should then be associated with the Account ID for further processing or storage within Rokwire.
The user Profile contains the user's personal information, including:
Note: All of this information is provided at the user's discretion, and therefore may not be populated or accurate. Any of this information that is available MUST NOT be shared with any other users or external systems without the user's explicit consent.
- First Name (
first_name) - The user's first (given) name - Last Name (
last_name) - The user's last (family) name - Email (
email) - The user's primary email address - Phone (
phone) - The user's primary phone number - Birth Year (
birth_year) - The year the user was born - Address (
address) - The user's primary street address - Zip Code (
zip_code) - The user's primary address zip code - State (
state) - The user's primary address state - Country (
country) - The user's primary address country - Photo URL (
photo_url) - A URL that can be accessed to retrieve a profile photo of the user
User Preferences can be used to store a user's application specific preferences and settings. There is no defined structure for this data, so any valid JSON can be stored here. Because this data is unstructured, anything stored here is for the use of the client application, and will not be interpreted by the Core BB.
Users who choose not to sign up for an account, or choose not to login, may still access an Application as an Anonymous User using the Anonymous Flow. Each Application may be configured to enable or disable support for Anonymous Users. Anonymous Users do not have an Account, or any form of authentication. This means that Anonymous Users may only access public information within the client.
While Anonymous Users do have Anonymous IDs
Anonymous Users will receive an identifier that can be used for logging and analytics purposes.
Warning: This Anonymous ID is not verified or authenticated, so there is no guarantee that a given Anonymous ID will always be associated with the same user. There is also no guarantee that the same user will always have the same Anonymous ID. For example, clearing a device cache, reinstalling a client application, or using a new device could all result in a new Anonymous ID.
Anonymous IDs MUST NEVER be associated with personal information about the user of any kind.
Service Accounts are accounts associated with non-human entities. These service accounts are used to enable secure communication between automated systems, even when no specific user request is being served. In these cases, the services will need to be able to recognize that the request is coming from another authorized service within the system.
Service accounts can be associated with a specific Application, a specific Organization, both, or neither. In the case where an application or organization is not specified, the service account will get access to all applications or organizations respectively. They may also be granted Permissions to grant access to specific APIs throughout the system. Service Accounts may be created for First-Party Services or Third-Party Services, and therefore contain a "first-party" flag to differentiate between the two.
In order to make use of Service Accounts, the associated service must use the Service Authorization Flow. In doing so, they will receive Service Access Tokens that can be verified to ensure that the service has the appropriate permissions or properties to access an API. These Service Accounts may also be associated with a Service Registration record to validate that the token belongs to a specific registered service if such a restriction is necessary.
A Service Registration (ServiceReg) is a record containing the basic information about each Service in the Rokwire ecosystem. These records are stored in the Core BB and published publicly so that other services, client applications, and community members can verify that they are communicating with a known service.
Each Service Registration contains the following information:
| Name | Key | Type | Required | Description |
|---|---|---|---|---|
| Service ID | service_id | string | true | The Service ID of the associated service. |
| Host | host | string | true | The base URL at which the APIs for the associated service are hosted. |
| Service Account ID | service_account_id | string | false | The ID of a Service Account associated with this service. This can be used to verify that Service Tokens were generated by the service described in this record. |
| Public Key | pub_key | PubKey | false | The Public Key used by the associated service. |
The unique ID for the associated service. This ID is a human-readable name that represents the functionality provided by the service (eg. "core" for the Core BB). This ID can be used to locate the Service Registration record, and therefore must remain consistent in its association with a specific service.
Service Key Pairs are asymmetric cryptographic key pairs which are used to encrypt or sign data that is sent to or from a given Service. Asymmetric cryptography involves a key "pair" consisting of a "public" key and a "private" key. The private key must be stored securely and known only to the owner (ie. the service). The public key may be published publicly for use by others to encrypt data that can only be decrypted by the associated private key, or verify signatures that could have only been created by the associated private key.
Currently, RSA is the only cryptographic algorithm that is supported by the Core BB for this purpose.
A Public Key (PubKey) is the public key of Service Key Pair used to sign requests, receive encrypted data, or perform other cryptographic functions.
Public Key records contain the following information:
- Key PEM (
key_pem) - A PEM encoded representation of the public key. - Algorithm (
alg) - The signing algorithm that this public key should be used with. For example, "RS256" indicates that this key should be used to compute a signature on the SHA-256 digest of the data using the RSA PSS algorithm.
Identity Providers contain the configurations to support External Authentication Providers. The settings for these providers can be configured for each Application Type. The configurations are specific to the provider type, however they typically include information about the provider host, application identifiers, secrets, and any other information needed to successfully complete the authentication process.
Date/Times (DateTimes, timestamps) are structures which represent a specific moment in time. In the Rokwire ecosystem, we have adopted the RFC 3339 format for all Date/Times sent to the Services.