Scope Authorization Manager¶

The Scope Authorization Manager allows for OAuth scopes to be used in access decisions, such as which client should be allowed to read or write to the user managements /Users endpoint. A presented access token to a protected endpoint will be checked for containing scopes and a decision will be made based on those.

Note

The Scope Authorization Manager cannot be used to authorize access to Curity GraphQL APIs.

Policies, Actions and Rules¶

At the heart of the Scope Authorization Manager is the option to configure policies. Each policy is setup on a path for which actions will be matched and configured rules applied.

Actions¶

An action defines the action that is being performed which requires authorization. The action is checked against the policies hierarchically, in order of the most specific policy action first moving towards broader and broader policy actions up to the base policy action. As an example, an admin trying to read the /Users endpoint at the user management profile will trigger the action um:authorization-actions.user-management.users.admin.read to be checked. This will be matched against all policy actions on the following paths, in the listed order:

Listing 12 Order of policy actions matched against an action¶

um:authorization-actions.user-management.users.admin.read
um:authorization-actions.user-management.users.admin
um:authorization-actions.user-management.users
um:authorization-actions.user-management.admin.read
um:authorization-actions.user-management.admin
um:authorization-actions.user-management

See the Type Reference section on Identities, sc:authorization actions for a complete reference of available actions with descriptions on what each one entails.

Rules¶

While each policy defines exactly one action it may contain multiple rules. A rule is setup with one or more scopes and a decision for what to do when any or all of the scopes are encountered (see applicability any-of, and all-of in the rules section).

As an example, we might add a rule on the action um:authorization-actions.user-management.users.admin.read for the scopes scim and admin where we require that both (all-of) the scopes must be present in a provided access token for the request to be authorized.

Configuration¶

Refer to the Scope Authorization Manager configuration options reference section for a complete list of the available options.

A simple Scope Authorization XML configuration file (applied to the user management profile) could look something like listing Listing 13:

Listing 13 Typical example of a Scope Authorization Manager configuration¶

<config xmlns="http://tail-f.com/ns/config/1.0">
    <profiles xmlns="https://curity.se/ns/conf/base">
        <profile>
            <id>user-management</id>
            <type xmlns:um="https://curity.se/ns/conf/profile/user-management">um:user-management-service</type>
            <settings>
                <user-management-service xmlns="https://curity.se/ns/conf/profile/user-management">
                    <authorization-manager>user-management-authorization-manager</authorization-manager>
                </user-management-service>
            </settings>
        </profile>
    </profiles>
    <processing xmlns="https://curity.se/ns/conf/base">
        <authorization-managers>
            <authorization-manager>
                <id>user-management-authorization-manager</id>
                <scopes xmlns="https://curity.se/ns/conf/authorization-manager/scopes">
                    <policies>
                        <policy>
                            <action xmlns:um="https://curity.se/ns/conf/profile/user-management">um:authorization-actions.user-management.users.admin.read</action>
                            <rules>
                                <id>um-admin-read</id>
                                <scope>admin_read</scope>
                                <authorization-decision>allow</authorization-decision>
                            </rules>
                        </policy>
                    </policies>
                </scopes>
            </authorization-manager>
        </authorization-managers>
    </processing>
</config>

This XML can be added to the configuration in $IDSVR_HOME/etc/init and reloaded using the normal procedure.

When it is, the above configuration updates the user management profile adding a reference to a scope authorization manager. This scope authorization manager is then setup in the processing section, with a trivial policy. This policy applies to an action, which in this case is um:authorization-actions.user-management.users.admin.read; in plain english a policy for who should be able to access the user management /Users endpoint acting as admin with read capabilities (listing all users, and so on).

Use with OpenID Connect User Info¶

It is possible to use a scopes authorization manager to restrict access to the OpenID Connect user info endpoint. Normally, this endpoint only requires the openid scope. To further restrict this, a scopes authorization manager can be created with additional scopes. If a policy is defined with the as:authorization-actions.oauth.user-read action and configured on the OAuth profile, this will be applied whenever a client requests access to the user info endpoint. This can be seen in the following video: