Skip to content

Commit

Permalink
Squashed commit of the following:
Browse files Browse the repository at this point in the history 
commit 96ab5d5
Author: Mark Stillings <[email protected]>
Date:   Mon Jun 22 13:56:56 2020 +0000

    Updated example inventory and playbook files.

commit 284698c
Author: Mark Stillings <[email protected]>
Date:   Mon Jun 22 13:46:33 2020 +0000

    Updated sample HTML and CSV reports.

commit a72c6e3
Author: Mark Stillings <[email protected]>
Date:   Fri Jun 19 15:50:19 2020 +0000

    Finished rework of MD files for all roles.  Changed report versioning to
    just use the overall collection version.
    Still need to update example playbooks and sample reports.

commit 62a661a
Author: Mark Stillings <[email protected]>
Date:   Wed Jun 17 18:38:19 2020 +0000

    Preliminary support for AIX added.  Only package version reading tested
    for now.

commit 8d9d18e
Author: Mark Stillings <[email protected]>
Date:   Wed Jun 17 14:47:38 2020 +0000

    Finished making changes to allow failure details to cascade to later
    roles for use in reports.
    Added 'sas_' (Safeguard Authentication Services) prefix to all Ansible facts generated by the collection since
    Ansible facts can be persisted after a run using a caching plugin and
    are a little more "global" than variables.  Variable names
    do not use this prefix.

commit 9a5d1d6
Author: Mark Stillings <[email protected]>
Date:   Fri Jun 12 21:26:28 2020 +0000

    Cleaned up client_join and added JSON and YAML report detail options.

commit 0f64e6d
Author: Mark Stillings <[email protected]>
Date:   Fri Jun 12 19:46:55 2020 +0000

    Fixes made to client_preflight including adding JSON and YAML options to
    report details.

commit 9e7c5d4
Author: Mark Stillings <[email protected]>
Date:   Fri Jun 12 17:59:14 2020 +0000

    Finalized client_sw code, still need to finish docs.

commit 2770852
Author: Mark Stillings <[email protected]>
Date:   Fri Jun 12 13:14:48 2020 +0000

    Minor fixes to client_sw reports.

commit 45bf4a4
Author: Mark Stillings <[email protected]>
Date:   Thu Jun 11 19:48:49 2020 +0000

    Clean up HTML report, added details support to CSV report, and added
    JSON and YAML formats for details.

commit d64b075
Author: Mark Stillings <[email protected]>
Date:   Thu Jun 11 14:24:30 2020 +0000

    client_sw changes to make it operate like client_preflight and
    client_join are complete and working but a little rough. Comitting
    changes before I do some code cleanup.

commit 977a225
Author: Mark Stillings <[email protected]>
Date:   Wed Jun 10 15:36:22 2020 +0000

    Committing client_sw changes so far.

commit 33c1ccb
Author: Mark Stillings <[email protected]>
Date:   Wed Jun 10 15:30:24 2020 +0000

    First cut at client_join documentation.

commit 680b561
Author: Mark Stillings <[email protected]>
Date:   Wed Jun 10 15:03:49 2020 +0000

    Updated existing docs and created new docs for client_preflight role.

commit 4a19986
Merge: 0ed8293 64236de
Author: Mark Stillings <[email protected]>
Date:   Wed Jun 10 13:54:15 2020 +0000

    Merge remote-tracking branch 'origin/master' into feature/client_join

