feat(api): move authorization service to v2 (#10914)

# Which Problems Are Solved

As part of our efforts to simplify the structure and versions of our
APIs, were moving all existing v2beta endpoints to v2 and deprecate
them. They will be removed in Zitadel V5.

# How the Problems Are Solved

- This PR moves the authorization v2beta service and its endpoints to a
corresponding v2 version. The v2beta service and endpoints are
deprecated.
- The docs are moved to the new GA service and its endpoints. The v2beta
is not displayed anymore.
- The comments and have been improved and, where not already done, moved
from swagger annotations to proto.
- All required fields have been marked with (google.api.field_behavior)
= REQUIRED and validation rules have been added where missing.
- The `organization_id` to create an authorization is now required to be
always passed. There's no implicit fallback to the project's
organization anymore.
- The `user_id` filter has been removed in favor of the recently added
`in_user_ids` filter.
- The returned `Authorization` object has been reworked to return
`project`, `organization` and `roles` as objects like the granted `user`
already was.
- Additionally the `roles` now not only contain the granted `role_keys`,
but also the `display_name` and `group`. To implement this the query has
been updated internally. Existing APIs are unchanged and still return
just the keys.

# Additional Changes

None

# Additional Context

- part of https://github.com/zitadel/zitadel/issues/10772
- closes #10746 
- requires backport to v4.x

internal/api/grpc/authorization/v2/authorization.go

@@ -0,0 +1,76 @@
+package authorization
+
+import (
+	"context"
+
+	"connectrpc.com/connect"
+	"google.golang.org/protobuf/types/known/timestamppb"
+
+	"github.com/zitadel/zitadel/internal/domain"
+	"github.com/zitadel/zitadel/internal/eventstore/v1/models"
+	"github.com/zitadel/zitadel/pkg/grpc/authorization/v2"
+)
+
+func (s *Server) CreateAuthorization(ctx context.Context, req *connect.Request[authorization.CreateAuthorizationRequest]) (*connect.Response[authorization.CreateAuthorizationResponse], error) {
+	grant := &domain.UserGrant{
+		UserID:    req.Msg.UserId,
+		ProjectID: req.Msg.ProjectId,
+		RoleKeys:  req.Msg.RoleKeys,
+		ObjectRoot: models.ObjectRoot{
+			ResourceOwner: req.Msg.GetOrganizationId(),
+		},
+	}
+	grant, err := s.command.AddUserGrant(ctx, grant, s.command.NewPermissionCheckUserGrantWrite(ctx))
+	if err != nil {
+		return nil, err
+	}
+	return connect.NewResponse(&authorization.CreateAuthorizationResponse{
+		Id:           grant.AggregateID,
+		CreationDate: timestamppb.New(grant.ChangeDate),
+	}), nil
+}
+
+func (s *Server) UpdateAuthorization(ctx context.Context, request *connect.Request[authorization.UpdateAuthorizationRequest]) (*connect.Response[authorization.UpdateAuthorizationResponse], error) {
+	userGrant, err := s.command.ChangeUserGrant(ctx, &domain.UserGrant{
+		ObjectRoot: models.ObjectRoot{
+			AggregateID: request.Msg.Id,
+		},
+		RoleKeys: request.Msg.RoleKeys,
+	}, true, true, s.command.NewPermissionCheckUserGrantWrite(ctx))
+	if err != nil {
+		return nil, err
+	}
+	return connect.NewResponse(&authorization.UpdateAuthorizationResponse{
+		ChangeDate: timestamppb.New(userGrant.ChangeDate),
+	}), nil
+}
+
+func (s *Server) DeleteAuthorization(ctx context.Context, request *connect.Request[authorization.DeleteAuthorizationRequest]) (*connect.Response[authorization.DeleteAuthorizationResponse], error) {
+	details, err := s.command.RemoveUserGrant(ctx, request.Msg.Id, "", true, s.command.NewPermissionCheckUserGrantDelete(ctx))
+	if err != nil {
+		return nil, err
+	}
+	return connect.NewResponse(&authorization.DeleteAuthorizationResponse{
+		DeletionDate: timestamppb.New(details.EventDate),
+	}), nil
+}
+
+func (s *Server) ActivateAuthorization(ctx context.Context, request *connect.Request[authorization.ActivateAuthorizationRequest]) (*connect.Response[authorization.ActivateAuthorizationResponse], error) {
+	details, err := s.command.ReactivateUserGrant(ctx, request.Msg.Id, "", s.command.NewPermissionCheckUserGrantWrite(ctx))
+	if err != nil {
+		return nil, err
+	}
+	return connect.NewResponse(&authorization.ActivateAuthorizationResponse{
+		ChangeDate: timestamppb.New(details.EventDate),
+	}), nil
+}
+
+func (s *Server) DeactivateAuthorization(ctx context.Context, request *connect.Request[authorization.DeactivateAuthorizationRequest]) (*connect.Response[authorization.DeactivateAuthorizationResponse], error) {
+	details, err := s.command.DeactivateUserGrant(ctx, request.Msg.Id, "", s.command.NewPermissionCheckUserGrantWrite(ctx))
+	if err != nil {
+		return nil, err
+	}
+	return connect.NewResponse(&authorization.DeactivateAuthorizationResponse{
+		ChangeDate: timestamppb.New(details.EventDate),
+	}), nil
+}

internal/api/grpc/authorization/v2/integration_test/server_test.go

@@ -0,0 +1,67 @@
+//go:build integration
+
+package authorization_test
+
+import (
+	"context"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/muhlemmer/gu"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/zitadel/zitadel/internal/integration"
+	"github.com/zitadel/zitadel/pkg/grpc/feature/v2"
+)
+
+var (
+	EmptyCTX             context.Context
+	IAMCTX               context.Context
+	Instance             *integration.Instance
+	InstanceQuery        *integration.Instance
+	InstancePermissionV2 *integration.Instance
+)
+
+func TestMain(m *testing.M) {
+	os.Exit(func() int {
+		ctx, cancel := context.WithTimeout(context.Background(), 15*time.Minute)
+		defer cancel()
+		EmptyCTX = ctx
+		Instance = integration.NewInstance(ctx)
+		InstanceQuery = integration.NewInstance(ctx) // use a separate instance for queries to avoid side effects
+		IAMCTX = Instance.WithAuthorizationToken(ctx, integration.UserTypeIAMOwner)
+		InstancePermissionV2 = integration.NewInstance(ctx)
+		return m.Run()
+	}())
+}
+
+func ensureFeaturePermissionV2Enabled(t *testing.T, instance *integration.Instance) {
+	ctx := instance.WithAuthorizationToken(EmptyCTX, integration.UserTypeIAMOwner)
+	f, err := instance.Client.FeatureV2.GetInstanceFeatures(ctx, &feature.GetInstanceFeaturesRequest{
+		Inheritance: true,
+	})
+	require.NoError(t, err)
+	if f.PermissionCheckV2.GetEnabled() {
+		return
+	}
+	_, err = instance.Client.FeatureV2.SetInstanceFeatures(ctx, &feature.SetInstanceFeaturesRequest{
+		PermissionCheckV2: gu.Ptr(true),
+	})
+	require.NoError(t, err)
+	retryDuration, tick := integration.WaitForAndTickWithMaxDuration(ctx, 5*time.Minute)
+	require.EventuallyWithT(t,
+		func(ttt *assert.CollectT) {
+			f, err := instance.Client.FeatureV2.GetInstanceFeatures(ctx, &feature.GetInstanceFeaturesRequest{
+				Inheritance: true,
+			})
+			assert.NoError(ttt, err)
+			if f.PermissionCheckV2.GetEnabled() {
+				return
+			}
+		},
+		retryDuration,
+		tick,
+		"timed out waiting for ensuring instance feature")
+}

internal/api/grpc/authorization/v2/query.go

@@ -0,0 +1,216 @@
+package authorization
+
+import (
+	"context"
+	"errors"
+
+	"connectrpc.com/connect"
+	"google.golang.org/protobuf/types/known/timestamppb"
+
+	"github.com/zitadel/zitadel/internal/api/grpc/filter/v2"
+	"github.com/zitadel/zitadel/internal/domain"
+	"github.com/zitadel/zitadel/internal/query"
+	"github.com/zitadel/zitadel/pkg/grpc/authorization/v2"
+	filter_pb "github.com/zitadel/zitadel/pkg/grpc/filter/v2"
+)
+
+func (s *Server) ListAuthorizations(ctx context.Context, req *connect.Request[authorization.ListAuthorizationsRequest]) (*connect.Response[authorization.ListAuthorizationsResponse], error) {
+	queries, err := s.listAuthorizationsRequestToModel(req.Msg)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := s.query.UserGrants(ctx, queries, false, s.checkPermission)
+	if err != nil {
+		return nil, err
+	}
+	return connect.NewResponse(&authorization.ListAuthorizationsResponse{
+		Authorizations: userGrantsToPb(resp.UserGrants),
+		Pagination:     filter.QueryToPaginationPb(queries.SearchRequest, resp.SearchResponse),
+	}), nil
+}
+
+func (s *Server) listAuthorizationsRequestToModel(req *authorization.ListAuthorizationsRequest) (*query.UserGrantsQueries, error) {
+	offset, limit, asc, err := filter.PaginationPbToQuery(s.systemDefaults, req.Pagination)
+	if err != nil {
+		return nil, err
+	}
+	queries, err := AuthorizationQueriesToQuery(req.Filters)
+	if err != nil {
+		return nil, err
+	}
+	return &query.UserGrantsQueries{
+		SearchRequest: query.SearchRequest{
+			Offset:        offset,
+			Limit:         limit,
+			Asc:           asc,
+			SortingColumn: authorizationFieldNameToSortingColumn(req.GetSortingColumn()),
+		},
+		Queries: queries,
+	}, nil
+}
+
+func authorizationFieldNameToSortingColumn(field authorization.AuthorizationFieldName) query.Column {
+	switch field {
+	case authorization.AuthorizationFieldName_AUTHORIZATION_FIELD_NAME_UNSPECIFIED:
+		return query.UserGrantCreationDate
+	case authorization.AuthorizationFieldName_AUTHORIZATION_FIELD_NAME_CREATED_DATE:
+		return query.UserGrantCreationDate
+	case authorization.AuthorizationFieldName_AUTHORIZATION_FIELD_NAME_CHANGED_DATE:
+		return query.UserGrantChangeDate
+	case authorization.AuthorizationFieldName_AUTHORIZATION_FIELD_NAME_ID:
+		return query.UserGrantID
+	case authorization.AuthorizationFieldName_AUTHORIZATION_FIELD_NAME_USER_ID:
+		return query.UserGrantUserID
+	case authorization.AuthorizationFieldName_AUTHORIZATION_FIELD_NAME_PROJECT_ID:
+		return query.UserGrantProjectID
+	case authorization.AuthorizationFieldName_AUTHORIZATION_FIELD_NAME_ORGANIZATION_ID:
+		return query.UserGrantResourceOwner
+	case authorization.AuthorizationFieldName_AUTHORIZATION_FIELD_NAME_USER_ORGANIZATION_ID:
+		return query.UserResourceOwnerCol
+	default:
+		return query.UserGrantCreationDate
+	}
+}
+
+func AuthorizationQueriesToQuery(queries []*authorization.AuthorizationsSearchFilter) (q []query.SearchQuery, err error) {
+	q = make([]query.SearchQuery, len(queries))
+	for i, query := range queries {
+		q[i], err = AuthorizationSearchFilterToQuery(query)
+		if err != nil {
+			return nil, err
+		}
+	}
+	return q, nil
+}
+
+func AuthorizationSearchFilterToQuery(query *authorization.AuthorizationsSearchFilter) (query.SearchQuery, error) {
+	switch q := query.Filter.(type) {
+	case *authorization.AuthorizationsSearchFilter_AuthorizationIds:
+		return AuthorizationIDQueryToModel(q.AuthorizationIds)
+	case *authorization.AuthorizationsSearchFilter_OrganizationId:
+		return AuthorizationOrganizationIDQueryToModel(q.OrganizationId)
+	case *authorization.AuthorizationsSearchFilter_State:
+		return AuthorizationStateQueryToModel(q.State)
+	case *authorization.AuthorizationsSearchFilter_InUserIds:
+		return AuthorizationInUserIDsQueryToModel(q.InUserIds)
+	case *authorization.AuthorizationsSearchFilter_UserOrganizationId:
+		return AuthorizationUserOrganizationIDQueryToModel(q.UserOrganizationId)
+	case *authorization.AuthorizationsSearchFilter_UserPreferredLoginName:
+		return AuthorizationUserNameQueryToModel(q.UserPreferredLoginName)
+	case *authorization.AuthorizationsSearchFilter_UserDisplayName:
+		return AuthorizationDisplayNameQueryToModel(q.UserDisplayName)
+	case *authorization.AuthorizationsSearchFilter_ProjectId:
+		return AuthorizationProjectIDQueryToModel(q.ProjectId)
+	case *authorization.AuthorizationsSearchFilter_ProjectName:
+		return AuthorizationProjectNameQueryToModel(q.ProjectName)
+	case *authorization.AuthorizationsSearchFilter_RoleKey:
+		return AuthorizationRoleKeyQueryToModel(q.RoleKey)
+	case *authorization.AuthorizationsSearchFilter_ProjectGrantId:
+		return AuthorizationProjectGrantIDQueryToModel(q.ProjectGrantId)
+	default:
+		return nil, errors.New("invalid query")
+	}
+}
+
+func AuthorizationIDQueryToModel(q *filter_pb.InIDsFilter) (query.SearchQuery, error) {
+	return query.NewUserGrantInIDsSearchQuery(q.Ids)
+}
+
+func AuthorizationDisplayNameQueryToModel(q *authorization.UserDisplayNameQuery) (query.SearchQuery, error) {
+	return query.NewUserGrantDisplayNameQuery(q.DisplayName, filter.TextMethodPbToQuery(q.Method))
+}
+
+func AuthorizationOrganizationIDQueryToModel(q *filter_pb.IDFilter) (query.SearchQuery, error) {
+	return query.NewUserGrantResourceOwnerSearchQuery(q.Id)
+}
+
+func AuthorizationProjectIDQueryToModel(q *filter_pb.IDFilter) (query.SearchQuery, error) {
+	return query.NewUserGrantProjectIDSearchQuery(q.Id)
+}
+
+func AuthorizationProjectNameQueryToModel(q *authorization.ProjectNameQuery) (query.SearchQuery, error) {
+	return query.NewUserGrantProjectNameQuery(q.Name, filter.TextMethodPbToQuery(q.Method))
+}
+
+func AuthorizationProjectGrantIDQueryToModel(q *filter_pb.IDFilter) (query.SearchQuery, error) {
+	return query.NewUserGrantGrantIDSearchQuery(q.Id)
+}
+
+func AuthorizationRoleKeyQueryToModel(q *authorization.RoleKeyQuery) (query.SearchQuery, error) {
+	return query.NewUserGrantRoleQuery(q.Key)
+}
+
+func AuthorizationUserNameQueryToModel(q *authorization.UserPreferredLoginNameQuery) (query.SearchQuery, error) {
+	return query.NewUserGrantUsernameQuery(q.LoginName, filter.TextMethodPbToQuery(q.Method))
+}
+
+func AuthorizationInUserIDsQueryToModel(q *filter_pb.InIDsFilter) (query.SearchQuery, error) {
+	return query.NewUserGrantInUserIDsSearchQuery(q.Ids)
+}
+
+func AuthorizationUserOrganizationIDQueryToModel(q *filter_pb.IDFilter) (query.SearchQuery, error) {
+	return query.NewUserGrantUserResourceOwnerSearchQuery(q.Id)
+}
+
+func AuthorizationStateQueryToModel(q *authorization.StateQuery) (query.SearchQuery, error) {
+	return query.NewUserGrantStateQuery(domain.UserGrantState(q.State))
+}
+
+func userGrantsToPb(userGrants []*query.UserGrant) []*authorization.Authorization {
+	o := make([]*authorization.Authorization, len(userGrants))
+	for i, grant := range userGrants {
+		o[i] = userGrantToPb(grant)
+	}
+	return o
+}
+
+func userGrantToPb(userGrant *query.UserGrant) *authorization.Authorization {
+	return &authorization.Authorization{
+		Id:           userGrant.ID,
+		CreationDate: timestamppb.New(userGrant.CreationDate),
+		ChangeDate:   timestamppb.New(userGrant.ChangeDate),
+		Project: &authorization.Project{
+			Id:             userGrant.ProjectID,
+			Name:           userGrant.ProjectName,
+			OrganizationId: userGrant.ProjectResourceOwner,
+		},
+		Organization: &authorization.Organization{
+			Id:   userGrant.ResourceOwner,
+			Name: userGrant.OrgName,
+		},
+		User: &authorization.User{
+			Id:                 userGrant.UserID,
+			PreferredLoginName: userGrant.PreferredLoginName,
+			DisplayName:        userGrant.DisplayName,
+			AvatarUrl:          userGrant.AvatarURL,
+			OrganizationId:     userGrant.UserResourceOwner,
+		},
+		State: userGrantStateToPb(userGrant.State),
+		Roles: rolesToPb(userGrant.RoleInformation),
+	}
+}
+
+func rolesToPb(roles []query.Role) []*authorization.Role {
+	r := make([]*authorization.Role, len(roles))
+	for i, role := range roles {
+		r[i] = &authorization.Role{
+			Key:         role.Key,
+			DisplayName: role.DisplayName,
+			Group:       role.GroupName,
+		}
+	}
+	return r
+}
+
+func userGrantStateToPb(state domain.UserGrantState) authorization.State {
+	switch state {
+	case domain.UserGrantStateActive:
+		return authorization.State_STATE_ACTIVE
+	case domain.UserGrantStateInactive:
+		return authorization.State_STATE_INACTIVE
+	case domain.UserGrantStateUnspecified, domain.UserGrantStateRemoved:
+		return authorization.State_STATE_UNSPECIFIED
+	default:
+		return authorization.State_STATE_UNSPECIFIED
+	}
+}

internal/api/grpc/authorization/v2/server.go

@@ -0,0 +1,60 @@
+package authorization
+
+import (
+	"net/http"
+
+	"connectrpc.com/connect"
+	"google.golang.org/protobuf/reflect/protoreflect"
+
+	"github.com/zitadel/zitadel/internal/api/authz"
+	"github.com/zitadel/zitadel/internal/command"
+	"github.com/zitadel/zitadel/internal/config/systemdefaults"
+	"github.com/zitadel/zitadel/internal/domain"
+	"github.com/zitadel/zitadel/internal/query"
+	"github.com/zitadel/zitadel/pkg/grpc/authorization/v2"
+	"github.com/zitadel/zitadel/pkg/grpc/authorization/v2/authorizationconnect"
+)
+
+var _ authorizationconnect.AuthorizationServiceHandler = (*Server)(nil)
+
+type Server struct {
+	systemDefaults systemdefaults.SystemDefaults
+	command        *command.Commands
+	query          *query.Queries
+
+	checkPermission domain.PermissionCheck
+}
+
+func CreateServer(
+	systemDefaults systemdefaults.SystemDefaults,
+	command *command.Commands,
+	query *query.Queries,
+	checkPermission domain.PermissionCheck,
+) *Server {
+	return &Server{
+		systemDefaults:  systemDefaults,
+		command:         command,
+		query:           query,
+		checkPermission: checkPermission,
+	}
+}
+
+func (s *Server) RegisterConnectServer(interceptors ...connect.Interceptor) (string, http.Handler) {
+	return authorizationconnect.NewAuthorizationServiceHandler(s, connect.WithInterceptors(interceptors...))
+}
+
+func (s *Server) FileDescriptor() protoreflect.FileDescriptor {
+	return authorization.File_zitadel_authorization_v2_authorization_service_proto
+}
+
+func (s *Server) AppName() string {
+	return authorization.AuthorizationService_ServiceDesc.ServiceName
+}
+
+func (s *Server) MethodPrefix() string {
+	return authorization.AuthorizationService_ServiceDesc.ServiceName
+}
+
+func (s *Server) AuthMethods() authz.MethodMapping {
+	return authorization.AuthorizationService_AuthMethods
+}

internal/api/grpc/authorization/v2beta/integration_test/query_test.go

@@ -487,17 +487,17 @@ func createAuthorization(ctx context.Context, instance *integration.Instance, t
 	return createAuthorizationForProject(ctx, instance, t, orgID, userID, projectName, projectResp.GetId())
 }
 
-func createAuthorizationForProject(ctx context.Context, instance *integration.Instance, t *testing.T, orgID, userID, projectName, projectID string) *authorization.Authorization {
+func createAuthorizationForProject(ctx context.Context, instance *integration.Instance, t *testing.T, organizationID, userID, projectName, projectID string) *authorization.Authorization {
 	userResp, err := instance.Client.UserV2.GetUserByID(ctx, &user.GetUserByIDRequest{UserId: userID})
 	require.NoError(t, err)
 
-	authResp := instance.CreateAuthorizationProject(t, ctx, projectID, userID)
+	authResp := instance.CreateAuthorizationProject(t, ctx, projectID, userID, organizationID)
 	return &authorization.Authorization{
 		Id:                    authResp.GetId(),
 		ProjectId:             projectID,
 		ProjectName:           projectName,
-		ProjectOrganizationId: orgID,
-		OrganizationId:        orgID,
+		ProjectOrganizationId: organizationID,
+		OrganizationId:        organizationID,
 		CreationDate:          authResp.GetCreationDate(),
 		ChangeDate:            authResp.GetCreationDate(),
 		State:                 1,

internal/api/grpc/oidc/v2/integration_test/oidc_test.go

@@ -961,12 +961,12 @@ func createProjectGrant(ctx context.Context, t *testing.T, projectID, grantedOrg
 	}, retryDuration, tick)
 }
 
-func createProjectUserGrant(ctx context.Context, t *testing.T, orgID, projectID, userID string) {
-	resp := Instance.CreateAuthorizationProject(t, ctx, projectID, userID)
+func createProjectUserGrant(ctx context.Context, t *testing.T, organizationID, projectID, userID string) {
+	resp := Instance.CreateAuthorizationProject(t, ctx, projectID, userID, organizationID)
 
 	retryDuration, tick := integration.WaitForAndTickWithMaxDuration(ctx, time.Minute)
 	require.EventuallyWithT(t, func(collect *assert.CollectT) {
-		_, err := Instance.Client.Mgmt.GetUserGrantByID(integration.SetOrgID(ctx, orgID), &mgmt.GetUserGrantByIDRequest{
+		_, err := Instance.Client.Mgmt.GetUserGrantByID(integration.SetOrgID(ctx, organizationID), &mgmt.GetUserGrantByIDRequest{
 			UserId:  userID,
 			GrantId: resp.GetId(),
 		})

internal/api/grpc/oidc/v2beta/integration_test/oidc_test.go

@@ -692,12 +692,12 @@ func createOIDCApplication(ctx context.Context, t *testing.T, projectRoleCheck,
 	return project.GetId(), clientV2.GetClientId()
 }
 
-func createProjectUserGrant(ctx context.Context, t *testing.T, orgID, projectID, userID string) {
-	resp := Instance.CreateAuthorizationProject(t, ctx, projectID, userID)
+func createProjectUserGrant(ctx context.Context, t *testing.T, organizationID, projectID, userID string) {
+	resp := Instance.CreateAuthorizationProject(t, ctx, projectID, userID, organizationID)
 
 	retryDuration, tick := integration.WaitForAndTickWithMaxDuration(ctx, time.Minute)
 	require.EventuallyWithT(t, func(collect *assert.CollectT) {
-		_, err := Instance.Client.Mgmt.GetUserGrantByID(integration.SetOrgID(ctx, orgID), &mgmt.GetUserGrantByIDRequest{
+		_, err := Instance.Client.Mgmt.GetUserGrantByID(integration.SetOrgID(ctx, organizationID), &mgmt.GetUserGrantByIDRequest{
 			UserId:  userID,
 			GrantId: resp.GetId(),
 		})

internal/api/grpc/saml/v2/integration_test/saml_test.go

@@ -715,12 +715,12 @@ func createProjectGrant(ctx context.Context, t *testing.T, projectID, grantedOrg
 	}, retryDuration, tick)
 }
 
-func createProjectUserGrant(ctx context.Context, t *testing.T, orgID, projectID, userID string) {
-	resp := Instance.CreateAuthorizationProject(t, ctx, projectID, userID)
+func createProjectUserGrant(ctx context.Context, t *testing.T, organizationID, projectID, userID string) {
+	resp := Instance.CreateAuthorizationProject(t, ctx, projectID, userID, organizationID)
 
 	retryDuration, tick := integration.WaitForAndTickWithMaxDuration(ctx, time.Minute)
 	require.EventuallyWithT(t, func(collect *assert.CollectT) {
-		_, err := Instance.Client.Mgmt.GetUserGrantByID(integration.SetOrgID(ctx, orgID), &mgmt.GetUserGrantByIDRequest{
+		_, err := Instance.Client.Mgmt.GetUserGrantByID(integration.SetOrgID(ctx, organizationID), &mgmt.GetUserGrantByIDRequest{
 			UserId:  userID,
 			GrantId: resp.GetId(),
 		})

internal/integration/client.go

@@ -27,7 +27,8 @@ import (
 	app_v2beta "github.com/zitadel/zitadel/pkg/grpc/app/v2beta"
 	"github.com/zitadel/zitadel/pkg/grpc/application/v2"
 	"github.com/zitadel/zitadel/pkg/grpc/auth"
-	authorization "github.com/zitadel/zitadel/pkg/grpc/authorization/v2beta"
+	authorization_v2 "github.com/zitadel/zitadel/pkg/grpc/authorization/v2"
+	authorization_v2beta "github.com/zitadel/zitadel/pkg/grpc/authorization/v2beta"
 	"github.com/zitadel/zitadel/pkg/grpc/feature/v2"
 	feature_v2beta "github.com/zitadel/zitadel/pkg/grpc/feature/v2beta"
 	group_v2 "github.com/zitadel/zitadel/pkg/grpc/group/v2"
@@ -90,7 +91,8 @@ type Client struct {
 	ApplicationV2            application.ApplicationServiceClient
 	InternalPermissionv2Beta internal_permission_v2beta.InternalPermissionServiceClient
 	InternalPermissionV2     internal_permission_v2.InternalPermissionServiceClient
-	AuthorizationV2Beta      authorization.AuthorizationServiceClient
+	AuthorizationV2Beta      authorization_v2beta.AuthorizationServiceClient //nolint:staticcheck // deprecated, but still used in tests
+	AuthorizationV2          authorization_v2.AuthorizationServiceClient
 	GroupV2                  group_v2.GroupServiceClient
 }
 
@@ -137,7 +139,8 @@ func newClient(ctx context.Context, target string) (*Client, error) {
 		ApplicationV2:            application.NewApplicationServiceClient(cc),
 		InternalPermissionv2Beta: internal_permission_v2beta.NewInternalPermissionServiceClient(cc),
 		InternalPermissionV2:     internal_permission_v2.NewInternalPermissionServiceClient(cc),
-		AuthorizationV2Beta:      authorization.NewAuthorizationServiceClient(cc),
+		AuthorizationV2Beta:      authorization_v2beta.NewAuthorizationServiceClient(cc),
+		AuthorizationV2:          authorization_v2.NewAuthorizationServiceClient(cc),
 		GroupV2:                  group_v2.NewGroupServiceClient(cc),
 	}
 	return client, client.pollHealth(ctx)
@@ -968,20 +971,23 @@ func (i *Instance) ActivateProjectGrant(ctx context.Context, t *testing.T, proje
 	return resp
 }
 
-func (i *Instance) CreateAuthorizationProject(t *testing.T, ctx context.Context, projectID, userID string) *authorization.CreateAuthorizationResponse {
-	resp, err := i.Client.AuthorizationV2Beta.CreateAuthorization(ctx, &authorization.CreateAuthorizationRequest{
-		UserId:    userID,
-		ProjectId: projectID,
+func (i *Instance) CreateAuthorizationProject(t *testing.T, ctx context.Context, projectID, userID, organizationID string, roles ...string) *authorization_v2.CreateAuthorizationResponse {
+	resp, err := i.Client.AuthorizationV2.CreateAuthorization(ctx, &authorization_v2.CreateAuthorizationRequest{
+		UserId:         userID,
+		ProjectId:      projectID,
+		OrganizationId: organizationID,
+		RoleKeys:       roles,
 	})
 	require.NoError(t, err)
 	return resp
 }
 
-func (i *Instance) CreateAuthorizationProjectGrant(t *testing.T, ctx context.Context, projectID, orgID, userID string) *authorization.CreateAuthorizationResponse {
-	resp, err := i.Client.AuthorizationV2Beta.CreateAuthorization(ctx, &authorization.CreateAuthorizationRequest{
+func (i *Instance) CreateAuthorizationProjectGrant(t *testing.T, ctx context.Context, projectID, organizationID, userID string, roles ...string) *authorization_v2.CreateAuthorizationResponse {
+	resp, err := i.Client.AuthorizationV2.CreateAuthorization(ctx, &authorization_v2.CreateAuthorizationRequest{
 		UserId:         userID,
 		ProjectId:      projectID,
-		OrganizationId: gu.Ptr(orgID),
+		OrganizationId: organizationID,
+		RoleKeys:       roles,
 	})
 	require.NoError(t, err)
 	return resp

internal/query/user_grant.go

@@ -3,7 +3,9 @@ package query
 import (
 	"context"
 	"database/sql"
+	"encoding/json"
 	"errors"
+	"fmt"
 	"slices"
 	"time"
 
@@ -21,11 +23,12 @@ import (
 
 type UserGrant struct {
 	// ID represents the aggregate id (id of the user grant)
-	ID           string                     `json:"id,omitempty"`
-	CreationDate time.Time                  `json:"creation_date,omitempty"`
-	ChangeDate   time.Time                  `json:"change_date,omitempty"`
-	Sequence     uint64                     `json:"sequence,omitempty"`
-	Roles        database.TextArray[string] `json:"roles,omitempty"`
+	ID              string                     `json:"id,omitempty"`
+	CreationDate    time.Time                  `json:"creation_date,omitempty"`
+	ChangeDate      time.Time                  `json:"change_date,omitempty"`
+	Sequence        uint64                     `json:"sequence,omitempty"`
+	Roles           database.TextArray[string] `json:"roles,omitempty"`
+	RoleInformation []Role                     `json:"-"`
 	// GrantID represents the project grant id
 	GrantID string                `json:"grant_id,omitempty"`
 	State   domain.UserGrantState `json:"state,omitempty"`
@@ -56,6 +59,12 @@ type UserGrant struct {
 	GrantedOrgDomain string `json:"granted_org_domain,omitempty"`
 }
 
+type Role struct {
+	Key         string `json:"role_key,omitempty"`
+	DisplayName string `json:"display_name,omitempty"`
+	GroupName   string `json:"group_name,omitempty"`
+}
+
 type UserGrants struct {
 	SearchResponse
 	UserGrants []*UserGrant
@@ -390,6 +399,7 @@ func prepareUserGrantQuery() (sq.SelectBuilder, func(*sql.Row) (*UserGrant, erro
 			UserGrantSequence.identifier(),
 			UserGrantGrantID.identifier(),
 			UserGrantRoles.identifier(),
+			"roles.role_information",
 			UserGrantState.identifier(),
 
 			UserGrantUserID.identifier(),
@@ -426,6 +436,7 @@ func prepareUserGrantQuery() (sq.SelectBuilder, func(*sql.Row) (*UserGrant, erro
 			LeftJoin(join(ProjectGrantColumnGrantID, UserGrantGrantID) + " AND " + ProjectGrantColumnProjectID.identifier() + " = " + UserGrantProjectID.identifier()).
 			LeftJoin(join(GrantedOrgColumnId, ProjectGrantColumnGrantedOrgID)).
 			LeftJoin(join(LoginNameUserIDCol, UserGrantUserID)).
+			LeftJoin("LATERAL (" + rolesInfoQuery + ") as roles ON true").
 			Where(
 				sq.Eq{LoginNameIsPrimaryCol.identifier(): true},
 			).PlaceholderFormat(sq.Dollar),
@@ -433,6 +444,8 @@ func prepareUserGrantQuery() (sq.SelectBuilder, func(*sql.Row) (*UserGrant, erro
 			g := new(UserGrant)
 
 			var (
+				roles []byte
+
 				username           sql.NullString
 				firstName          sql.NullString
 				userType           sql.NullInt32
@@ -463,6 +476,7 @@ func prepareUserGrantQuery() (sq.SelectBuilder, func(*sql.Row) (*UserGrant, erro
 				&g.Sequence,
 				&g.GrantID,
 				&g.Roles,
+				&roles,
 				&g.State,
 
 				&g.UserID,
@@ -496,6 +510,12 @@ func prepareUserGrantQuery() (sq.SelectBuilder, func(*sql.Row) (*UserGrant, erro
 				}
 				return nil, zerrors.ThrowInternal(err, "QUERY-oQPcP", "Errors.Internal")
 			}
+			if len(roles) > 0 {
+				err = json.Unmarshal(roles, &g.RoleInformation)
+				if err != nil {
+					return nil, err
+				}
+			}
 
 			g.Username = username.String
 			g.UserType = domain.UserType(userType.Int32)
@@ -527,6 +547,7 @@ func prepareUserGrantsQuery() (sq.SelectBuilder, func(*sql.Rows) (*UserGrants, e
 			UserGrantSequence.identifier(),
 			UserGrantGrantID.identifier(),
 			UserGrantRoles.identifier(),
+			"roles.role_information",
 			UserGrantState.identifier(),
 
 			UserGrantUserID.identifier(),
@@ -565,6 +586,7 @@ func prepareUserGrantsQuery() (sq.SelectBuilder, func(*sql.Rows) (*UserGrants, e
 			LeftJoin(join(ProjectGrantColumnGrantID, UserGrantGrantID) + " AND " + ProjectGrantColumnProjectID.identifier() + " = " + UserGrantProjectID.identifier()).
 			LeftJoin(join(GrantedOrgColumnId, ProjectGrantColumnGrantedOrgID)).
 			LeftJoin(join(LoginNameUserIDCol, UserGrantUserID)).
+			LeftJoin("LATERAL (" + rolesInfoQuery + ") as roles ON true").
 			Where(
 				sq.Eq{LoginNameIsPrimaryCol.identifier(): true},
 			).PlaceholderFormat(sq.Dollar),
@@ -575,6 +597,8 @@ func prepareUserGrantsQuery() (sq.SelectBuilder, func(*sql.Rows) (*UserGrants, e
 				g := new(UserGrant)
 
 				var (
+					roles []byte
+
 					username           sql.NullString
 					userType           sql.NullInt32
 					userOwner          sql.NullString
@@ -605,6 +629,7 @@ func prepareUserGrantsQuery() (sq.SelectBuilder, func(*sql.Rows) (*UserGrants, e
 					&g.Sequence,
 					&g.GrantID,
 					&g.Roles,
+					&roles,
 					&g.State,
 
 					&g.UserID,
@@ -637,6 +662,12 @@ func prepareUserGrantsQuery() (sq.SelectBuilder, func(*sql.Rows) (*UserGrants, e
 				if err != nil {
 					return nil, err
 				}
+				if len(roles) > 0 {
+					err = json.Unmarshal(roles, &g.RoleInformation)
+					if err != nil {
+						return nil, err
+					}
+				}
 
 				g.Username = username.String
 				g.UserType = domain.UserType(userType.Int32)
@@ -672,3 +703,21 @@ func prepareUserGrantsQuery() (sq.SelectBuilder, func(*sql.Rows) (*UserGrants, e
 			}, nil
 		}
 }
+
+var rolesInfoQuery = fmt.Sprintf(
+	`SELECT JSON_AGG(
+                 JSON_BUILD_OBJECT(
+                     'role_key', pr.role_key,
+                     'display_name', pr.display_name,
+                     'group_name', pr.group_name
+                 )
+             ) as role_information
+			 FROM %[1]s pr
+			 WHERE pr.instance_id = %[2]s
+			   AND pr.project_id = %[3]s
+			   AND pr.role_key = ANY(%[4]s)`,
+	projectRolesTable.identifier(),
+	UserGrantInstanceID.identifier(),
+	UserGrantProjectID.identifier(),
+	UserGrantRoles.identifier(),
+)

internal/query/user_grant_test.go

@@ -21,6 +21,7 @@ var (
 			", projections.user_grants5.sequence" +
 			", projections.user_grants5.grant_id" +
 			", projections.user_grants5.roles" +
+			", roles.role_information" +
 			", projections.user_grants5.state" +
 			", projections.user_grants5.user_id" +
 			", projections.users14.username" +
@@ -52,6 +53,7 @@ var (
 			" LEFT JOIN projections.project_grants4 ON projections.user_grants5.grant_id = projections.project_grants4.grant_id AND projections.user_grants5.instance_id = projections.project_grants4.instance_id AND projections.project_grants4.project_id = projections.user_grants5.project_id" +
 			" LEFT JOIN projections.orgs1 AS granted_orgs ON projections.project_grants4.granted_org_id = granted_orgs.id AND projections.project_grants4.instance_id = granted_orgs.instance_id" +
 			" LEFT JOIN projections.login_names3 ON projections.user_grants5.user_id = projections.login_names3.user_id AND projections.user_grants5.instance_id = projections.login_names3.instance_id" +
+			" LEFT JOIN LATERAL (SELECT JSON_AGG( JSON_BUILD_OBJECT( 'role_key', pr.role_key, 'display_name', pr.display_name, 'group_name', pr.group_name ) ) as role_information FROM projections.project_roles4 pr WHERE pr.instance_id = projections.user_grants5.instance_id AND pr.project_id = projections.user_grants5.project_id AND pr.role_key = ANY(projections.user_grants5.roles)) as roles ON true " +
 			" WHERE projections.login_names3.is_primary = $1")
 	userGrantCols = []string{
 		"id",
@@ -60,6 +62,7 @@ var (
 		"sequence",
 		"grant_id",
 		"roles",
+		"role_information",
 		"state",
 		"user_id",
 		"username",
@@ -90,6 +93,7 @@ var (
 			", projections.user_grants5.sequence" +
 			", projections.user_grants5.grant_id" +
 			", projections.user_grants5.roles" +
+			", roles.role_information" +
 			", projections.user_grants5.state" +
 			", projections.user_grants5.user_id" +
 			", projections.users14.username" +
@@ -122,6 +126,7 @@ var (
 			" LEFT JOIN projections.project_grants4 ON projections.user_grants5.grant_id = projections.project_grants4.grant_id AND projections.user_grants5.instance_id = projections.project_grants4.instance_id AND projections.project_grants4.project_id = projections.user_grants5.project_id" +
 			" LEFT JOIN projections.orgs1 AS granted_orgs ON projections.project_grants4.granted_org_id = granted_orgs.id AND projections.project_grants4.instance_id = granted_orgs.instance_id" +
 			" LEFT JOIN projections.login_names3 ON projections.user_grants5.user_id = projections.login_names3.user_id AND projections.user_grants5.instance_id = projections.login_names3.instance_id" +
+			" LEFT JOIN LATERAL (SELECT JSON_AGG( JSON_BUILD_OBJECT( 'role_key', pr.role_key, 'display_name', pr.display_name, 'group_name', pr.group_name ) ) as role_information FROM projections.project_roles4 pr WHERE pr.instance_id = projections.user_grants5.instance_id AND pr.project_id = projections.user_grants5.project_id AND pr.role_key = ANY(projections.user_grants5.roles)) as roles ON true " +
 			" WHERE projections.login_names3.is_primary = $1")
 	userGrantsCols = append(
 		userGrantCols,
@@ -172,6 +177,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 						20211111,
 						"grant-id",
 						database.TextArray[string]{"role-key"},
+						`[{"display_name":"displayName","group_name":"groupName","role_key":"role-key"}]`,
 						domain.UserGrantStateActive,
 						"user-id",
 						"username",
@@ -203,6 +209,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 				ChangeDate:              testNow,
 				Sequence:                20211111,
 				Roles:                   database.TextArray[string]{"role-key"},
+				RoleInformation:         []Role{{Key: "role-key", DisplayName: "displayName", GroupName: "groupName"}},
 				GrantID:                 "grant-id",
 				State:                   domain.UserGrantStateActive,
 				UserID:                  "user-id",
@@ -242,6 +249,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 						20211111,
 						"grant-id",
 						database.TextArray[string]{"role-key"},
+						`[{"display_name":"displayName","group_name":"groupName","role_key":"role-key"}]`,
 						domain.UserGrantStateActive,
 						"user-id",
 						"username",
@@ -273,6 +281,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 				ChangeDate:              testNow,
 				Sequence:                20211111,
 				Roles:                   database.TextArray[string]{"role-key"},
+				RoleInformation:         []Role{{Key: "role-key", DisplayName: "displayName", GroupName: "groupName"}},
 				GrantID:                 "grant-id",
 				State:                   domain.UserGrantStateActive,
 				UserID:                  "user-id",
@@ -312,6 +321,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 						20211111,
 						"grant-id",
 						database.TextArray[string]{"role-key"},
+						`[{"display_name":"displayName","group_name":"groupName","role_key":"role-key"}]`,
 						domain.UserGrantStateActive,
 						"user-id",
 						"username",
@@ -343,6 +353,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 				ChangeDate:              testNow,
 				Sequence:                20211111,
 				Roles:                   database.TextArray[string]{"role-key"},
+				RoleInformation:         []Role{{Key: "role-key", DisplayName: "displayName", GroupName: "groupName"}},
 				GrantID:                 "grant-id",
 				State:                   domain.UserGrantStateActive,
 				UserID:                  "user-id",
@@ -382,6 +393,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 						20211111,
 						"grant-id",
 						database.TextArray[string]{"role-key"},
+						`[{"display_name":"displayName","group_name":"groupName","role_key":"role-key"}]`,
 						domain.UserGrantStateActive,
 						"user-id",
 						"username",
@@ -413,6 +425,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 				ChangeDate:              testNow,
 				Sequence:                20211111,
 				Roles:                   database.TextArray[string]{"role-key"},
+				RoleInformation:         []Role{{Key: "role-key", DisplayName: "displayName", GroupName: "groupName"}},
 				GrantID:                 "grant-id",
 				State:                   domain.UserGrantStateActive,
 				UserID:                  "user-id",
@@ -452,6 +465,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 						20211111,
 						"grant-id",
 						database.TextArray[string]{"role-key"},
+						`[{"display_name":"displayName","group_name":"groupName","role_key":"role-key"}]`,
 						domain.UserGrantStateActive,
 						"user-id",
 						"username",
@@ -483,6 +497,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 				ChangeDate:              testNow,
 				Sequence:                20211111,
 				Roles:                   database.TextArray[string]{"role-key"},
+				RoleInformation:         []Role{{Key: "role-key", DisplayName: "displayName", GroupName: "groupName"}},
 				GrantID:                 "grant-id",
 				State:                   domain.UserGrantStateActive,
 				UserID:                  "user-id",
@@ -552,6 +567,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 							20211111,
 							"grant-id",
 							database.TextArray[string]{"role-key"},
+							`[{"display_name":"displayName","group_name":"groupName","role_key":"role-key"}]`,
 							domain.UserGrantStateActive,
 							"user-id",
 							"username",
@@ -589,6 +605,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 						ChangeDate:              testNow,
 						Sequence:                20211111,
 						Roles:                   database.TextArray[string]{"role-key"},
+						RoleInformation:         []Role{{Key: "role-key", DisplayName: "displayName", GroupName: "groupName"}},
 						GrantID:                 "grant-id",
 						State:                   domain.UserGrantStateActive,
 						UserID:                  "user-id",
@@ -631,6 +648,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 							20211111,
 							"grant-id",
 							database.TextArray[string]{"role-key"},
+							`[{"display_name":"displayName","group_name":"groupName","role_key":"role-key"}]`,
 							domain.UserGrantStateActive,
 							"user-id",
 							"username",
@@ -668,6 +686,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 						ChangeDate:              testNow,
 						Sequence:                20211111,
 						Roles:                   database.TextArray[string]{"role-key"},
+						RoleInformation:         []Role{{Key: "role-key", DisplayName: "displayName", GroupName: "groupName"}},
 						GrantID:                 "grant-id",
 						State:                   domain.UserGrantStateActive,
 						UserID:                  "user-id",
@@ -710,6 +729,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 							20211111,
 							"grant-id",
 							database.TextArray[string]{"role-key"},
+							`[{"display_name":"displayName","group_name":"groupName","role_key":"role-key"}]`,
 							domain.UserGrantStateActive,
 							"user-id",
 							"username",
@@ -747,6 +767,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 						ChangeDate:              testNow,
 						Sequence:                20211111,
 						Roles:                   database.TextArray[string]{"role-key"},
+						RoleInformation:         []Role{{Key: "role-key", DisplayName: "displayName", GroupName: "groupName"}},
 						GrantID:                 "grant-id",
 						State:                   domain.UserGrantStateActive,
 						UserID:                  "user-id",
@@ -789,6 +810,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 							20211111,
 							"grant-id",
 							database.TextArray[string]{"role-key"},
+							`[{"display_name":"displayName","group_name":"groupName","role_key":"role-key"}]`,
 							domain.UserGrantStateActive,
 							"user-id",
 							"username",
@@ -826,6 +848,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 						ChangeDate:              testNow,
 						Sequence:                20211111,
 						Roles:                   database.TextArray[string]{"role-key"},
+						RoleInformation:         []Role{{Key: "role-key", DisplayName: "displayName", GroupName: "groupName"}},
 						GrantID:                 "grant-id",
 						State:                   domain.UserGrantStateActive,
 						UserID:                  "user-id",
@@ -868,6 +891,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 							20211111,
 							"grant-id",
 							database.TextArray[string]{"role-key"},
+							`[{"display_name":"displayName","group_name":"groupName","role_key":"role-key"}]`,
 							domain.UserGrantStateActive,
 							"user-id",
 							"username",
@@ -905,6 +929,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 						ChangeDate:              testNow,
 						Sequence:                20211111,
 						Roles:                   database.TextArray[string]{"role-key"},
+						RoleInformation:         []Role{{Key: "role-key", DisplayName: "displayName", GroupName: "groupName"}},
 						GrantID:                 "grant-id",
 						State:                   domain.UserGrantStateActive,
 						UserID:                  "user-id",
@@ -947,6 +972,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 							20211111,
 							"grant-id",
 							database.TextArray[string]{"role-key"},
+							`[{"display_name":"displayName","group_name":"groupName","role_key":"role-key"}]`,
 							domain.UserGrantStateActive,
 							"user-id",
 							"username",
@@ -977,6 +1003,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 							20211111,
 							"grant-id",
 							database.TextArray[string]{"role-key"},
+							`[{"display_name":"displayName","group_name":"groupName","role_key":"role-key"}]`,
 							domain.UserGrantStateActive,
 							"user-id",
 							"username",
@@ -1014,6 +1041,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 						ChangeDate:              testNow,
 						Sequence:                20211111,
 						Roles:                   database.TextArray[string]{"role-key"},
+						RoleInformation:         []Role{{Key: "role-key", DisplayName: "displayName", GroupName: "groupName"}},
 						GrantID:                 "grant-id",
 						State:                   domain.UserGrantStateActive,
 						UserID:                  "user-id",
@@ -1044,6 +1072,7 @@ func Test_UserGrantPrepares(t *testing.T) {
 						ChangeDate:              testNow,
 						Sequence:                20211111,
 						Roles:                   database.TextArray[string]{"role-key"},
+						RoleInformation:         []Role{{Key: "role-key", DisplayName: "displayName", GroupName: "groupName"}},
 						GrantID:                 "grant-id",
 						State:                   domain.UserGrantStateActive,
 						UserID:                  "user-id",