Auth Sync App

Auth Sync App takes user group and "privilege information" from federated source systems to grant roles in target systems. The code is designed to support adding new sources and target systems.

Auth Sync App does not setup the source systems or the target systems. You are responsible for creating any required accounts and setting up access for the Auth Sync App in those systems.

Auth Sync App does not directly grant user access. Instead, clients of the target systems are configured independely of interpret the role themselves. An OIDC target, for example, will have roles added or removed and those roles granted to users by Auth Sync App. It is up to the application to interpret the roles a user is granted appropriately. The client (application) may have its own tool (like the Vault Sync App) for managing on the application side of interpreting the roles received from OIDC.

Supported Sources

Sources return a group of users for each role in the configuration.

Broker
Static files

Supported Targets

A target is kept in sync with the configured roles.

BC Gov Common Hosted Single Sign-on (CSS)

The CSS target lets you sync the roles and role membership of an integration.

To use this target, you must have a CSS API Account with access to the integration you want to manage.

See: CSS Documentation

GitHub

The GitHub target lets you sync teams and team membership to a GitHub organization.

To use this target, you must have a fine-grained PAT with read and write access to members in the organization.

Auth Sync App
Development
Usage
Commands

Running

The tool can be run from the source using Node.js or a container image by using Podman or Docker.

./bin/dev.js generate

podman run --rm ghcr.io/bcgov-nr/auth-sync-app:v1.0.0 generate

The sample command runs the generate command. All the commands will require authentication and configuration to function.

Workflows

The general pattern is to call the following commands:

generate - Create a configuration file from a template (if necessary)
role-sync - Sync roles to target system
member-sync - Sync membership in roles to target system

The monitor command can be used to automate running this workflow.

monitor

Authentication

It is recommended to set all confidential parameters (such as tokens and secrets) using environment variables instead of using arguments. As an example, the argument 'broker-token' should always be configured with the environment variable 'BROKER_TOKEN'.

These can be found by looking in the src/flags.ts file.

A sample env file is provided. To setup for running the tool using a local dev environment, run the following command:

source setenv-local.sh

Configuration

See: Development

Development

This document is aimed at developers looking to setup the Auth Sync Tool to run or make modifications to it.

See: Development

Usage

$ npm install -g authtool
$ authtool COMMAND
running command...
$ authtool (--version)
authtool/1.0.0 darwin-x64 node-v20.17.0
$ authtool --help [COMMAND]
USAGE
  $ authtool COMMAND
...

The script in /bin/run.js can also run the code without installing it.

$ ./bin/run.js COMMAND
running command...
$ ./bin/run.js (-v|--version|version)
...

Commands

authtool generate
authtool help [COMMAND]
authtool member-sync
authtool monitor
authtool role-sync

`authtool generate`

Generates configuration file from template.

USAGE
  $ authtool generate [-h] [--broker-api-url <value>] [--broker-token <value>] [--config-path <value>]
    [--source-broker-idp <value>] [--css-token-url <value>] [--css-client-id <value>] [--css-client-secret <value>]
    [--github-client-type <value>] [--github-app-id <value>] [--github-client-id <value>] [--github-client-secret
    <value>] [--github-private-key <value>] [--github-token <value>]