commit 0ed8293
Author: Mark Stillings <[email protected]>
Date:   Mon Apr 20 13:58:07 2020 +0000

    Initial add of the client_join role.  Plugin client_join_preflight.py is
    pretty far along.  Most everything else was copied from the client_sw
    role and needs to be reworked.

    Minor changes to finish cient_join_preflight.py

    Initial checkin of client_join_vastool.py and vastool.yml files.
    Working in simple cases, still needs work to support more than join.
    Should I use a different name?
    Made some changes to client_join_preflight after improving some things
    in client_join_vastool.

    Renamed preflight and vastool modules.

    Moved common functions from preflight.py and vastool.py to
    module_utils/client_join_utils.py.

    Renamed client_join_utils.py

    Split vastool join into its own module vastool_join.py.  Will be working
    to add other options as normal arguments instead of grouping them all in
    the optional arguments section.

    Broke client_preflight out into its own role.
    Changed output from client_preflight and client_join modules to place
    output in ansible_facts so that it will be useable to generate reports.

    Fixed output formatting of preflight.py and vastool_join.py.

    Progress on client_preflight role and preflight module.  Need to finish
    by adding copying of preflight binary which will require modifying the
    client_sw_pkg_dir module.

    client_preflight role is working including reports.  Need to to done
    cleanup but checking in as it is a good point to do so.

    A lot of changes to finally make preflight work as I would like.
    Ansible fail is no longer masked and will work the same with or without
    report generation.
    Ansible unreachable is now handled.
    Report generation will always include all hosts including failed and
    unreachable hosts.
    Report generation will always succeed even if the last host fails or is
    unreachable.
    Report format for html has been reworked to be able to show full log
    details.
    Still a lot of work left but this is a great start.

    Template work has started.  This version has switched to using
    bootstrap-table for the table.  Right now I still have the popovers for
    log detail but I need to change this to be row details.  It will
    require a lot of changes to I'm checking in progress so far.

    Finished client_preflight html report template.  Will still need to
    split out common code which has been identified in the report for use in
    other reports.
    Will now fix csv report.

    Updated client_preflight CSV report template.

    Finalized client_preflight.  The only thing left is to split out common
    parts of report templates if possible.
    Then, I'll move on to client_join and client_sw.

    Split out parts of html template that could be reused.

    Added coloring of changed, unreachable, and failed table cells.

    Broke out common/detail code in report so that overall report format is
    now clearer.

    Made the required changes to client_join to make it work like
    client_preflight.  Will now move on to doing the same to client_sw.
  • Loading branch information
