Category: Backstage

Backstage by Spotify is a platform to build Dev Portal for your organisation. The tool provides a robust framework which can be used to customize and create a Dev Portal, custom fit – as I’d like to say 😉

The tool is evolving rapidly with new plugins/features being added quite often. Recently I worked to implement custom Authorization to access Backstage, which I found really interesting and thus am sharing my experience on how I did it.

We have Backstage hosted in K8s (EKS) with GitOps based deployments managed through ArgoCD. We also have Templates (with custom scaffolder actions) to provision new microservices. While setting up the AuthZ, granular access to these Templates was one of our requirements and we wanted to manage its access in a proper way.

Backstage has several AuthN integrations out of the box and it’s pretty easy to set that up. In our case we use OneLogin for AuthN. For AuthZ, Backstage provides a permissions plugin. I am not discussing how to configure and setup that up as it’s documented well.

An authenticated user gets allotted some default user groups. To have a proper group based AuthZ the first thing we did was to develop a custom sign-in resolver to set custom groups for authenticated users.

// auth.ts custom login snippet
onelogin: providers.onelogin.create({
        signIn: {
          // Custom sign-in resolver
          async resolver({ result }, ctx) {
            const email = result.fullProfile.username ?? '';
            const [id] = email.split('@');
            let entity:any;
 
            try {
              ({ entity } = await ctx.findCatalogUser({
                entityRef: {
                  kind: 'user', 
                  namespace: BACKSTAGE_NAMESPACE, 
                  name: id
                }
              }));      
            }
            catch (error)  {
              if(error instanceof NotFoundError){
                entity = {
                  kind: 'user',
                  namespace: BACKSTAGE_NAMESPACE,
                  name: id,
                };
              }
            }

            // Set default group ownerships
            const membershipRefs = entity.relations
              ?.filter(
                (r:any) => r.type === RELATION_MEMBER_OF && r.targetRef.startsWith('group:'),
              )
              .map((r:any) => r.targetRef) ?? [];

            const ownershipRefs:string[] = Array.from(new Set([`group:${BACKSTAGE_NAMESPACE}/default`, ...membershipRefs]));

            return ctx.issueToken({
              claims: {
                sub: stringifyEntityRef(entity),
                ent: ownershipRefs,
              },
            });
          },
        },
      }),

The above resolver adds default memberships as below:

1. If authenticated:
   • group:/backstage/default
   • Explicit groups set for the user entity, created in Backstage
2. If not authenticated (Guest): user:/default/guest

Our approach here is to manage the AuthZ from Backstage by creating the User/Group entities in Backstage and mapping the authenticated user to inherit these specified groups. To achieve this, there should be an identical id (which the user uses to authenticate) and the one created in Backstage. In the above example, this id is populated based on the user’s email, by using the part preceding @ of the email.

Thus we have users.yaml and groups.yaml which creates the users and groups at Backstage end, and maps groups with the user, like below:

apiVersion: backstage.io/v1alpha1
kind: User
metadata:
  namespace: backstage
  name: username.surname
spec:
  profile:
    displayName: Username Surname
  memberOf:
    - admin
    ...

apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
   namespace: backstage
   name: admin
spec:
   type: team
   profile:
      displayName: Admin
   children: []

Now that we have the Users and Groups ready with correct memberships defined, the next thing is to setup the permission policy.

As stated, we use a custom permission rule to provided access to Templates based on entity tags. (ABAC).

// permission-rule.ts snippet
// Custom permission rule to authorize based on entity tags
export const isGroupInTagRule = createCatalogPermissionRule({
  name: 'IS_GROUP_IN_TAG',
  description: 'Checks if an entity tag contains an user group, to allow access to the entity',
  resourceType: 'catalog-entity',
  apply: (resource: Entity, claims:string[]) => {
    if (!resource.metadata.tags) {
     return false;
    }
    return resource.metadata.tags
      .some(tag => claims.includes(`group:backstage/${tag.split(':')[1]}`))
  },
  toQuery: (claims:string[]) => ({
    key: 'metadata.tags',
    values: claims.map(group => `group:${group.split('/')[1]}`),
  }),
});

export const isGroupInTag = createConditionFactory(isGroupInTagRule);

You can refer the detailed process to define custom permission rules here, which will be required with the above change to make this work.

So the above permission rule now provides us with a isGroupInTagRule function that can be used in the permission policy to authorize entities based on tags.

Finally let’s have a look at the permission policy:

// permission.ts defining custom authZ policy
class CustomPermissionPolicy implements PermissionPolicy {
  async handle(request: PolicyQuery, user: BackstageIdentityResponse): Promise<PolicyDecision> {

    // Exempt admin from permission checks
    if (isAdmin(user)) {
      return { result: AuthorizeResult.ALLOW };
    }

    // RO permissions
    if (isPermission(request.permission, catalogEntityReadPermission)) {
      return createCatalogConditionalDecision(request.permission, {
        anyOf: [
          catalogConditions.isEntityKind([
            'Domain',
            'Component',
            'System',
            'API',
            'Group',
            'User',
            'Resource',
            'Location',
          ]),
          { // Template RO permission only to groups specified in tags
            allOf: [
              catalogConditions.isEntityKind(['Template']),
              isGroupInTag(
	            user?.identity.ownershipEntityRefs ?? [],
	          ),
            ],
          },
        ],
      });
    }

    // Deny explicit creat/delete permissions
    if (isPermission(request.permission, catalogEntityDeletePermission) || 
        isPermission(request.permission, catalogEntityCreatePermission)) {
      return { result: AuthorizeResult.DENY };
    }

    return { result: AuthorizeResult.ALLOW };
  }
}

// Function to check if user has admin group membership
const isAdmin = (user: BackstageIdentityResponse):boolean => {
  if (typeof(user) === 'object') {
    return user.identity.ownershipEntityRefs.includes('group:backstage/admin');
  }
  return false;
}

The above policy:

1. Allows full access to users with admin group membership
2. RO access to all entities (except Templates)
3. Read access to Templates to users with membership to groups specified in the Template tag

Here is how the Template definition snippet looks, which provides access to users only with the staff membership:

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: golden-path-template
  title: Golden Path Template
  description: Create a new microservice from scratch following the golden path
  tags:
    - recommended
    - microservice
    - "group:staff"
...

That’s all! This works perfectly, is scalable and achieves its purpose well. 🙂