Access (Token) Scopes
Scopes govern what the application can ask for in relation to the service. The service must be part of an OAuth 2.0 Resource Server. When the user grants their consent, requested scopes are included in the Access Token, meaning that the Client is now authorized to access the requested data.
Scopes Overview
Scopes are a key access control component in SecureAuth CIAM Platform, allowing you to perform more fine-grained authorization than that for an entire Resource Server (keep in mind that all OAuth 2.0 services in your Workspace essentially constitute an OAuth 2.0 Resource Server). Scopes should reflect specific service areas (service features, functions, APIs) to which access must be controlled and user consent given explicitly.
Scope Governance
The typical way to restrict client application's access is to utilize the concept of scopes represented as a special access token claim that has a set of governance and privacy workflows connected to it.
There can be the following types of policies assigned to scopes:
Parameter | Description |
|---|---|
Human Users | Controls whether or not the Authorization Code flow can be used with this service. If enabled, you can configure the policy for such flow. |
Machine Users | Controls whether or not the Client Credentials flow can be used with this service. If enabled, you can configure the policy for such flow. |
3rd Party Developers | Controls whether or not third party developers can subscribe to this service . If enabled, you can configure the policy for such flow. |
Dynamic Client Registration | Controls whether or not dynamically registered clients can subscribe to this service. Define conditions dynamically registered clients need to meet to subscribe to a protected scope using a policy. |
Subscribing Apps to Scopes
When client applications are subscribed to scopes, they request those scopes as a part of the token request. If consent is granted by a user, then, the access token contains those scopes.
Limiting Scopes in Access Tokens
It's considered a good practice to limit the scopes the client application can request. It is done by providing the scopes to be requested as the value of the scope parameter. Then, the client application requests only the scopes that it needs. When no scopes are provided with the scope parameter, the client application receives access to all scopes.
Dynamic Scopes
Building a client application that uses the OAuth-based authorization, you need to limit the access that the client application have. The typical way to restrict that access is to utilize the concept of scopes represented as a special access token claim that has a set of governance and privacy workflows connected to it.
The API or application owner usually defines scopes as simple nouns or verbs describing actions that the client application can perform using the so-called "dot" notation. For example:
accounts.listtransactions.manageusers.delete
Such scopes are perfect if you want to control access at the coarse-grained level. However, what can pose a challenge for the client application developer is restricting access to a specific object or intent. If the developer is aware that the next set of operations relates to a single item, such as a specific account or user, they might want to restrict the authorization access token to this action or intent. It can be done by including a reference to the object as a part of the scope. Example:
account.list.05542transaction.manage.433212user.delete.2321
To facilitate this type of scenarios, we support the mechanism of dynamic scopes enabling the wildcard-based definition of scopes in addition to defining them one-by-one with their explicit authorization request.
Dynamic Scope Purpose
With dynamic scopes, your authorization flows get fine-grained and simplified, so does your access to the clients. The use of dynamic scopes not only speeds up and facilitates the process of defining scopes but also enables you to build your policies more efficiently.
Combining this capability with the SecureAuth intelligent policy-based scope governance enables a shift of the authorization logic from the application code to your authorization server offloading your developers and accelerating the application creation.
How It Works
Here's a basic authorization flow using dynamic scopes:
As an administrator, you define a dynamic scope in wildcard form
account.*as part of the protected service/resource.Client asks for scope
account.1234.SecureAuth matches the requested scope to the wildcard (dynamic) one defined by the administrator.
SecureAuth applies the scope governance policies attached to the
account.*.Optionally consent screen displays
account.1234to the users so that they know what account the client requested access to.
Dynamic Scope Syntax
The syntax for dynamic-scope names uses dot notation with generic form templates including scope parameters, for example account.*, where * represents a wildcard allowing multiple scope-name interpretations.
There are two elements in the scope name template:
Scope root, which is a fixed core of the dynamic scope name, for example account or users
Scope wildcard (*), which is an adjustable extension to the scope root allowing to retrieve a specific requested scope.
Note
scopes[user.*].params[1]returns the first parameter matched by theuser.*scope that comes in the access token.
Dynamic Scopes Matching
See the logic behind the dynamic scopes matching:
accounts.* matches accounts.read.
accounts.* matches accounts.read.foo.
accounts.read matches accounts.read.
accounts does not match accounts.read.
accounts.read.* does not match accounts.read.
accounts.*.* does not match accounts.read.
accounts.*.* matches accounts.read.own.
accounts.*.* matches accounts.read.own.other.
accounts.read.* matches accounts.read.own.
accounts.read.* matches accounts.read.own.other.
accounts.write.* does not match accounts.read.own.
accounts.*.bar matches accounts.baz.bar.
accounts.*.bar does not accounts.baz.baz.bar.
Scope Validators in Policies
Scope parameters that match wildcard parameters in the scope name are available in policy validators.
For example, if the administrator defines scope account.*.* and the client requests account.read.1234, the scope policy has access to wildcard-matched scope properties read and 1234, as well as the whole scope name.
Dynamic scope validators have at least three attributes:
Parameters available in policy validators
Note
The number of parameters matches the number of wildcards in the scope name, for example, {{users..}} has two parameters available: {{params.0}} and {{params.1}}.
Requested scope name, for example, {{users.1234}}
Scope name, for example, {{users.*}}.