@mstillings
mstillings committed Jun 22, 2020
1 parent 64236de commit 9d47859
Show file tree
Hide file tree
Showing 87 changed files with 7,725 additions and 470 deletions.
45 changes: 27 additions & 18 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,37 @@
**One Identity open source projects are supported through [One Identity GitHub issues](https://github.com/OneIdentity/ars-ps/issues) and the [One Identity Community](https://www.oneidentity.com/community/). This includes all scripts, plugins, SDKs, modules, code snippets or other solutions. For assistance with any One Identity GitHub project, please raise a new Issue on the [One Identity GitHub project](https://github.com/OneIdentity/ars-ps/issues) page. You may also visit the [One Identity Community](https://www.oneidentity.com/community/) to ask questions. Requests for assistance made through official One Identity Support will be referred back to GitHub and the One Identity Community forums where those requests can benefit all users.**

# Authentication Services Ansible Collection
# Safeguard Authentication Services Ansible Collection

The One Identity Authentication Services Ansible Collection, referred to as `ansible-authentication-services`, consists of roles, modules, plugins, report templates, and sample playbooks to automate software deployment, configuration, Active Directory joining, profiling, and report generation for [Authentication Services](https://www.oneidentity.com/products/authentication-services/).
The One Identity Safeguard Authentication Services Ansible Collection, referred to as `ansible-authentication-services`, consists of roles, modules, plugins, report templates, and sample playbooks to automate software deployment, configuration, Active Directory joining, profiling, and report generation for [Safeguard Authentication Services](https://www.oneidentity.com/products/authentication-services/).

## Collection Contents

### Implemented

* [`common role`](docs/COMMON.md): Common tasks and variables required by other roles
* [`common role`](docs/COMMON.md): Common tasks and variables required by other roles.

* [`client_sw role`](docs/CLIENT_SW.md): Client software install, upgrade, downgrade, uninstall, and version checking.
* [`client_sw_pkg_dir module`](docs/CLIENT_SW.md#Plugins) Client software install package directory checking
* [`pkgdict2items filter`](docs/CLIENT_SW.md#Plugins) Client software package sorting by state and name
* [`client_sw_pkgs module`](docs/CLIENT_SW.md#Plugins) Client software install package directory checking.
* [`pkgdict2items filter`](docs/CLIENT_SW.md#Plugins) Client software package sorting by state and name.

* [`client_preflight role`](docs/CLIENT_PREFLIGHT.md): Check client readiness for software install and AD join.
* [`preflight module`](docs/CLIENT_PREFLIGHT.md#Plugins) Performs preflight tasks on host.

* [`client_join role`](docs/CLIENT_JOIN.md): Client Active Directory joining/unjoining.
* [`vastool_join module`](docs/CLIENT_JOIN.md#Plugins) Performs Active Directory join/unjoin tasks on host.

### In Development

* [`client_join role`](docs/CLIENT_JOIN.md): Client configuration and Active Directory joining.
* [`client_configure role`](docs/CLIENT_CONFIGURE.md): Client configuration.

* [`client_profile role`](docs/CLIENT_PROFILE.md): Client profiling.

### Future

* [`server_sw role`](docs/SERVER_SW.md): Active Directory Server software install, upgrade, downgrade, uninstall, and version checking.

* [`server_config role`](docs/SERVER_CONFIG.md): Active Directory Server configuration.

* [`server_profile role`](docs/SERVER_PROFILE.md): Active Directory Server profiling.

## Installation
Expand All @@ -32,11 +42,11 @@ The One Identity Authentication Services Ansible Collection, referred to as `ans

* `Collections are a new feature introduced in Ansible version 2.9. Please use the latest 2.9+ release for the best user experience.`

* One Identity [Authentication Services](https://www.oneidentity.com/products/authentication-services/) version 4.2.x or later
* One Identity [Safeguard Authentication Services](https://www.oneidentity.com/products/authentication-services/) version 4.2.x or later

* `This collection expects the components and structure of Authentication Services 4.2.x or later.`
* `This collection expects the components and structure of Safeguard Authentication Services 4.2.x or later.`
* See collection role [documentation](docs/) for specific, per-role requirements and instructions.
* See One Identity [Authentication Services documentation](https://support.oneidentity.com/authentication-services/4.2.3/technical-documents) for Authentication Services requirements and instructions.
* See One Identity [Safeguard Authentication Services documentation](https://support.oneidentity.com/authentication-services/4.2.4/technical-documents) for requirements and instructions.

### From Ansible Galaxy
The collection will soon be available through [Ansible Galaxy](https://galaxy.ansible.com/) until then please use the [From GitHub](#FromGitHub) or [Local Build and Install](#LocalBuildandInstall) instructions.
Expand Down Expand Up @@ -70,14 +80,14 @@ To install from [GitHub](https://github.com/OneIdentity/ansible-authentication-s

Using `ansible-galaxy` command:
```bash
ansible-galaxy collection install https://github.com/OneIdentity/ansible-authentication-services/releases/download/v0.0.1/oneidentity-authentication_services-0.0.1.tar.gz
ansible-galaxy collection install https://github.com/OneIdentity/ansible-authentication-services/releases/download/v0.0.2/oneidentity-authentication_services-0.0.2.tar.gz
```

The collection can also be added to a project's `requirements.yml` file
```yaml
---
collections:
- name: https://github.com/OneIdentity/ansible-authentication-services/releases/download/v0.0.1/oneidentity-authentication_services-0.0.1.tar.gz
- name: https://github.com/OneIdentity/ansible-authentication-services/releases/download/v0.0.2/oneidentity-authentication_services-0.0.2.tar.gz
```

and installed using the `ansible-galaxy` command. This method allows all required collections for a project to be specified in one place and installed with one command.
Expand Down Expand Up @@ -107,7 +117,7 @@ For local build and installation, you can clone the Git repository, build the co
The build command will generate an Ansible Galaxy collection artifact with a `tar.gz` file extension, sample output will look like the following:

```
Created collection for oneidentity.authentication_services at /home/user/ansible-authentication-services/oneidentity-authentication_services-0.0.1.tar.gz
Created collection for oneidentity.authentication_services at /home/user/ansible-authentication-services/oneidentity-authentication_services-0.0.2.tar.gz
```

`Pleae note the path shown above is just an example, the path to your build artifact will be in the root directory of the cloned repository.`
Expand All @@ -117,14 +127,14 @@ For local build and installation, you can clone the Git repository, build the co
Using `ansible-galaxy` command:

```bash
ansible-galaxy collection install /home/user/ansible-authentication-services/oneidentity-authentication_services-0.0.1.tar.gz
ansible-galaxy collection install /home/user/ansible-authentication-services/oneidentity-authentication_services-0.0.2.tar.gz
```

The collection can also be added to a project's `requirements.yml` file
```yaml
---
collections:
- name: /home/user/ansible-authentication-services/oneidentity-authentication_services-0.0.1.tar.gz
- name: /home/user/ansible-authentication-services/oneidentity-authentication_services-0.0.2.tar.gz
```

and installed using the `ansible-galaxy` command. This method allows all required collections for a project to be specified in one place and installed with one command.
Expand All @@ -140,19 +150,18 @@ The collection provides various sample playbooks in the [examples](examples/READ

## Supported Platforms

All Authentication Services supported [platforms](https://support.oneidentity.com/technical-documents/authentication-services/4.2.3/release-notes/2#TOPIC-1376245) except IBM AIX. Support for IBM AIX will be added soon.
All [Safeguard Authentication Services supported platforms](https://support.oneidentity.com/technical-documents/authentication-services/4.2.4/release-notes/2#TOPIC-1376245).

## Notes

### Known issues

* Check mode does not work as expected for the client_sw role. No changes are made and it doesn't cause errors but the stated changes that would or would not be made if run normally are not accurate.
* The directory of client software install packages has to be on the Ansible control node. It would be nice to be able to point to this directory on another machine but this is not possible at this time.
* The IPV4 address for HP-UX machines does not show up in the CSV and HTML reports, this is due to differences in how facts are reported for this OS. No plan to fix at issue at this time.
* The IPV4 address for HP-UX machines does not show up in the CSV and HTML reports, this is due to differences in how facts are reported for this OS. No plan to fix this issue at this time.

### TODO's

* Add support to client_sw role for IBM AIX.
* Implement client_join role.
* Implement client_configure role.
* Implement client_profile role.
* Other roles/features depending on interest may include roles to automate server software deployment, server configuration, and server profiling.
145 changes: 144 additions & 1 deletion docs/CLIENT_JOIN.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,146 @@
# `client_join` Role

In development
The `client_join` role performs [Safeguard Authentication Services](https://www.oneidentity.com/products/authentication-services/) client Active Directory joins and unjoins. Report generation can be enabled to provide CSV and HTML reports of the results.

## Requirements

The role requires the [Safeguard Authentication Services](https://www.oneidentity.com/products/authentication-services/) client software be installed on the client. See [`client_sw role`](docs/CLIENT_SW.md) for how to peform client software installation using Ansible.

## Variables

All of the variables shown below have a default value but can be overridden to suit your environment. Variable overriding can be done in playbooks, inventories, from the command line using the `-e` switch with the `ansible-playbook` command, or from Ansible Tower and AWX. See [Ansbile documentation](https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html) for further information.

### Active Directory

See [Active Directory variables](./COMMON.md##ActiveDirectory) in `common role`.

* `client_join_state` sets the desired join state. Possible state values:

* `joined` joined to specified Active Directory domain.
* `unjoined` unjoined from specified Active Directory domain.

Default value is:
```yaml
client_join_state: joined
```
### Vastool Binary
* `client_join_extra_args` allows passing additional arguments to the vastool binary. `client_join` uses the `join` and `unjoin` vastool commands.

Default value is:
```yaml
client_preflight_extra_args:
```

### Facts generation

Facts generation variable defaults for all roles are set by variables in the `common role` and can be overriden for all roles by setting the appropriate `common role` variable. See [common role facts generation variables](./COMMON.md##FactsGeneration) in `common role`.

* `client_join_facts_generate` enables facts generation. Implicitely enabled if `client_join_reports_generate` is set.

Default value is:
```yaml
client_join_facts_generate: "{{ facts_generate }}"
```

* `client_join_facts_verbose` enables verbose facts generation.

Default value is:
```yaml
client_join_facts_verbose: "{{ facts_verbose }}"
```

### Report generation

Report generation variable defaults for all roles are set by variables in the `common role` and can be overriden for all roles by setting the appropriate `common role` variable. See [common role reports generation variables](./COMMON.md##ReportsGeneration) in `common role`.

* `client_sww_reports_generate` enables report generation. Reports are generated at the end of a `client_sw` run for all hosts.

Default value is:
```yaml
client_join_reports_generate: "{{ reports_generate }}"
```

Disabling report generation if not needed will increase the speed of the `client_sw` role.

* `client_join_reports_backup` enables backup of prior reports by renaming them with the date and time they were generated so that the latest reports do not override the previous reports.

Default value is:
```yaml
client_join_reports_backup: "{{ reports_backup }}"
```

* `client_join_reports_details_format` sets the format of the details section in both the HTML and CSV reports. Valid options:
* `yaml` details will be in YAML format
* `json` details will be in JSON format

Default value is:
```yaml
client_join_reports_details_format: "{{ reports_details_format }}"
```

* `client_join_reports_host` sets the host on which the reports should be generated.

Default value is:
```yaml
client_join_reports_host: "{{ reports_host }}"
```

* `client_join_reports` is a list of dictionaries that define the reports to be generated. The default value creates a CSV and HTML report using the templates included with the `client_sw` role.

Default value is:
```yaml
client_join_reports:
- src: client_join_report.csv.j2
dest: client_join_report.csv
- src: client_join_report.html.j2
dest: client_join_report.html
```

The `src` key for each list entry is the report template file on the Ansible control node. With a relative path Ansible will look in the `client_sw` role `template` directory. Use a absolute path to speciy templates located elsewhere on the Ansible control node.

The `dest` key for each list entry is the report file on the machine specified in `client_join_reports_host`. If `client_join_reports_host` is set to the Ansible control node a relative path can be used and it will be relative to the directory from which the playbook is run. For other hosts, an absolute path must be used. In either case the containing directory must exist.

## Plugins

The `client_join` role contains a plugin to support operation of the role:

* `vastool_join` module performs Active Directory join/unjoin tasks on host by wrapping the [Safeguard Authentication Services](https://www.oneidentity.com/products/authentication-services/) vastool binary join and unjoin commands.

## Usage

Below is a sample playbook using the `client_join` role.

```yaml
---
- hosts: all
gather_facts: false
# The variables you would most likely want/need to override have been included
vars:
# Active Directory
client_join_state: joined
client_domain: sample.net
client_username: user
client_password: pass
# Facts
client_join_facts_generate: false
client_join_facts_verbose: true
# Reports
client_join_reports_generate: true
client_join_reports_backup: false
roles:
- name: oneidentity.authentication_services.client_join
```

See sample [HTML](http://htmlpreview.github.io/?https://github.com/OneIdentity/ansible-authentication-services/blob/master/docs/client_join_report.html) and [CSV](client_join_report.csv) reports generated from a run of this sample playbook.

For a copy of this and other sample playbooks see [examples](../examples/README.md)
Loading

0 comments on commit 9d47859

Please sign in to comment.