Organicity Accounts - Permission Component

Version: 0.3.0-development

Several functions of Organicity are not available to any user, but require additional permissions to be executed. This component streamlines the handling of reading, editing and assigning roles and permissions for specific users, and the reading and editing of clients.

The functionalities in this document are only available to the service accounts of clients, and require appropriate roles themselves, which is documented per resource.

Schemes: https

Base URL: https://accounts.organicity.eu/permissions/

Summary

Path Operation Description
/clients POST

Create a client

/clients/{clientId}/redirecturis GET

Get the redirect URIs for a given clientId

PUT

Update the redirect URIs for a given clientId

/users GET

Retrieve a list of users

/users/{userId}/roles GET

Retrieves a list of all available roles of a user

POST

Add a role to a user

/users/{userId}/roles/{roleName} DELETE

Removes a specific role from a user

GET

Tests if a user is assigned a specific role

Security

Bearer

name:
Authorization
in:
header
description:
Every API call must be authorized with a Bearer Token in the HTTP header (Authorization: Bearer <TOKEN>) provided by OrganiCity Accounts - https://accounts.organicity.eu

Paths

Create a client

POST /clients

Permission accounts-permissions:createClient required.

This endpoint allows tools to create clients.

application/json

The new client to be created.

client

Reference: Client

application/json

201 Created

The client was successfully created.

Example for application/json
{
"client_id": "c6e3c4ae-37e8-4662-b201-65ddb9bca6ff",
"secret": "e49545ba-48a0-40de-9ad9-ea75ca23f15f"
}
Reference: ClientCredentials
403 Forbidden

The requesting client does not have sufficient permissions (e.g., accounts-permissions:createClient) to create a client.

500 Internal Server Error

An unknown internal server error occured.

Bearer
Get the redirect URIs for a given clientId

GET /clients/{clientId}/redirecturis

Permission accounts-permissions:readClientRedirectUris required.

This endpoint allows tools to get the redirect URIs for clients.

clientId

The identifier of the client

path string

application/json

200 OK

The requested list of redirect URIs returned as the body of the reply as an array. If no redirect URIs are available, the array will be emtpy

Example for application/json
{
"redirectUris": [
"https://example.com/callback",
"https://login.example.com/callback"
]
}
Reference: RedirectUris
500 Internal Server Error

An unknown internal server error occured.

Bearer
Update the redirect URIs for a given clientId

PUT /clients/{clientId}/redirecturis

Permission accounts-permissions:editClientRedirectUris required.

This endpoint allows tools to update the redirect URIs for clients. This is a full update, e.g. all existing redirect URIs will be exchanged by the given one.

application/json

The list of redirect URIs

redirectUris

Reference: RedirectUris
clientId

The identifier of the client

path string
200 OK

Just a simple 200 will be returned, if the update was successful

500 Internal Server Error

An unknown internal server error occured.

Bearer
Retrieve a list of users

GET /users

Permission accounts-permissions:listUsers or/and accounts-permissions:findUserByEmail required.

This endpoint supplies a list of available user names and userIds that can be used for the more detailed actions.

Due to privacy resons, this endpoint only returns these two fields; more data can only be obtained when the respective user performs a successful login through the client and supplies an ID Token.

The endpoint always only returns a part of the list of users (paginated), given by the offset (which defaults to 0) and the page length (which defaults to the maximum value of 50). If you want to query for more users, you have to make multiple calls to the api.

The list of users is always sorted alphabetically with regard to the user name. The offset into a list is thus not guaranteed to always return a list starting with the same user, as new users might shift the offset. However, as long as the list of users itself does not change, the returned list is constant as well.

offset

Permission accounts-permissions:listUsers required.

The offset in the list of users, given as the amount of users to skip. Defaults to 0, thus returning the start of the list.

query integer , { x ∈ ℤ | x ≥ 0 }
count

Permission accounts-permissions:listUsers required.

The maximum amount of users to return as the result of the call. Only values between 1 and 50 are allowed, in order to limit the result size. Defaults to 50.

query integer , { x ∈ ℤ | 1 ≤ x ≤ 50 } 50
email

Permission accounts-permissions:findUserByEmail required.

Using this parameter allows to search for a user by an email address. If found, an HTTP 200 with a list containing one user will be returned, otherwise an HTTP 404 NOT FOUND.

query string

application/json

200 OK

The requested list of users has been extracted and is returned as the body of the reply as an array. If no users matched the query (i.e. the offset is too high), an empty array may be returned.

Example for application/json
[
{
"id": "cf2c1723-3369-4123-8b32-49abe71c0e57",
"name": "fbuether"
},
{
"id": "0dfc01f7-a234-4cbc-8e70-7ae361127dd4",
"name": "jackie"
}
]

Body Schema: object[]

An array of user identifiers, along with the human-readable user name.

Reference: UserIdentifier
401 Unauthorized

The requesting client did not supply identify information (see Security Definitions).