FLAGS
  -h, --help                          Show CLI help.
      --broker-api-url=<value>        [default: https://nr-broker.apps.silver.devops.gov.bc.ca/] The broker api base url
      --broker-token=<value>          The broker JWT
      --config-path=<value>           [default: ./config] The path to the config directory
      --css-client-id=<value>         [default: id] The css keycloak client id
      --css-client-secret=<value>     [default: password] The css keycloak client secret
      --css-token-url=<value>         [default: url] The css token url
      --github-app-id=<value>         [default: id] The GitHub app id
      --github-client-id=<value>      [default: id] The GitHub client id
      --github-client-secret=<value>  [default: password] The GitHub client secret
      --github-client-type=<value>    The GitHub client type
      --github-private-key=<value>    [default: key] The GitHub private key for signing requests
      --github-token=<value>          [default: token] A GitHub PAT
      --source-broker-idp=<value>     The idp to filter users to

DESCRIPTION
  Generates configuration file from template.

EXAMPLES
  $ authtool generate

`authtool help [COMMAND]`

Display help for authtool.

USAGE
  $ authtool help [COMMAND...] [-n]

ARGUMENTS
  COMMAND...  Command to show help for.

FLAGS
  -n, --nested-commands  Include all nested commands in the output.

DESCRIPTION
  Display help for authtool.

See code: @oclif/plugin-help

`authtool member-sync`

Syncs user and role configuration to CSS

USAGE
  $ authtool member-sync [-h] [--broker-api-url <value>] [--broker-token <value>] [--config-path <value>]
    [--notification-smtp-host <value>] [--notification-smtp-port <value>] [--notification-smtp-secure]
    [--notification-option-from <value>] [--notification-option-subject <value>] [--notification-option-template-text
    <value>] [--notification-option-template-html <value>] [--source-broker-idp <value>] [--css-token-url <value>]
    [--css-client-id <value>] [--css-client-secret <value>] [--github-client-type <value>] [--github-app-id <value>]
    [--github-client-id <value>] [--github-client-secret <value>] [--github-private-key <value>] [--github-token
    <value>]

FLAGS
  -h, --help                                       Show CLI help.
      --broker-api-url=<value>                     [default: https://nr-broker.apps.silver.devops.gov.bc.ca/] The broker
                                                   api base url
      --broker-token=<value>                       The broker JWT
      --config-path=<value>                        [default: ./config] The path to the config directory
      --css-client-id=<value>                      [default: id] The css keycloak client id
      --css-client-secret=<value>                  [default: password] The css keycloak client secret
      --css-token-url=<value>                      [default: url] The css token url
      --github-app-id=<value>                      [default: id] The GitHub app id
      --github-client-id=<value>                   [default: id] The GitHub client id
      --github-client-secret=<value>               [default: password] The GitHub client secret
      --github-client-type=<value>                 The GitHub client type
      --github-private-key=<value>                 [default: key] The GitHub private key for signing requests
      --github-token=<value>                       [default: token] A GitHub PAT
      --notification-option-from=<value>           The notification from address
      --notification-option-subject=<value>        [default: Your Access Report (authtool)] The notification subject
      --notification-option-template-html=<value>  The notification template in html
      --notification-option-template-text=<value>  The notification template in text
      --notification-smtp-host=<value>             The SMTP Host
      --notification-smtp-port=<value>             The SMTP port
      --notification-smtp-secure                   The SMTP secure flag
      --source-broker-idp=<value>                  The idp to filter users to

DESCRIPTION
  Syncs user and role configuration to CSS

EXAMPLES
  $ authtool member-sync

`authtool monitor`

Monitor for auth changes to sync

USAGE
  $ authtool monitor [-h] [--broker-api-url <value>] [--broker-token <value>] [--config-path <value>]
    [--notification-smtp-host <value>] [--notification-smtp-port <value>] [--notification-smtp-secure]
    [--notification-option-from <value>] [--notification-option-subject <value>] [--notification-option-template-text
    <value>] [--notification-option-template-html <value>] [--source-broker-idp <value>] [--css-token-url <value>]
    [--css-client-id <value>] [--css-client-secret <value>] [--github-client-type <value>] [--github-app-id <value>]
    [--github-client-id <value>] [--github-client-secret <value>] [--github-private-key <value>] [--github-token
    <value>]

FLAGS
  -h, --help                                       Show CLI help.
      --broker-api-url=<value>                     [default: https://nr-broker.apps.silver.devops.gov.bc.ca/] The broker
                                                   api base url
      --broker-token=<value>                       The broker JWT
      --config-path=<value>                        [default: ./config] The path to the config directory
      --css-client-id=<value>                      [default: id] The css keycloak client id
      --css-client-secret=<value>                  [default: password] The css keycloak client secret
      --css-token-url=<value>                      [default: url] The css token url
      --github-app-id=<value>                      [default: id] The GitHub app id
      --github-client-id=<value>                   [default: id] The GitHub client id
      --github-client-secret=<value>               [default: password] The GitHub client secret
      --github-client-type=<value>                 The GitHub client type
      --github-private-key=<value>                 [default: key] The GitHub private key for signing requests
      --github-token=<value>                       [default: token] A GitHub PAT
      --notification-option-from=<value>           The notification from address
      --notification-option-subject=<value>        [default: Your Access Report (authtool)] The notification subject
      --notification-option-template-html=<value>  The notification template in html
      --notification-option-template-text=<value>  The notification template in text
      --notification-smtp-host=<value>             The SMTP Host
      --notification-smtp-port=<value>             The SMTP port
      --notification-smtp-secure                   The SMTP secure flag
      --source-broker-idp=<value>                  The idp to filter users to

DESCRIPTION
  Monitor for auth changes to sync

`authtool role-sync`

Syncs roles to CSS

USAGE
  $ authtool role-sync [-h] [--broker-api-url <value>] [--broker-token <value>] [--config-path <value>]
    [--source-broker-idp <value>] [--css-token-url <value>] [--css-client-id <value>] [--css-client-secret <value>]
    [--github-client-type <value>] [--github-app-id <value>] [--github-client-id <value>] [--github-client-secret
    <value>] [--github-private-key <value>] [--github-token <value>]

FLAGS
  -h, --help                          Show CLI help.
      --broker-api-url=<value>        [default: https://nr-broker.apps.silver.devops.gov.bc.ca/] The broker api base url
      --broker-token=<value>          The broker JWT
      --config-path=<value>           [default: ./config] The path to the config directory
      --css-client-id=<value>         [default: id] The css keycloak client id
      --css-client-secret=<value>     [default: password] The css keycloak client secret
      --css-token-url=<value>         [default: url] The css token url
      --github-app-id=<value>         [default: id] The GitHub app id
      --github-client-id=<value>      [default: id] The GitHub client id
      --github-client-secret=<value>  [default: password] The GitHub client secret
      --github-client-type=<value>    The GitHub client type
      --github-private-key=<value>    [default: key] The GitHub private key for signing requests
      --github-token=<value>          [default: token] A GitHub PAT
      --source-broker-idp=<value>     The idp to filter users to

DESCRIPTION
  Syncs roles to CSS

EXAMPLES
  $ authtool role-sync

Name		Name	Last commit message	Last commit date
Latest commit History 116 Commits
.github/workflows		.github/workflows
.vscode		.vscode
bin		bin
src		src
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.mocharc.json		.mocharc.json
.prettierrc		.prettierrc
Dockerfile		Dockerfile
README-dev.md		README-dev.md
README.md		README.md
env.hcl		env.hcl
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
setenv-local.sh		setenv-local.sh
tsconfig.build.json		tsconfig.build.json
tsconfig.eslint.json		tsconfig.eslint.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Auth Sync App

Supported Sources

Supported Targets

BC Gov Common Hosted Single Sign-on (CSS)

GitHub

Running

Workflows

Authentication

Configuration

Development

Usage

Commands

`authtool generate`

`authtool help [COMMAND]`

`authtool member-sync`

`authtool monitor`

`authtool role-sync`

About

Releases 9

Packages

Contributors 5

Languages

bcgov-nr/auth-sync-app

Folders and files

Latest commit

History

Repository files navigation

Auth Sync App

Supported Sources

Supported Targets

BC Gov Common Hosted Single Sign-on (CSS)

GitHub

Running

Workflows

Authentication

Configuration

Development

Usage

Commands

authtool generate

authtool help [COMMAND]

authtool member-sync

authtool monitor

authtool role-sync

About

Resources

Stars

Watchers

Forks

Releases 9

Packages 0

Contributors 5

Languages

`authtool generate`

`authtool help [COMMAND]`

`authtool member-sync`

`authtool monitor`

`authtool role-sync`

Packages