Authorization Scopes

An important aspect of credential configuration is the configuration (or limitation) of what actions or against what resources a credential is authorized to access. These limitations of a credential’s authorization within the application are known as “Auth Scopes” and should be considered when creating or updated an application credential.

Auth Scopes are configured by pairing a SUBJECT and VERB that define appropriate access to various actions in the application (see below for details on available SUBJECT and VERB values). The SUBJECT determines what resources can be accessed, and the VERB determines what actions can be performed on those resources.

Auth Scopes can be configured to define a credential’s access controls across the application or within a specific tenant. To define access controls across the application, use the credential’s scopes property. To define tenant-specific access controls, use the tenants property. These properties can be defined when creating or updating a credential.

For example, consider a credential creation request with the following scopes value:

"scopes": [
    {
        "verb": "READ",
        "subject": "JOBS"
    }
]

The above credential would be authorized to make readonly API endpoints organized under the “jobs” tag. Specifically, the credential would be allowed to make only the following requests:

• GET api/v1/jobs
• GET api/v1/jobs/{job_id}

If the above credential attempts to make API request to other endpoints, the request will be rejected by the application, as the credential’s Authorization Scope configuration does not allow access to other actions.

Similarly, a Credential’s tenants property is used to set tenant specific Auth Scopes. A credential can have different Auth Scopes defined for different tenants. Consider the following tenants property value:

"tenants": {
    "tenant1": [
      {
        "verb": "READ",
        "subject": "JOBS"
      }
    ],
    "tenant2": [
      {
        "verb": "READ",
        "subject": "JOBS"
      },
      {
        "verb": "WRITE",
        "subject": "JOBS"
      }
    ]
  }

The above credential would have READ access to all JOBS resources in tenant1. Additionally, the same credential would have READ and WRITE access to all JOBS resources in tenant2.

In the case where a Credential has defined values for both its scopes and tenants properties, the functional Auth Scope of the Credential will be a combination of the defined values. In other words, a credential will be permitted to perform an action if either the credential’s scope or tenants configuration allows the action. Consider a credential with the following scopes and tenant values:

"scopes": [
    {
        "verb": "READ",
        "subject": "JOBS"
    }
],
"tenants": {
    "tenant1": [
      {
        "verb": "WRITE",
        "subject": "JOBS"
      }
    ]
}

The above credential will have the authorization to READ JOBS for all tenants, but will also have the authorization to WRITE JOBS in tenant1. The credential will have READ and WRITE permissions in tenant1.

The * Wildcard

In addition to the list below, Rustici Generator supports the use of a * wildcard specification for both the SUBJECT and VERB authorization properties. This allows properties of credential authorization to be unbounded, which can help define a range of Authorization Scope for a given credential. For example, consider a credential creation request with the following scopes value:

"scopes": [
    {
        "verb": "READ",
        "subject": "*"
    }
]

The above credential would be authorized to make readonly API requests, but would be able to access endpoints organized under all tags.

Root Credentials

As another example, consider the scopes value for the following credential:

"scopes": [
    {
        "verb": "*",
        "subject": "*"
    }
]

The above credential would be authorized to all API requests, unbounded by either SUBJECT or VERB. These credentials can do whatever they want; colloquially, we call these “root” credentials or “superusers”.

Scope Configuration

The lists below define the possible SUBJECT and VERB values when defining Authorization Scopes.

Subjects

The following values can be used for a scope’s subject. These define which resources can be used in setting authorization scopes

Verbs

The following values can be used for a scope’s verb. These define what actions a credential may take towards a given authorization subject.

Note: The above verbs are NOT compounding. WRITE does not include the authorization to READ or DELETE. Likewise, DELETE does NOT include permission to WRITE or READ.