Self-Service Authorization Manager#

Introduction#

The Self Service authorization manager is meant to provide adequate access control in self-service scenarios, that is, when the resource being accessed, such as an account, must be related or owned by the requesting user. Currently, it can be used to control access to the following GraphQL APIs:

User Management GraphQL API ( User Management ) - only allows access to the account associated to the requesting subject.
Granted Authorization GraphQL API ( Granted Authorization ) - only allows access to the granted authorizations whose owner is the requesting subject.

The Self Service authorization manager is the authorization manager that should be used for the Curity Identity Server User Self-Service Portal . However, it is not exclusive to the User Self-Service Portal, and can be used with other self-service management applications.

Usage and configuration#

The Self Service authorization manager has the following resource-independent configuration settings:

Setting	Description
`required-scope`	Mandatory Configuration setting defining the name of a scope that must be present in the request’s access token. If the access token doesn’t contain the configured scope, any request will be denied. This configuration setting allows restricting the usage of the protected GraphQL APIs to a specific application (e.g. a self-service management portal).
`account-id-claim-name`	Mandatory configuration setting defining the name of the access token claim containing the subject’s account ID. The value for this claim is matched against the resources being accessed.
`mutation-throttler`	Configuration setting allows the definition of an optional throttler service that will be applied to all mutations. See Throttler Service more more information on throttling services.

In addition to the previous configuration settings, the Self Service authorization manager provides fine-grained control on which GraphQL operations are allowed, always enforcing the self-service restriction. This fine-grained control can be made in one of two alternative configuration models:

A low-level GraphQL-based model where the authorization policy is defined mostly as the set of allowed GraphQL operations.
A high-level Portal-based model where the authorization policy is defined in terms of the resources and operations that can be done by a user in a Self Service Portal, such as allowing for reading or updating of emails.

Both models can be used with the Curity Identity Server User Self-Service Portal. For simple use cases, the high-level Portal-based model is recommended. The low-level GraphQL-based should be used when fine-grained control on the GraphQL API authorization is needed, such as listing exactly the allowed queries and mutations.

GraphQL-based configuration model#

The GraphQL-based configuration model allows defining the authorization policy via the set of allowed GraphQL operations for each of the supported GraphQL APIs. It is possible to individually enable or disable access to any of these APIs.

GraphQL-based Granted Authorization model#

The GraphQL-based Granted Authorization model is composed of two configuration settings:

Setting	Description
`allowed-query-operations`	The list of GraphQL queries that are allowed. This list needs to have at least one element from the set composed of `grantedAuthorizationsByOwner` and `grantedAuthorizationsByOwnerAndClient`.
`allowed-mutation-operations`	The list of GraphQL mutations that are allowed. This list can be empty and its elements must come from the set composed of `revokeGrantedAuthorizationsByOwner` and `revokeGrantedAuthorizationsByOwnerAndClient`.

For instance, implementing a policy where the requesting app can see the user’s granted authorizations but cannot revoke them can be accomplished by:

Setting allowed-query-operations with the values grantedAuthorizationsByOwner and grantedAuthorizationsByOwnerAndClient.
Setting allowed-mutation-operations to the empty list.

GraphQL-based User Management model#

The GraphQL-based User Management model is composed of the following configuration settings:

Setting	Description
`allowed-query-operations`	List with the allowed user management query operations.
`allowed-mutation-operations`	List with the allowed user management mutation operations.
`allowed-account-update-fields`	List with the account fields that can be mutated via an `updateAccountById` mutation or a `validatePasswordAndUpdateAccountById` mutation.
`allowed-account-read-attributes`	List with the account attributes that are visible on an `accountByUserName` query or an `accountById` query.
`allowed-read-device-categories`	List with the categories of the devices that can be read.
`allowed-delete-device-categories`	List with the categories of the devices that can be deleted.

Allowed GraphQL User Management Queries#

The allowed-query-operations contains the list of allowed query operations, selected from the following set.

Query	Observations
`accountByUserName`	Can be explicitly allowed. Subject’s username must always match requested username.
`accountById`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`credentialPolicy`	Can be explicitly allowed.

Query operations not in this table are always denied and cannot be configured to be allowed.

Allowed GraphQL User Management Mutations#

The allowed-mutation-operations contains the list of allowed mutation operations, selected from the following set.

