UE Auth allows you to configure your API Services (oAuth Clients) to have associated Product access and Roles, which in turn can represent Permissions. In this way, just as you would configure Permissions for a user, you can configure Permissions for a client integration (machine-to-machine API integration). All United Effects services are configured to look for these permissions on the token and map access accordingly. When the "access" scope is included during a token request, all access objects including Products, Roles, Organizations, and Permissions are included in the token, where each is represented by an ID.

Context: User Access vs. Client Access

The tokenization of access is different for an Account (user) vs. that of a Client. This is necessary because Accounts may be attributed to more than one Organization.

Here is an example of a decoded user token where access was requested:

{
    "active": true,
    "sub": "d09ee4f7-941f-4679-a491-9781a424d4a8",
    "group": "xHZkqKppIHshpZxAJ9QBU",
    "x-access-group": "member",
    "x-access-organizations": "a5f69fe5-e16a-4e35-b5a4-86e1056085a9",
    "x-access-domains": {
        "a5f69fe5-e16a-4e35-b5a4-86e1056085a9": "c527bac6-f7ae-4885-b367-6a7dae4dc87f"
    },
    "x-access-products": {
        "a5f69fe5-e16a-4e35-b5a4-86e1056085a9": "b0e8f460-f9ea-428e-893f-29c040aa229e,3NPBzv0Goq 5188ec2e-b2fb-46fe-aec2-84cec906bcf4 b2836e07-d6f8-497e-bca8-7ba13224614e,NvdTUPZTGk f2ae2683-b7dd-43e8-a44c-b915191d6b2c,LxnT4-p33r 38b45a78-618c-4b4e-bfa6-b97214f70c22,rzJkbmWJhy 322f130a-1f2e-4155-8e2e-6363defb858b,EIt_ASd59z aed81f7e-cadc-4fd1-a6be-347e83f03dbe,IZgCoZggcT 75d65818-3277-4d13-8213-880d5680e1d3,FjEDLE1mY-"
    },
    "x-access-roles": {
        "a5f69fe5-e16a-4e35-b5a4-86e1056085a9": "3NPBzv0Goq::Kcesa5-3t_ rzJkbmWJhy::rRRFtJS9r9 NvdTUPZTGk::d46sD1GXKO EIt_ASd59z::EB8XFnqnum LxnT4-p33r::6HEd25CiRd FjEDLE1mY-::fRiHgv5bCv IZgCoZggcT::-Lj7V-rzzS"
    },
    "x-access-permissions": {
        "member": "6xGuyhqD5hDcQna7FNbW_-member:::accounts::update:own 6xGuyhqD5hDcQna7FNbW_-member:::accounts::read:own 6xGuyhqD5hDcQna7FNbW_-member:::accounts::delete:own 6xGuyhqD5hDcQna7FNbW_-member:::useraccess::delete:own 6xGuyhqD5hDcQna7FNbW_-member:::useraccess::read:own 6xGuyhqD5hDcQna7FNbW_-member:::operations-reset-user-password::create 6xGuyhqD5hDcQna7FNbW_-member:::operations-user::create:own 6xGuyhqD5hDcQna7FNbW_-member:::operations-invite::create:own 6xGuyhqD5hDcQna7FNbW_-member:::accounts-notification::read:own",
        "a5f69fe5-e16a-4e35-b5a4-86e1056085a9": "3NPBzv0Goq:::group::update:own 3NPBzv0Goq:::group::read:own 3NPBzv0Goq:::group-keys::read:own 3NPBzv0Goq:::accounts::create 3NPBzv0Goq:::accounts::update 3NPBzv0Goq:::accounts::read 3NPBzv0Goq:::accounts::delete 3NPBzv0Goq:::accounts-organization::read 3NPBzv0Goq:::clients::create 3NPBzv0Goq:::clients::read 3NPBzv0Goq:::clients::update 3NPBzv0Goq:::clients::delete 3NPBzv0Goq:::operations::create 3NPBzv0Goq:::initialaccesstoken::create 3NPBzv0Goq:::notification::create 3NPBzv0Goq:::notification::read 3NPBzv0Goq:::notification::update 3NPBzv0Goq:::notification::delete",
    },
    "client_id": "ee3dc1fc-e84d-46aa-b23c-a0cdafb11137",
    "exp": 1675710255,
    "iat": 1675706655,
    "iss": "https://auth.unitedeffects.com/xHZkqKppIHshpZxAJ9QBU",
    "scope": "openid email access",
    "token_type": "Bearer"
}

In the example, "x-access-permissions" is mapped by organization. There are two organizations listed within that object.

1. "member" - Not really an organization, however, it is used to signify default privileges that all users have within the Auth Group.
2. "a5f69fe5-e16a-4e35-b5a4-86e1056085a9" - An organization with this ID has the associated permissions you see as the property value. Each Permission across all products associated to this organization is listed.

Permissions are encoded in the following syntax:

PRODUCT_CODE:::PERMISSION_TARGET::PERMISSION_ACTION::OWNERSHIP_REQUIREMENT

• PRODUCT_CODE is the shorter "Coded ID" listed on the product screen in the portal (see below)
• PERMISSION_TARGET is the resource you (or we if this is a UE product) defined for access
• PERMISSION_ACTION is the action you (or we if this is a UE product) defined as acceptable against the target
• OWNERSHIP_REQUIREMENT is a conditional that lets you communicate whether the agent (person or machine) to whom this permission is attributed must "own" the resource (e.g., PERMISSION_TARGET) for the PERMISSION_ACTION to be possible. If the ownership requirement is not there (e.g., only PERMISSION_TARGET and PERMISSION ACTION are visible) then it the requirement does not apply.

In this context, "own" simply means that there is a relationship between the resource ID and the agent. For example, the combination of ACCOUNT::READ:OWN, when applied to a a user, would indicate that they can read their own account information, but no not that of anyone else. Within your own APIs, this relationship is something you ultimately control and define.

As stated, the Client Credential token with access defined is a little different. This is because Services (oAuth Clients) are not associated to Organizations and can be mapped to products directly. This distinction is important because it means that the access a Service has is inherently across all Organizations. Here is an example of such a token decoded.

{
  "group": "xHZkqKppIHshpZxAJ9QBU",
  "x-access-group": "member",
  "x-access-products": "dd3d8f04-ce9c-4329-8d06-03287ad73ef5",
  "x-access-roles": "WGNGV9HIDD::zzBtuT7Zqk",
  "x-access-permissions": "WGNGV9HIDD:::clients::update WGNGV9HIDD:::clients::create WGNGV9HIDD:::clients::read",
  "jti": "3QcPXsDVkEvojQkC_95W-",
  "sub": "d6529498-0a12-4358-8aea-9ff0d6b230f6",
  "iat": 1675710090,
  "exp": 1675713690,
  "scope": "access",
  "client_id": "d6529498-0a12-4358-8aea-9ff0d6b230f6",
  "iss": "https://auth.unitedeffects.com/xHZkqKppIHshpZxAJ9QBU",
  "aud": "https://example.com"
}

📘

NOTE: Sub and Client ID are the Same

This is a good indicator that you are dealing with a Client Credential token.

You'll notice that the token is much simpler. This particular Service seems to have permission to create, update, and read data of other oAuth Clients (Services) and is attributed to the UE Labs UE Auth portal itself via Product ID c5f21be6-040f-4e55-87c8-1328b9f6de67.

Defining Client Access

Now that we understand what Client Access means, we can define it for any given client using the API. This is a very simple process that only involves applying a single Product ID and then 1 or more Role IDs attributed to that Product ID via a single API call.

Get the Product ID

To get a Product ID from a mapped product in UE Auth, simply open the portal and select "Products" from the left navigation. In the resulting window, you will see the Product ID in the middle column of any Product you then select.

Get the Role ID

To get the Role ID from a mapped product, open the portal and select "Roles" from the left navigation. In the resulting window, you will see the various Roles attributed to each highlighted Product. Select the Role you need and you will see its ID in the right panel of the window.

Map the Product and Role to the Client

With your Product ID and Role ID ready, go to the Client Access API (click here).

You'll need to provide your Group ID, Client ID, and Product ID as part of the path. Then you'll pass your Role ID as part of an array in the body as shown below.

{
  "roles": [
    "89a152d6-203c-4b16-8ba6-340a24bc4680"
  ]
}

👍

Your Service API oAuth Client is Configured with Access!