feat(uma): Add support for User-Managed Access

Author: anonrig

package.json

@@ -41,6 +41,7 @@
     "@nestjs/common": "^7.1.3"
   },
   "dependencies": {
+    "axios": "^0.19.2",
     "keycloak-admin": "^1.13.0",
     "openid-client": "^3.15.2",
     "reflect-metadata": "^0.1.13",

readme.md

@@ -1,25 +1,51 @@
-### Keycloak Admin Client for NestJs
+## Keycloak Admin Client for NestJs
 
 Install using `npm i --save nestjs-keycloak-admin` or `yarn add nestjs-keycloak-admin`
 
 Then on your app.module.ts
 
-```javascript
+```typescript
   @Module({
-    KeycloakAdminModule.registerAsync({
-      imports: [ConfigModule],
-      useFactory: async () => ({
-        config: {
-          baseUrl: 'https://relevantfruit.com/auth',
-          realmName: 'relevant-fruit',
-          jwtIssuer: 'https://relevantfruit.com/auth/realms/relevant-fruit'
-        },
-        credentials: {
-          clientId: 'batman',
-          clientSecret: 'batman-is-cool'
-        }
+    imports: [
+      KeycloakAdminModule.registerAsync({
+        imports: [ConfigModule],
+        useFactory: async () => ({
+          config: {
+            baseUrl: 'https://relevantfruit.com/auth',
+            realmName: 'relevant-fruit',
+            jwtIssuer: 'https://relevantfruit.com/auth/realms/relevant-fruit'
+          },
+          credentials: {
+            clientId: 'batman',
+            clientSecret: 'batman-is-cool'
+          }
+        }),
+        inject: [ConfigService]
       }),
-      inject: [ConfigService]
-    }),
+    ]
   })
 ```
+
+### UMA Support
+
+By default nestjs-keycloak-admin supports User Managed Access for managing your resources.
+
+```typescript
+class Organization() {
+  constructor(private readonly adminProvider: KeycloakAdminService) {}
+
+  async findAll(): UMAResource[] {
+    return this.adminProvider.resourceManager.findAll()
+  }
+
+  async create(payload: payload): Promise<UMAResource> {
+    const resource = new UMAResource(payload)
+      .setOwner(1)
+      .addScope('organization:create')
+      .setType('organization')
+      .setUri('/organization/123')
+
+    return this.adminProvider.create(resource)
+  }
+}
+```

src/interfaces.ts

@@ -28,3 +28,19 @@ export interface KeycloakAdminOptions {
   config: KeycloakAdminConfig;
   credentials: Credentials;
 }
+
+export interface UMAScopeOptions {
+  name: string;
+  id?: string;
+  iconUri?: string;
+}
+
+export interface UMAResourceOptions {
+  name: string;
+  id?: string;
+  uri?: string;
+  type?: string;
+  iconUri?: string;
+  owner?: string;
+  scopes?: string[] | UMAScopeOptions[];
+}

src/lib/request-manager.ts

@@ -0,0 +1,50 @@
+import Axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios';
+import { KeycloakAdminService } from '../service';
+
+export class RequestManager {
+  private requester: AxiosInstance;
+  private readonly client: KeycloakAdminService;
+
+  constructor(client: KeycloakAdminService) {
+    this.client = client;
+
+    const { baseUrl, realmName } = this.client.options.config;
+    this.requester = Axios.create({
+      baseURL: `${baseUrl}/auth/realms/${realmName}`,
+    });
+
+    this.requester.interceptors.request.use(async (config) => {
+      const tokenSet = await this.client.refreshGrant();
+      config.headers.authorization = `Bearer ${tokenSet.access_token}`;
+      return config;
+    });
+  }
+
+  async get<T>(...args: [string, (AxiosRequestConfig | undefined)?]) {
+    return this.requester.get.apply<any, any, Promise<AxiosResponse<T>>>(
+      null,
+      args,
+    );
+  }
+
+  async post<T>(...args: [string, any?, (AxiosRequestConfig | undefined)?]) {
+    return this.requester.post.apply<any, any, Promise<AxiosResponse<T>>>(
+      null,
+      args,
+    );
+  }
+
+  async put<T>(...args: [string, any?, (AxiosRequestConfig | undefined)?]) {
+    return this.requester.put.apply<any, any, Promise<AxiosResponse<T>>>(
+      null,
+      args,
+    );
+  }
+
+  async delete<T>(...args: [string, (AxiosRequestConfig | undefined)?]) {
+    return this.requester.delete.apply<any, any, Promise<AxiosResponse<T>>>(
+      null,
+      args,
+    );
+  }
+}

src/lib/resource-manager.ts

@@ -0,0 +1,67 @@
+import { UMAResourceOptions } from '../interfaces';
+import { KeycloakAdminService } from '../service';
+import { UMAResource } from '../uma/resource';
+import { RequestManager } from './request-manager';
+
+export class ResourceManager {
+  private readonly requestManager: RequestManager;
+
+  constructor(client: KeycloakAdminService) {
+    this.requestManager = new RequestManager(client);
+  }
+
+  async create(resource: UMAResource): Promise<UMAResource> {
+    const { data } = await this.requestManager.post<UMAResourceOptions>(
+      '/authz/protection/resource_set',
+      resource.toJson(),
+    );
+
+    if (data.id) {
+      resource.setId(data.id);
+    }
+
+    return resource;
+  }
+
+  async update(resource: UMAResource): Promise<UMAResource> {
+    const { id } = resource.toJson();
+
+    if (!id) throw new Error(`Id is missing from resource`);
+
+    await this.requestManager.put<any>(
+      `/authz/protection/resource_set/${id}`,
+      resource.toJson(),
+    );
+    return resource;
+  }
+
+  async delete(resource: UMAResource): Promise<void> {
+    const { id } = resource.toJson();
+
+    if (!id) throw new Error(`Id is missing from resource`);
+
+    await this.requestManager.delete<any>(
+      `/authz/protection/resource_set/${id}`,
+    );
+  }
+
+  async findById(id: string): Promise<UMAResource | null> {
+    const { data } = await this.requestManager.get<UMAResourceOptions>(
+      `/authz/protection/resource_set/${id}`,
+    );
+
+    return data && new UMAResource(data);
+  }
+
+  async findAll(deep: Boolean = false): Promise<UMAResource[] | any> {
+    const { data } = await this.requestManager.get<string[]>(
+      `/authz/protection/resource_set`,
+    );
+
+    if (deep) {
+      return data;
+    }
+
+    return Promise.all(data.map((id) => this.findById(id)));
+  }
+}

src/service.ts

@@ -1,20 +1,22 @@
 import { Logger } from '@nestjs/common';
 import AdminClient from 'keycloak-admin';
-import { Client, GrantBody, Issuer, TokenSet } from 'openid-client';
+import { Client, Issuer, TokenSet } from 'openid-client';
 import { KeycloakAdminOptions } from './interfaces';
+import { ResourceManager } from './lib/resource-manager';
 
 export class KeycloakAdminService {
   private logger = new Logger(KeycloakAdminService.name);
 
-  private options: KeycloakAdminOptions;
-  private client: AdminClient;
-  private tokenSet: TokenSet | null | undefined;
-  private issuerClient: Client | null | undefined;
-  private connectionConfig: GrantBody & any;
+  public readonly options: KeycloakAdminOptions;
+  private tokenSet?: TokenSet;
+  private issuerClient?: Client;
+  public resourceManager: ResourceManager;
+  public client: AdminClient;
 
   constructor(options: KeycloakAdminOptions) {
     this.options = options;
     this.client = new AdminClient(options.config);
+    this.resourceManager = new ResourceManager(this);
     this.initConnection();
   }
 
@@ -27,9 +29,6 @@ export class KeycloakAdminService {
       grantType: 'client_credentials',
     } as any);
 
-    if (!this.options.config.baseUrl) {
-      throw new Error(`Base url is missing from options.`);
-    }
     const keycloakIssuer = await Issuer.discover(this.options.config.jwtIssuer);
 
     this.issuerClient = new keycloakIssuer.Client({
@@ -46,46 +45,20 @@ export class KeycloakAdminService {
     this.logger.log(
       `Initial token expires at ${new Date(this.tokenSet.expires_at!)}`,
     );
-
-    this.initRefresh();
   }
 
-  async initRefresh() {
-    // Periodically using refresh_token grant flow to get new access token here
-    // TODO: it will be better to check for token expiration instead of interval check
-    setInterval(async () => {
-      const tokenSet = this.tokenSet;
-
-      if (!tokenSet || !tokenSet?.refresh_token) {
-        return this.logger.warn(
-          'Refresh token is missing. Refresh doesnt work.',
-        );
-      }
+  async refreshGrant(): Promise<TokenSet> {
+    if (this.tokenSet && !this.tokenSet.expired()) {
+      return this.tokenSet;
+    }
 
-      if (!tokenSet.expired()) {
-        return this.logger.verbose(`Omitting refreshing of Keycloak token.`);
-      }
+    this.logger.verbose(`Grant token expired, refreshing.`);
 
-      try {
-        this.tokenSet = await this.issuerClient?.refresh(
-          tokenSet.refresh_token,
-        );
-        this.logger.log('Successfully refreshed token');
-      } catch (e) {
-        if (e.name === 'TimeoutError' || e?.error === 'invalid_grant') {
-          this.tokenSet = await this.issuerClient?.grant(this.connectionConfig);
-        } else {
-          this.logger.error(e);
-          throw e;
-        }
-      }
-      if (this.tokenSet?.access_token) {
-        this.client.setAccessToken(this.tokenSet.access_token);
-      }
-    }, 58 * 1000); // 58 seconds
-  }
+    this.tokenSet = await this.issuerClient?.refresh(
+      this.tokenSet!.refresh_token!,
+    );
 
-  getClient() {
-    return this.client;
+    this.client.setAccessToken(this.tokenSet!.access_token!);
+    return this.tokenSet!;
   }
 }

src/uma/resource.ts

@@ -0,0 +1,66 @@
+import { UMAResourceOptions, UMAScopeOptions } from '../interfaces';
+import { UMAScope } from './scope';
+
+export class UMAResource {
+  public options: UMAResourceOptions;
+  private scopes: UMAScope[] = [];
+  constructor(options: UMAResourceOptions) {
+    this.options = options;
+    this.setScopes(options.scopes);
+  }
+
+  setScopes(scopes: string[] | UMAScopeOptions[] = []): UMAResource {
+    scopes.forEach((scope: string | UMAScopeOptions) => {
+      if (typeof scope === 'string')
+        this.scopes.push(new UMAScope({ name: scope }));
+      if (typeof scope === 'object') this.scopes.push(new UMAScope(scope));
+    });
+    return this;
+  }
+
+  setName(name: string): UMAResource {
+    this.options.name = name;
+    return this;
+  }
+
+  setUri(uri: string): UMAResource {
+    this.options.uri = uri;
+    return this;
+  }
+
+  setType(type: string): UMAResource {
+    this.options.type = type;
+    return this;
+  }
+
+  setOwner(owner: string): UMAResource {
+    this.options.owner = owner;
+    return this;
+  }
+
+  setId(id: string): UMAResource {
+    this.options.id = id;
+    return this;
+  }
+
+  setIconUri(iconUri: string): UMAResource {
+    this.options.iconUri = iconUri;
+    return this;
+  }
+
+  toJson() {
+    return Object.assign({}, this.options, {
+      scopes: this.scopes.map((s) => s.toJson()),
+    });
+  }
+
+  isEqual(rawRhs: UMAResource): Boolean {
+    const rhs = rawRhs.toJson();
+    return (
+      rhs.name === this.options.name &&
+      rhs.id === this.options.id &&
+      rhs.iconUri === this.options.uri &&
+      rhs.type === this.options.type
+    );
+  }
+}

src/uma/scope.ts

@@ -0,0 +1,17 @@
+import { UMAScopeOptions } from '../interfaces';
+
+export class UMAScope {
+  private readonly options: UMAScopeOptions;
+
+  constructor(opts: UMAScopeOptions) {
+    this.options = opts;
+  }
+
+  isEqual(rhs: UMAScope) {
+    return this.toJson().name === rhs.toJson().name;
+  }
+
+  toJson() {
+    return this.options;
+  }
+}