Experimental

Granted Authorization GraphQL API

Important

The Granted Authorization GraphQL API is currently experimental and may be subject to breaking changes in the future.

The Granted Authorization GraphQL API allows the query and mutation of granted authorizations, which represents the set of authorizations granted by a resource owner (e.g. a user) to an OAuth 2.0 client. In the Curity Identity Server these authorizations are captured in the form of delegations (see Introduction to the Token Service) and stored by a Delegation Data Access Provider. A new delegation is created every time an access token is created based on a non-refresh grant, even if an equivalent delegation already exists. So a user may have multiple similar delegations for the same client.

In contrast, a granted authorization represents an unique aggregation of all delegations created for a given owner and client. Each granted authorization contains:

  • A string identifying the delegation owner (e.g. the authenticated username on a OAuth 2.0 code flow).
  • Information about the client to which the authorization was granted, including its unique identifier and name.
  • The authorized scopes, computed as the union of all scopes granted by all matching delegations.
  • The authorized claims, computed as the union of all claims granted by all matching delegations.
  • A creation timestamp, corresponding to the lowest creation timestamp of all matching delegations.
  • A last update timestamp, corresponding to the highest creation timestamp of all matching delegations.

By matching delegations we mean all non-revoked delegations with the given owner and client. Note also that granted authorizations are never stored and are always computed from the stored delegations.

The Granted Authorization GraphQL API allows the querying of granted authorization:

  • By an owner, which can return zero or more results.
  • By an owner and client identifier, which can produce zero or one results.

The Granted Authorization GraphQL API also allows the revocation of granted authorizations:

  • By an owner, which results in the revocation of all delegations with that owner.
  • By an owner and client identifier, which results in the revocation of all delegations with that owner and client identifier.

The Granted Authorization GraphQL API is self-documented. Check the GraphQL APIs documentation for more information about using Curity’s GraphQL APIs and obtaining the full GraphQL schema.

Endpoint

The Granted Authorization GraphQL API is exposed by Token Service endpoints with the oauth-granted-authorization-graphql-api kind.

Access Control

For the Granted Authorization GraphQL API to be usable without the Curity DevOps Dashboard, it is necessary to configure an appropriate Authorization Manager in the relevant Token Service, implementing the desired authorization policy.

Not all Authorization Managers support GraphQL APIs. As of writing, the Groups Authorization Manager and Attribute Authorization Manager have full support for the Granted Authorization GraphQL API.

All the queries operations are considered to be reads. All the revocation operations are considered to be deletes.

Licensing

The Granted Authorization GraphQL API requires a license with the GraphQL feature, including the granted-authorization restriction.

Limitations

Important

Currently, granted authorizations are an aggregation of all delegations for a given criteria. Due to this, there are some limitations, described in this section.

Granted Authorization Queries

Querying granted authorizations currently requires querying all delegations for a user or for a user and client identifier. To protect the system performance and stability, the number of queried delegations is limited. When that limit is exceeded, the returned granted authorizations may be incomplete and not reflect all the existing delegations for the query criteria. This is communicated in the query result via the warnings field present in the GrantedAuthorizationConnection type, containing an entry with the value INCOMPLETE_RESULT.

Note that this should only happen in uncommon situations, where the same user has hundreds of delegations, i.e, performed hundreds of authorization requests.

Granted Authorization Mutations

The limitation described in the previous section also applies to mutations. However, in this case the mutation operation will fail if the number of delegations to revoke exceeds a limit, instead of doing a partial revoke. This way the Curity Identity Server ensures all delegations are revoked or none are revoked.

The success or failure to revoke all delegations of a granted authorization is communicated via the success field present in the RevokeGrantedAuthorizationPayload. This type also contains an asynchronous field, communicating if the revocation was already synchronously performed (value will be false) or if the revocation will be performed asynchronously (value will be true). Currently, all successful revocations are performed synchronously, however in the future some may be performed asynchronously.

GraphQLObligation.CanDeleteAttributes obligation

Revocation of granted authorizations is considered to be a delete operation. However, the GraphQLObligation.CanDeleteAttributes obligation is not currently enforced, i.e., it will be ignored even if an authorization manager returns one in a revocation operation authorization decision.

Note that it is still possible to control the access to granted authorization revocation via an authorization manager.

  • The configured authorization manager is always called before performing the revocation and a deny response will result in the revocation not being performed.
  • If the authorization manager returns a GraphQLObligation.BeginOperation, then this obligation will be called before the revocation is performed. If this obligation denies the operation then the revocation will not be performed.

It is only the enforcement of the GraphQLObligation.CanDeleteAttributes obligation that isn’t currently supported.