403 Forbidden

The requesting client does not have sufficient permissions (e.g., accounts-permissions:listUsers or/and accounts-permissions:findUserByEmail) to list users.

404 Not Found

Will be returned, if no users will be found. The body will be empty.

422 Unprocessable Entity

The given query parameters where not valid. This might occur if either the given offset or count where negative, or if count was too large.

Example for application/json
{
"error": "The given count is too large."
}
Reference: Error
500 Internal Server Error

An unknown internal server error occured.

Bearer
Retrieves a list of all available roles of a user

GET /users/{userId}/roles

Permission accounts-permissions:readGlobalRoles or/and accounts-permissions:readLocalRoles required.

This endpoint retrieves a list of all roles available to the supplied user and visible to the requesting tool. This includes global roles as well as roles specific to the requesting tool.

userId

The identifier of the user, as given by the subject field in the user's ID Token (the authentication token handed out by Organicity Accounts on login).

path string

application/json

200 OK

The request has been processed and the determined roles are returned.

Note that for a user that has no (visible) roles, an empty list is returned.

Example for application/json
[
{
"role": "experimenter"
},
{
"role": "scenarios:admin"
}
]

Body Schema: object[]

An array of roles, where each role describes a role assigned to the user.

Reference: Role
401 Unauthorized

The requesting client did not supply identify information (see Security Definitions).

403 Forbidden

The requesting client does not have sufficient permissions (e.g., accounts-permissions:readGlobalRoles or/and accounts-permissions:readLocalRoles) to inspect the roles of users.

404 Not Found

The supplied user ID does not denote an existing user.

500 Internal Server Error

An unknown internal server error occured.

Bearer
Add a role to a user

POST /users/{userId}/roles

Permission accounts-permissions:editGlobalRoles or/and accounts-permissions:editLocalRoles required.

This endpoint allows tools to assign roles to a specific user, effectively allowing the user to perform additional actions.

application/json

The new role to be assigned to the user. See the definition of roles for possible values.

role

Reference: Role
userId

The identifier of the user, as given by the subject field in the user's ID Token (the authentication token handed out by Organicity Accounts on login).

path string

application/json

201 Created

The given role was successfully assigned to the specified user. This reply is also returned if the role was already assigned to the user previously; in that case, no changes have been made.

401 Unauthorized

The requesting client did not supply identify information (see Security Definitions).

403 Forbidden

The requesting client does not have sufficient permissions (e.g., Permission accounts-permissions:editGlobalRoles or/and accounts-permissions:editLocalRoles required.) to assign roles to users.

404 Not Found

The supplied user ID does not denote an existing user.

422 Unprocessable Entity

The supplied role is not valid. This usually means that an experiment identifier was required as part of the role, but was not supplied.

Example for application/json
{
"error": "An Experiment ID is required for the given role, but was not supplied."
}
Reference: Error
500 Internal Server Error

An unknown internal server error occured.

Bearer
Removes a specific role from a user

DELETE /users/{userId}/roles/{roleName}

Permission accounts-permissions:editGlobalRoles or/and accounts-permissions:editLocalRoles required.

This endpoint allows a requesting client to remove a role from a user, effectively revoking permissions or access to specific resources.

This endpoint only allows a requesting tool to manipulate the global roles or the roles specific to itself. A tool cannot remove permissions assigned to the user that are specific to a different tool.

userId

The identifier of the user, as given by the subject field in the user's ID Token (the authentication token handed out by Organicity Accounts on login).

path string
roleName

The role to be checked for. This needs to adhere to the format specified in the Role Type Definition.

path string
experiment

This field supplies an experiment identifier if the role to be deleted is specific for an experiment.

query string

application/json

200 OK

The given role has been successfully removed from the supplied user.

401 Unauthorized

The requesting client did not supply identify information (see Security Definitions).

403 Forbidden

The requesting client does not have sufficient permissions (e.g., accounts-permissions:editGlobalRoles or/and accounts-permissions:editLocalRoles) to remove roles.

404 Not Found

The user ID does not describe a valid user, or the role name does not denote a valid role.

422 Unprocessable Entity

The supplied role is not valid. This usually means that an experiment identifier was required as part of the role, but was not supplied.

Example for application/json
{
"error": "An Experiment ID is required for the given role, but was not supplied."
}
Reference: Error
500 Internal Server Error

An unknown internal server error occured.

Bearer
Tests if a user is assigned a specific role

GET /users/{userId}/roles/{roleName}

Permission accounts-permissions:readGlobalRoles or/and accounts-permissions:readLocalRoles required.

This endpoint can be used if a tool is not interested in the complete list of assigned roles, but wants to check one specific role for a user.

userId

The identifier of the user, as given by the subject field in the user's ID Token (the authentication token handed out by Organicity Accounts on login).

path string
roleName

The role to be checked for. This needs to adhere to the format specified in the Role Type Definition.

path string
experiment

