Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The CoreOne Suite offers an extensive access management. In the domain of this access management, permissions are called resource assignments. So whenever Whenever an administrator is assigning a resource in the Admin UI, when a user receives resources through a assignment rule, or someone uses the self-service portal to delegate a service permission or a service permission of a company to someone else, those permissions are stored in the access management space as resource assignments.

...

There are use cases where those permission need to be available to the application even if the user is not present (offline access) or if the application needs to know permissions of other users or other entities (companies, users). In those cases, the permission API of the CoreOne Authentication Service can be used.

It is important to note that calls to api/permission do not read the access management space (IAM space) but the actually provisioned resources at the CoreOne Authentication Service (IdP space). For example if a user has access to a role, but that assignment was paused, the assignment will show up in the IAM space (resource assignment) but is not provisioned to the CoreOne Authentication Service (IdP space) and will not show up over the permission API, as the user currently does not have that permission.

Base URL

The base URL for the permission API is as following:

Code Block
{authentication service url}/api

Endpoints

There are two different endpoints. Depending on your use case, you might choose either one of those.

Generic permissions

Available from version 8.0 and upwards.

Code Block
{authentication service url}/api/permission

To access this endpoint, you need to have the CoreOne Authentication Service API Read Permissions for any Application assigned to your user. The endpoint itself can return all permission of all applications.

Application Specific Permissions

Available from version 9.0.3 and upwards.

Code Block
{authentication service url}/api/permission/myapplication

To access this endpoint, you need to have the CoreOne Authentication Service API Read Permissions for My Application assigned to your user. The endpoint itself only returns permissions associated to client calling the endpoint, thus restricting the permissions. In most use cases it’s advised to use this endpoint.

Authentication

In order to access the API, you will need to configure an appropriate client of the CoreOne Suite application and assign the cos_auth_api scope. Additionally you will need an appropriate user with permissions to access the data, that’s either the CoreOne Authentication Service API Read Permissions for any Application or the CoreOne Authentication Service API Read Permissions for My Application resource. Authentication then is done by passing a bearer token in each request. Also note that in order to receive the email address of a user, the client needs to have access to the email scope.

Data Objects

Permission

All the endpoints return a permission object which looks as following:

Code Block
{
    "$type": "iTsense.CoreLogin2.Server.API.Models.PermissionApiDto, iTsense.CoreLogin2.Server",
    "username": "max@dax.ch",
    "userId": 17173,
    "userEmail": "max@dax.ch",
    "role": "TrusteeApp_AddBill",
    "application": "Trustee Test Application",
    "contextType": "OrganizationUnit",
    "contextObjectIdentifier": "5445"
}

Property

Data Type

Example

Description

$type

String

"iTsense.CoreLogin2.Server.API.Models.PermissionApiDto, iTsense.CoreLogin2.Server"

Identifies the type of the object

username

String

"max@dax.ch"

The username of the user that holds the permission

userId

String

17173

The userId of the user that holds the permission

application

String

"Trustee Test Application"

The name of the application to which the permission belongs

contextType

String

"OrganizationUnit"

Defines the context type as documented here. So it's either "OrganizationUnit", "User" or "All"

contextObjectIdentifier

String

"5445"

The identifier of the context object. In this case, the internal ID of the organization unit / company. Note that you can transform this data with a context transformation.

Use Cases

For our use cases we have trustee management app, where a user can add, remove and approve bills. So the application has three rights: add, remove and approve.

...

Code Block
{authentication service url}/api/permission?contextType=User&contextObjectIdentifier=17175&application=trusteeApp

or

Code Block
{authentication service url}/api/permission/myapplication?contextType=User&contextObjectIdentifier=17175

Property

Data Type

Example

Description

contextType

String

User

Set this to User as you are interested in representations for a user

contextObjectIdentifier

String

17175

This is dependent on how the user is stored. By default it’s the user id. But if any token transformation has been applied, this might also be the users email or any other unique attribute.

application

String

trusteeApp

The name of the application to which the permission have to belong

Example result

Code Block
[
    {
        "$type": "iTsense.CoreLogin2.Server.API.Models.PermissionApiDto, iTsense.CoreLogin2.Server",
        "username": "peter@pan.de",
        "userId": 17175,
        "userEmail": "peter@pan.de",
        "role": "TrusteeApp_AddBill",
        "application": "trusteeApp",
        "contextType": "User",
        "contextObjectIdentifier": "17175"
    },
    {
        "$type": "iTsense.CoreLogin2.Server.API.Models.PermissionApiDto, iTsense.CoreLogin2.Server",
        "username": "peter@pan.de",
        "userId": 17175,
        "userEmail": "peter@pan.de",
        "role": "TrusteeApp_RemoveBill",
        "application": "trusteeApp",
        "contextType": "User",
        "contextObjectIdentifier": "17175"
    },
    {
        "$type": "iTsense.CoreLogin2.Server.API.Models.PermissionApiDto, iTsense.CoreLogin2.Server",
        "username": "peter@pan.de",
        "userId": 17175,
        "userEmail": "peter@pan.de",
        "role": "TrusteeApp_ApproveBill",
        "application": "trusteeApp",
        "contextType": "User",
        "contextObjectIdentifier": "17175"
    },
    {
        "$type": "iTsense.CoreLogin2.Server.API.Models.PermissionApiDto, iTsense.CoreLogin2.Server",
        "username": "max@dax.ch",
        "userId": 17173,
        "userEmail": "max@dax.ch",
        "role": "TrusteeApp_AddBill",
        "application": "trusteeApp",
        "contextType": "User",
        "contextObjectIdentifier": "17175"
    },
    
]

...

Code Block
{authentication service url}/api/permission?contextType=OrganizationUnit&contextObjectIdentifier=5445&application=trusteeApp

or

Code Block
{authentication service url}/api/permission/myapplication?contextType=OrganizationUnit&contextObjectIdentifier=5445

Property

Data Type

Example

Description

contextType

String

OrganizationUnit

Set this to User as you are interested in representations for a user

contextObjectIdentifier

String

5445

This is dependent on how the organization is stored. By default it’s the organization unit id. But if any token transformation has been applied, this might also be the companies UID or any other unique attribute.

application

String

trusteeApp

The name of the application to which the permission have to belong

Example Result

Code Block
[
    {
        "$type": "iTsense.CoreLogin2.Server.API.Models.PermissionApiDto, iTsense.CoreLogin2.Server",
        "username": "max@dax.ch",
        "userId": 17173,
        "userEmail": "max@dax.ch",
        "role": "TrusteeApp_AddBill",
        "application": "trusteeApp",
        "contextType": "OrganizationUnit",
        "contextObjectIdentifier": "5445"
    },
    {
        "$type": "iTsense.CoreLogin2.Server.API.Models.PermissionApiDto, iTsense.CoreLogin2.Server",
        "username": "max@dax.ch",
        "userId": 17173,
        "userEmail": "max@dax.ch",
        "role": "TrusteeApp_Approver",
        "application": "trusteeApp",
        "contextType": "OrganizationUnit",
        "contextObjectIdentifier": "5445"
    }
]

...

Code Block
{authentication service url}/api/permission?application=Trustee Test Application&userSubject=c1s:17173

or

Code Block
{authentication service url}/api/permission/myapplication?userSubject=c1s:17173

Property

Data Type

Example

Description

application

String

"Trustee Test Application"

The name of the application to which the permission have to belong

userSubject

String

c1s:17173

The subject of the user. This is usually used when the user is logged in, so the subject can be taken directly from the token.