Mutation	Observations
`updateAccountById`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`validatePasswordAndUpdateAccountById`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`deleteLinkFromAccountByAccountId`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`deleteDeviceFromAccountByAccountId`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`startVerifyEmailAddress`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`completeVerifyEmailAddress`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`updatePrimaryEmailAddress`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`deleteEmailAddress`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`startVerifyPhoneNumber`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`completeVerifyPhoneNumber`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`updatePrimaryPhoneNumber`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`deletePhoneNumber`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`startVerifyPasskey`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`completeVerifyPasskey`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`startVerifyTotpDevice`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`completeVerifyTotpDevice`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`startOptInMfaSetupByAccountId`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`completeOptInMfaSetupByAccountId`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`startOptInMfaResetRecoveryCodesByAccountId`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`completeOptInMfaResetRecoveryCodesByAccountId`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`addOptInMfaFactorToAccountByAccountId`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`deleteOptInMfaFactorFromAccountByAccountId`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`resetOptInMfaStateByAccountId`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.
`deleteAccountById`	Can be explicitly allowed. Subject’s account ID must always match requested account ID.

Mutation operations not in this table are always denied and cannot be configured to be allowed.

Allowed Account Update Fields#

By default, only the following AccountUpdateFields input type field subset can be used with updateAccountById or validatePasswordAndUpdateAccountById: name, displayName, nickName, title, preferredLanguages, profileUrl, locale, timeZone, photos, addresses, website.

For instance, trying to mutate the account’s email addresses using updateAccountById or validatePasswordAndUpdateAccountById will fail, even if these mutations are allowed. The design criterion was to allow the update of fields that should be directly controlled by an end user in a self-service scenario. However, it is possible to change this default behavior by explicitly configuring the allowed-account-update-fields setting and defining the allowed fields in the inner field-names setting.

Allowed Account Read Attributes#

By default, only the following AccountAttributes are visible on an accountByUserName or accountById query: id, externalId, meta, userName, name, displayName, nickName, title, preferredLanguage, userType, profileUrl, locale, timezone, active, emails, phoneNumbers, ims, photos, addresses, groups, entitlements, roles, x509Certificates, devices, linkedAccounts, and mfaOptIn.

The design criterion was to allow the reading of attributes that an end user should be allowed to observe in a self-service scenario. It is possible to change this default behavior by explicitly configuring the allowed-account-read-attributes setting and defining the allowed attributes in the inner attribute-names setting. Independently of what is configured, the following attributes are always allowed: id, userName, and active.

Device categories#

By default, all device categories can be read or deleted, as long as the associated query or mutation are enabled. For instance, if the deleteDeviceFromAccountByAccountId mutation is enabled, then any device associated to the user’s account can be deleted. However, it is possible to have a more fine-grained control by using one of the following settings:

Setting	Description
`allowed-read-device-categories`	List with the device categories that are visible in a `accountByUserName` or `accountById` query. Possible values are `totp` and `webauthn/passkeys`.
`allowed-delete-device-categories`	List with the device categories that can be deleted via the `deleteDeviceFromAccountByAccountId` mutation. Possible values are `totp` and `webauthn/passkeys`.

Portal-based configuration model#

The Portal-based configuration model allows defining the authorization policy via the set of resources and operations managed by the Self-Service Portal.

Portal-based Granted Authorization model#

The Portal-based Granted Authorization model is composed of the granted-authorization configuration setting and defines the operations allowed on the granted-authorization resource. It is composed of two inner configuration settings:

read - defines whether reading the granted authorizations owned by the requesting subject is allowed or not. The default value is false.
delete - defines whether revoking the granted authorizations owned by the requesting subject is allowed or not. The default value is false.

Portal-based User Management model#

The Portal-based User Management model is composed of the following resources and operations.

Resource	Operation	Observations
`name`	`read`	Allows reading user’s name information.
	`update`	Allows updating user’s name information.
`address`	`read`	Allows reading user’s address information.
	`update`	Allows updating user’s address information.
`email`	`read`	Allows reading user’s email addresses.
	`update`	Allows updating user’s email addresses.
`phone-number`	`read`	Allows reading user’s phone numbers.
	`update`	Allows updating user’s phone numbers.
`totp`	`read`	Allows reading user’s TOTP devices.
	`create`	Allows creating new TOTP devices for the user.
	`delete`	Allows deleting user’s TOTP devices.
`passkey`	`read`	Allows reading user’s passkey devices.
	`create`	Allows creating new passkey devices for the user.
	`delete`	Allows deleting user’s passkey devices.
`password`	`update`	Allows updating user’s password.
`linked-accounts`	`read`	Allows reading user’s linked accounts.
	`delete`	Allows deleting user’s linked accounts.
`opt-in-mfa`	`read`	Allows reading user’s opt-in MFA configuration.
	`setup`	Allows setting up opt-in MFA for the user.
	`reset-recovery-codes`	Allows resetting recovery codes for user’s opt-in MFA.
	`remove-factor`	Allows removing MFA factors from user’s opt-in MFA configuration.
	`reset`	Allows resetting user’s opt-in MFA configuration.
`account`	`delete`	Allows deleting the account.

Administration

System and Operation

Facilities

Profiles

Developer Guide

Configuration Reference