OAuth2 Client Model

The following is an example of an OAuth2 client model:

{
  "scopes": [
    "profile",
    "inspect"
  ],
  "description": "Developer Doc OAuth2 Test Client",
  "approved?": true,
  "redirects": [
    "https://my.domain.tld/ctr-oauth/callback.html"
  ],
  "availability": "org",
  "password": "CrXwg31_vnRHpjPXzgVzUFKHr6RO8GTL-iI8aDeUU3n48NtD7PFLhg",
  "name": "OAuth2 Developer Doc Test",
  "org-id": "f47a89bf-5d2e-4392-b770-000000000000",
  "enabled?": true,
  "grants": [
    "auth-code"
  ],
  "client-type": "confidential",
  "id": "client-3bb1e787-381d-4f12-bf32-e1158f200ddc",
  "approval-status": "approved",
  "owner-id": "f0010924-e1bc-4b03-b600-000000000000",
  "created-at": "2019-07-25T14:15:29.117Z"
}

Below are the definitions of the OAuth2 client model fields.

Client mandatory fields:

  • id - The unique ID of the client across all IROH.
  • name - A name for the client that will be user-facing.
  • client-type - It can be either confidential or public (no secret).
  • grants - A list that may contain auth-code, client-creds or device-grant.
  • redirects - A set of URIs (only for auth-code grant clients).
  • scopes - A set of scopes.
  • enabled? - A boolean; editable only by users with an Administrator role.
  • approved? - A boolean; editable only by IROH administrators.

Client optional fields:

  • description - A long description of the client that could be presented to the users during client authorization.
  • allow-partial-user-scopes? - If true, a user without all the requested scopes from the client can still authorize the client. The refresh and access tokens will only have the intersection of both scopes.
  • availability - It can be user, org or everyone. This filters the user that can grant access to this client:
    • user - Only the owner.
    • org - Only by members of the organization.
    • everyone - Any IROH user.
  • audiences - The list of audiences to add to the JWT related to this client. See https://tools.ietf.org/html/rfc7519#section-4.1.3 and https://openid.net/specs/openid-connect-core-1_0.html#IDToken.
  • owner-id - The user ID of the client’s owner.
  • org-id - The org ID of the client’s owner.
  • password - Also known as the "client’s secret"; public clients do not have a password.
  • access-token-lifetime-in-sec - Access token lifetime this client provides.
  • refresh-token-lifetime-in-sec - Refresh token lifetime this client provides.
  • enabled-by - The user ID of the admin that enabled the client.
  • disabled-by - The user ID of the admin that disabled the client.
  • approval-status- Possible values are waiting rejected approved. During client creation, some criteria will need an IROH administrator’s approval.
  • approver-id- The user D of the user (a IROH admin) that approved the client.
  • approval-message - A message left for the user.
  • client-preset-id - A Client Preset ID. For more information, see Client Presets.

Client Presets

Client Presets are objects that represent a partial construction of an OAuth2 Client. Client Presets have global visibility. They are managed by Cisco XDR administrators, thus you cannot create a client preset.

A given client can associate a client_preset_id. When doing so, the complete client that consumers will perceive will be a merging of the client fields and the client preset:

perceived client = <client> + <client preset>

This feature has the goal of making clients more manageable. It will be easier for end users to create new clients for known specific needs.

Override rules

In the case that the same field is defined in both the client and the preset:

  • For scalar values, the client value will take precedence.
  • For collection values, the fields will be merged (typically for scopes and redirects).