Oauth scope (#363)

* feat: support configuration of OAuth `scope`

Related to camunda/camunda-modeler#4102

Implements camunda/camunda-8-js-sdk#21

* chore(types): `ZClientOptions#hostname` can be null

Returned internally as `null`.

* test: rewrite test cleanup

Ensures we properly clean up after each test,
also in cases of test failures.

* Small tweaks

* update CHANGELOG

---------

Co-authored-by: Josh Wulf <[email protected]>

CHANGELOG.md

@@ -1,3 +1,11 @@
+# 8.3.2
+
+## New Features
+
+_New shiny stuff_
+
+-   Added support for providing a value for a `scope` field in the OAuth request. This can be set with environment variable `ZEEBE_TOKEN_SCOPE`, or by passing a `scope` field as part of the `oAuth` config options for a `ZBClient`. This is needed to support OIDC / EntraID. Thanks to [@nikku](https://github.com/nikku) for the implementation. See PR [#363](https://github.com/camunda-community-hub/zeebe-client-node-js/pull/363) for more details.
+
 # 8.3.1
 
 ## New Features

README.md

@@ -485,6 +485,7 @@ const zbc = new ZBClient("my-secure-broker.io:443", {
 	oAuth: {
 		url: "https://your-auth-endpoint/oauth/token",
 		audience: "my-secure-broker.io",
+        scope: "myScope",
 		clientId: "myClientId",
 		clientSecret: "randomClientSecret",
 		customRootCert: fs.readFileSync('./my_CA.pem'),
@@ -599,6 +600,7 @@ Self-hosted or local broker with OAuth + TLS:
 ZEEBE_CLIENT_ID
 ZEEBE_CLIENT_SECRET
 ZEEBE_TOKEN_AUDIENCE
+ZEEBE_TOKEN_SCOPE
 ZEEBE_AUTHORIZATION_SERVER_URL
 ZEEBE_ADDRESS
 ```
@@ -613,6 +615,7 @@ ZEEBE_CLIENT_ID='zeebe'
 ZEEBE_CLIENT_SECRET='zecret'
 ZEEBE_AUTHORIZATION_SERVER_URL='http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token'
 ZEEBE_TOKEN_AUDIENCE='zeebe.camunda.io'
+ZEEBE_TOKEN_SCOPE='not needed'
 CAMUNDA_CREDENTIALS_SCOPES='Zeebe'
 CAMUNDA_OAUTH_URL='http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token'
 ```

package.json

@@ -83,7 +83,7 @@
 		"@types/debug": "0.0.31",
 		"@types/got": "^9.6.9",
 		"@types/jest": "^27.5.2",
-		"@types/node": "^10.17.60",
+		"@types/node": "^14.17.1",
 		"@types/promise-retry": "^1.1.3",
 		"@types/stack-trace": "0.0.29",
 		"@types/uuid": "^3.4.4",
@@ -105,7 +105,7 @@
 		"tslint": "^6.1.3",
 		"tslint-config-prettier": "^1.18.0",
 		"typedoc": "^0.21.10",
-		"typescript": "^4.2.0"
+		"typescript": "^4.4.4"
 	},
 	"author": {
 		"name": "Josh Wulf",

src/__tests__/ConfigurationHydrator.spec.ts

@@ -13,14 +13,16 @@ const ENV_VARS_TO_STORE = [
 	'ZEEBE_GATEWAY_ADDRESS',
 	'ZEEBE_ADDRESS',
 	'ZEEBE_TOKEN_AUDIENCE',
+	'ZEEBE_TOKEN_SCOPE',
 	'ZEEBE_AUTHORIZATION_SERVER_URL',
 	'ZEEBE_CLIENT_MAX_RETRIES',
 	'ZEEBE_CLIENT_RETRY',
 	'ZEEBE_CLIENT_MAX_RETRY_TIMEOUT',
 	'ZEEBE_CLIENT_SSL_ROOT_CERTS_PATH',
 	'ZEEBE_CLIENT_SSL_PRIVATE_KEY_PATH',
 	'ZEEBE_CLIENT_SSL_CERT_CHAIN_PATH',
-	'ZEEBE_TENANT_ID'
+	'ZEEBE_TENANT_ID',
+	'ZEEBE_SECURE_CONNECTION',
 ]
 
 beforeAll(() => {
@@ -96,6 +98,29 @@ test('Takes an explicit Gateway address over the environment ZEEBE_GATEWAY_ADDRE
 	expect(conf.port).toBe('26600')
 })
 
+/**
+ * Self-managed
+ */
+test('Constructs the self-managed connection with oauth credentials', () => {
+	process.env.ZEEBE_CLIENT_SECRET = 'CLIENT_SECRET'
+	process.env.ZEEBE_CLIENT_ID = 'CLIENT_ID'
+	process.env.ZEEBE_GATEWAY_ADDRESS = 'zeebe://my-server:26600'
+	process.env.ZEEBE_TOKEN_AUDIENCE = 'TOKEN_AUDIENCE'
+	process.env.ZEEBE_TOKEN_SCOPE = 'TOKEN_SCOPE'
+	process.env.ZEEBE_AUTHORIZATION_SERVER_URL = 'https://auz'
+
+	const conf = ConfigurationHydrator.configure(undefined, undefined)
+
+	expect(conf.hostname).toBe('my-server')
+	expect(conf.port).toBe('26600')
+	expect(conf.oAuth!.audience).toBe('TOKEN_AUDIENCE')
+	expect(conf.oAuth!.scope).toBe('TOKEN_SCOPE')
+	expect(conf.oAuth!.clientId).toBe('CLIENT_ID')
+	expect(conf.oAuth!.audience).toBe('TOKEN_AUDIENCE')
+	expect(conf.oAuth!.clientSecret).toBe('CLIENT_SECRET')
+	expect(conf.oAuth!.url).toBe('https://auz')
+})
+
 /**
  * Camunda Cloud
  */
@@ -105,7 +130,13 @@ test('Constructs the Camunda Cloud connection from the environment with clusterI
 	process.env.ZEEBE_CLIENT_SECRET =
 		'WZahIGHjyj0-oQ7DZ_aH2wwNuZt5O8Sq0ZJTz0OaxfO7D6jaDBZxM_Q-BHRsiGO_'
 	process.env.ZEEBE_CLIENT_ID = 'yStuGvJ6a1RQhy8DQpeXJ80yEpar3pXh'
+
 	delete process.env.ZEEBE_GATEWAY_ADDRESS
+	delete process.env.ZEEBE_TOKEN_AUDIENCE
+	delete process.env.ZEEBE_TOKEN_SCOPE
+	delete process.env.ZEEBE_AUTHORIZATION_SERVER_URL
+	delete process.env.ZEEBE_GATEWAY_ADDRESS
+
 	// process.env.ZEEBE_GATEWAY_ADDRESS = 'zeebe://localhost:26500'
 	const conf = ConfigurationHydrator.configure(undefined, undefined)
 	expect(conf.hostname).toBe(
@@ -447,7 +478,7 @@ describe('Configures secure connection with custom root certs', () => {
 })
 
 test('Is insecure by default', () => {
-	delete process.env.ZEEBE_INSECURE_CONNECTION
+	delete process.env.ZEEBE_SECURE_CONNECTION
 	const conf = ConfigurationHydrator.configure('localhost:26600', {})
 	expect(conf.useTLS).toBeFalsy()
 })
@@ -526,13 +557,17 @@ test('Tenant ID is picked up from environment', () => {
 })
 
 test('Tenant ID is picked up from constructor options', () => {
-	const conf = ConfigurationHydrator.configure(undefined, {tenantId: 'thisOne'})
+	const conf = ConfigurationHydrator.configure(undefined, {
+		tenantId: 'thisOne',
+	})
 	expect(conf.tenantId).toBe('thisOne')
 })
 
 test('Tenant ID from constructor overrides environment', () => {
 	process.env.ZEEBE_TENANT_ID = 'someId'
-	const conf = ConfigurationHydrator.configure(undefined, {tenantId: 'thisOne'})
+	const conf = ConfigurationHydrator.configure(undefined, {
+		tenantId: 'thisOne',
+	})
 	expect(conf.tenantId).toBe('thisOne')
 })