Skip to content

Latest commit

 

History

History
278 lines (216 loc) · 12.3 KB

README.md

File metadata and controls

278 lines (216 loc) · 12.3 KB
Raw

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

Supported Targets

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 OIDC roles to target system

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

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

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