This field specifies an experiment to check against. The parameter should only be supplied if the given role requires an experiment identifier.

query string

application/json

200 OK

The role is assigned to the user.

401 Unauthorized

The requesting client did not supply identify information (see Security Definitions).

403 Forbidden

The requesting client does not have sufficient permissions (e.g., accounts-permissions:readGlobalRoles or/and accounts-permissions:readLocalRoles) to inspect roles, or the client tried to inspect permissions that are not visible to the client (e.g. because they belong to a different tool).

404 Not Found

The user ID does not describe a valid user, or the role name does not denote a valid role.

422 Unprocessable Entity

The supplied role is not valid. This usually means that an experiment identifier was required as part of the role, but was not supplied.

Example for application/json
{
"error": "An Experiment ID is required for the given role, but was not supplied."
}
Reference: Error
500 Internal Server Error

An unknown internal server error occured.

Bearer

Schema definitions

Client: object

This JSON object is needed to create a client.

clientName: string

A name for the client

clientUri: string

The URI of a client

redirectUri: string

A redirect URI for a client

{
"clientName": "A client name",
"clientUri": "http://localhost",
"redirectUri": "http://localhost"
}

ClientCredentials: object

This JSON object contains the credentials of a client

client_id: string

The unique id of a client

secret: string

The secred (e.g., the password) of the client

{
"client_id": "c6e3c4ae-37e8-4662-b201-65ddb9bca6ff",
"secret": "e49545ba-48a0-40de-9ad9-ea75ca23f15f"
}

Error: object

These JSON objects are returned when the server encounters an error on processing a request, and needs to explain further error details to the requesting client.

error: string

A detailed explanation on why the request failed.

{
"error": "The requested role does not adhere to the required format."
}

RedirectUris: object

This JSON object represents a list of redirect URIs

redirectUris: string[]

An array of redirectUris

string

All items should be URIs

{
"redirectUris": [
"https://example.com/callback",
"https://login.example.com/callback"
]
}

Role: object

This JSON object represents a role.

The actual roles are managed by the Organicity Permissions. Roles are represented by strings, which can come in two flavours:

A role might be a global role, applying to all of Organicity, or it might be specific to a single tool (a Client from the view of Organicity Accounts). A tool-specific role is called permission and is always prefixed with the tool name and a colon.

For example, the global role to create a new asset can be experimenter or participant. In contrast, the specific role of an administrator of the Scenario Tool is called: scenarios:admin.

Note: tool-specific permissions are only visible to the respective tools. Consequently, when a tool queries the Permission Component for the roles/permission of a single user, only the global roles and the permission specific to the querying tool are returned.

The following roles for users are available:

  • OC User - Everybody that is registered at OrganiCity, but does not participate in experiments
  • experimenter - OC Experimenter - People that promote and implement an experiment with the OC Platform
  • participant - OC Participant - People that participate in an experiment, e.g., by running it on their smartphones
  • sitemanager - OC Site Manager -

    TODO

  • administator - OC Administrator - Technical administration and support, e.g., the OC Facility administrator

The following roles for clients are available:

  • ocsite - OC Site - A Client, which represents a OC City Site
  • provider - OC Provider -

    TODO

The following permission are available (representative selection):

  • Account Permissions:
    • accounts-permissions:readGlobalRoles, which allows reading global roles assigned to a user.
    • accounts-permissions:readLocalRoles, which allows reading roles specific the requesting client assigned to a user.
    • accounts-permissions:editGlobalRoles, which allows adding or removing global roles to or from a user.
    • accounts-permissions:editLocalRoles, which allows adding or removing roles specific to the requesting client to or from a user.
    • accounts-permissions:listUsers, which allows listing of all users.
    • accounts-permissions:findUserByEmail, which allows to find users by an email.
    • accounts-permissions:createClient, which allows to create a client
    • accounts-permissions:readClientRedirectUris, which allows reading the redirect urls beloning to a client
    • accounts-permissions:editClientRedirectUris, which allows editing the redirect urls beloning to a client
  • Scenarios:
    • scenarios:moderator
    • scenarios:admin
  • Site Manager:
    • site-manager:role-admin
    • site-manager:dictionary-admin
    • ...

Note: Some composite permissions are given, thus an user with the role administrator has the permissions scenarios:admin and site-manager:role-admin

role: string

The name of the role

experiment: string

An experiment identifier, denoting the experiment that this specific role applies to.

This field only needs to be set for roles restricted to specific experiments. If a query specifies a such a role without supplying an experiment id, the query will fail.

{
"role": "experimenter"
}

UserIdentifier: object

This is a simple record of only user id and name, to group a system-unique identifier together with a human-readable name of a user. This record is deliberatly kept small to not leak any privacy-related information.

id: string

The unique and permanent user identifier.

name: string

The self-appointed user name.

{
"id": "0dfc01f7-a234-4cbc-8e70-7ae361127dd4",
"name": "jackie"
}