Self-Service Authorization Manager

The self-service authorization manager is meant to provide adequate access control in self-service scenarios, i.e., when the resource being accessed, such as an account. must be related or owned by the requesting user. 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.

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

The mandatory required-scope configuration setting defines 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).

The mandatory account-id-claim-name configuration setting defines 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.

The 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 two 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 the Curity Identity Server 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 by two configuration settings:

  • allowed-query-operations - contains 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 - contains 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 by the following configuration settings:

  • 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 list.

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 list.

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.

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 criteria 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. Again, the design criteria 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:

  • allowed-read-device-categories - explicitly enumerates the device categories that are visible in a accountByUserName or accountById query. Possible values are totp and webauthn/passkeys.
  • allowed-delete-device-categories - explicitly enumerates 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.