{"id":26934964,"url":"https://github.com/magicmemories/puppet-auth0","last_synced_at":"2025-04-02T11:16:25.470Z","repository":{"id":57664694,"uuid":"191850920","full_name":"magicmemories/puppet-auth0","owner":"magicmemories","description":"Puppet module for managing Auth0 configuration via the management API","archived":false,"fork":false,"pushed_at":"2021-01-21T21:31:41.000Z","size":121,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-16T17:40:38.244Z","etag":null,"topics":["auth0","puppet","puppet-module"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/magicmemories.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-06-14T00:33:05.000Z","updated_at":"2021-01-27T20:25:18.000Z","dependencies_parsed_at":"2022-09-14T21:40:41.536Z","dependency_job_id":null,"html_url":"https://github.com/magicmemories/puppet-auth0","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicmemories%2Fpuppet-auth0","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicmemories%2Fpuppet-auth0/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicmemories%2Fpuppet-auth0/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicmemories%2Fpuppet-auth0/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/magicmemories","download_url":"https://codeload.github.com/magicmemories/puppet-auth0/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246802624,"owners_count":20836373,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auth0","puppet","puppet-module"],"created_at":"2025-04-02T11:16:22.931Z","updated_at":"2025-04-02T11:16:24.675Z","avatar_url":"https://github.com/magicmemories.png","language":"Ruby","readme":"# auth0\n\n#### Table of Contents\n\n1. [Description](#description)\n2. [Setup - The basics of getting started with auth0](#setup)\n3. [Usage - Managing Auth0](#usage---managing-auth0)\n4. [Usage - Querying Auth0](#usage---querying-auth0)\n5. [Limitations - OS compatibility, etc.](#limitations)\n6. [License and Authorship](#license-and-authorship)\n7. [Development - Guide for contributing to the module](#development)\n\n## Description\n\nThis module allows you to use Puppet to manage your Auth0 entities. It also provides the ability to query Auth0 and retrieve credentials\nfor use in Machine-to-Machine authentication flows (which you can then write to an application configuration file).\n\n## Setup\n\nIn order for Puppet to access Auth0, you will need to create a Machine-to-Machine Application (aka a `non_interactive` client) inside Auth0,\nand grant that client access to the Auth0 Management API. See [Machine-to-Machine Applications](https://auth0.com/docs/applications/machine-to-machine)\nfor details. The scopes used by each resource type and function are documented in REFERENCE.md.\n\nThis module treats each Auth0 tenant as a remote 'device', and uses the `puppet device` pattern for managing Auth0 resources. See the\n[Puppet Device](https://puppet.com/docs/puppet/5.5/puppet_device.html) Documentation for details. The easiest way to get started is to use\nthe [puppetlabs-device_manager](https://forge.puppet.com/puppetlabs/device_manager) module, like so:\n\n```puppet\ndevice_manager { 'my-tenant.auth0.com':\n  type        =\u003e 'auth0_tenant',\n  credentials =\u003e {\n    client_id     =\u003e $management_client_id,\n    client_secret =\u003e $management_client_secret,\n    domain        =\u003e 'my-tenant.auth0.com',\n  },\n}\n```\n\nThe proxy node that is running `puppet device` will need to have the [auth0](https://rubygems.org/gems/auth0) gem installed. The easiest way to set this up is\nto use the [`puppet_gem`](https://puppet.com/docs/puppet/5.5/types/package.html#package-provider-puppet_gem) provider for the `package` resource type:\n\n```puppet\npackage { 'auth0':\n  ensure   =\u003e '4.11.0',\n  provider =\u003e 'puppet_gem',\n}\n```\n\nTo use the `auth0_get_client_credentials` function you will also need the auth0 gem installed on the Puppet Server. The easiest way to set this up is\nwith the [puppetlabs-puppetserver_gem](https://forge.puppet.com/puppetlabs/puppetserver_gem) module:\n\n```puppet\npackage { 'auth0':\n  ensure   =\u003e present,\n  provider =\u003e 'puppetserver_gem',\n}\n```\n\nIf you are using this module with Puppet 5, you will need to have access to the [`puppet-resource_api`](https://rubygems.org/gems/puppet-resource_api) gem\non both your server and agents. You can either do this via `package` resources with the `puppet_gem` and `puppetserver_gem` types as above, or use the\n[`puppetlabs-resource_api`](https://forge.puppet.com/puppetlabs/resource_api) module to do it for you.\n\n## Usage - Managing Auth0\nThese resource types can be used in a Device context to manage resources via the Auth0 Management API\n\n### Creating a Client (Application)\n```puppet\nauth0_client { 'example_application':\n  display_name    =\u003e 'Example Application',\n  description     =\u003e 'An example application to show how to use the auth0 Puppet module.',\n  app_type        =\u003e 'non_interactive',\n  callbacks       =\u003e ['https://app.example.com/callback'],\n  allowed_origins =\u003e ['https://app.example.com'],\n  web_origins     =\u003e ['https://app.example.com'],\n}\n```\n\nFor Clients, the resource title will be stored in the `client_metadata` as `puppet_resource_identifier`.\n\nIf you pass `keep_extra_callbacks =\u003e true`, then callbacks defined in Auth0 but not in Puppet will be retained; otherwise they will be removed.\nThis is useful for dev/test tenants in which individual developers may add callbacks on localhost through the dashboard. `keep_extra_allowed_origins`,\n`keep_extra_web_origins` and `keep_extra_logout_urls` function similarly.\n\n### Creating a Resource Server (API)\n```puppet\nauth0_resource_server { 'https://api.example.com':\n  display_name =\u003e \"Example API\",\n  signing_alg  =\u003e \"RS256\",\n  scopes       =\u003e {\n    'read:thingies'  =\u003e 'Get information about Thingies',\n    'write:thingies' =\u003e 'Create, update and destroy Thingies',\n    'read:doodads'   =\u003e 'Get information about Doodads',\n  },\n}\n```\n\n### Grant a Client access to a Resource Server with a Client Grant:\n```puppet\nauth0_client_grant { 'Give Example Application access to Example API':\n  client_resource =\u003e 'example_application',\n  audience        =\u003e 'https://api.example.com':,\n  scopes          =\u003e [\n    'read:thingies',\n  ],\n}\n\n# Equivalent to above\nauth0_client_grant { 'example_application -\u003e https://api.example.com':\n  scopes =\u003e [\n    'read:thingies',\n  ],\n}\n```\n\n### Define a Rule\n```puppet\nauth0_rule { 'Example Rule':\n  script =\u003e file('profile/auth0/example_rule.js'),\n}\n```\n\n### Assign a Connection to Clients\n```puppet\nauth0_connection { 'ExampleConnection':\n  clients  =\u003e [\n    'example_application',\n    'another_application',\n  ],\n  options  =\u003e {\n    brute_force_protection =\u003e true,\n    mfa                    =\u003e {\n      active                 =\u003e true,\n      return_enroll_settings =\u003e true,\n    },\n  },\n  strategy =\u003e 'auth0',\n}\n```\nIf you pass `keep_extra_clients =\u003e true`, then clients assigned to that\nconnection in Auth0 but not in Puppet will be retained; otherwise they will be\nremoved. `keep_extra_options` behaves similarly. However, in either case these\nonly have an effect if you specify a value for the `clients` or `options`\nattributes, respectively; omitting those attributes entirely will leave them\nuntouched.\n\n`keep_extra_options` performs a non-recursive merge between the options stored\nin Auth0 and the options you specify; nested hashes such as the `mfa` hash in\nthe example above will be overwritten even with `keep_extra_options`, if you\nprovide a value for them.\n\n## Usage - Querying Auth0\n\nThe `auth0_get_client_credentials` `auth0_get_client_credentials_by_name`\nfunctions can be used in an Agent or Apply context to retrieve information from\nAuth0 when configuring your own servers and applications.\n\n`auth0_get_client_credentials` looks up clients by their\npuppet_resource_identifier, whereas `auth0_get_client_credentials_by_name`\nlooks them up by display name.\n\n### Retrieve client credentials for a Machine-to-Machine application\n\n#### With Management API credentials stored in Hiera\n```yaml\nauth0::management_client_id: 'abcdef12345678'\nauth0::management_client_secret: 'abcedfg12313fgasdt235gargq345qrg4423425413543254535'\nauth0::tenant_domain: 'example.auth0.com'\n```\n```puppet\n$credentials = auth0_get_client_credentials('example_application')\nfile { '/etc/example.conf':\n  ensure  =\u003e present,\n  content =\u003e epp('profile/example/example.conf.epp', {\n    client_id     =\u003e $credentials['client_id'],\n    client_secret =\u003e $credentials['client_secret'],\n  }),\n}\n```\n\n#### With Management API credentials provided explicitly\n```puppet\n$credentials = auth0_get_client_credentials(\n  'example_application',\n  'abcdef12345678',\n  'abcedfg12313fgasdt235gargq345qrg4423425413543254535',\n  'example.auth0.com',\n)\nfile { '/etc/example.conf':\n  ensure  =\u003e present,\n  content =\u003e epp('profile/example/example.conf.epp', {\n    client_id     =\u003e $credentials['client_id'],\n    client_secret =\u003e $credentials['client_secret'],\n  }),\n}\n```\n\n## Limitations\n\n### Resource Names\nIn order for Puppet to operate, every resource needs an identifier which meets two criteria:\n\n1. It uniquely identifies a specific resource, consistently over time.\n2. It can be specified by the sysadmin when creating the resource.\n\nMost Auth0 resource types have a unique identifier which fails the second criterion: for example, the unique identifier for an\nAuth0 Client resource should be its `client_id`, but you can't specify the client_id when creating a resource, so it can't be used as a\n`namevar` in Puppet (and even if you could, you wouldn't really want to).\n\nIn order to work around this for clients we look for a field named `puppet_resource_identifier` in the client's\n`client_metadata` hash, and use that as the `namevar`. This attribute should be treated as unique and immutable,\neven if auth0 doesn't force you to.\n\nRules don't have anything analogous to `client_metadata`, so we're stuck using the rule's \"Display Name\" as a namevar.\nAgain, because of this you should treat Rule names as unique and immutable identifiers, even though Auth0 doesn't require you to.\n\n`auth0_resource_server` resources don't have this problem, since the `identifier` (aka 'Audience') attribute of a Resource Server _is_\nan immutable identifier that can be specified when creating the resource.\n\n### Rate Limiting\nThe `ruby-auth0` gem (on which this module is built) doesn't expose enough information during rate-limiting to try dynamically wait out the issue. If rate-limiting\nis encountered during the puppet run, then further resources which make use of the same API endpoints will fail. This module does do some caching to limit the number\nof API requests.\n\n### Missing Features\nNot all aspects of your Auth0 configuration can be managed via their API, not all resource types that _can_ be managed by the API are implemented by this module yet,\nand not all properties of the implemented resource types are supported yet. Specifically, the following properties are not yet supported by this module:\n\n* from the Clients API:\n  * allowed_clients\n  * jwt_configuration.scopes\n  * encryption_key\n  * cross_origin_auth\n  * cross_origin_loc\n  * custom_login_page_on\n  * custom_login_page\n  * custom_login_page_preview\n  * form_template\n  * is_heroku_app\n  * addons\n  * client_metadata (except for the puppet_resource_identifier)\n  * mobile\n* from the ResourceServers API:\n  * verificationLocation\n  * options\n\n## License and Authorship\n\nThis module was authored by Adam Gardner, and is Copyright (c) 2019 Magic Memories (USA) LLC.\n\nIt is distributed under the terms of the Apache-2.0 license; see the LICENSE file for details.\n\n## Development\nIf you run into any problems, open an [issue](https://github.com/magicmemories/puppet-auth0/issues) or\n[fork](https://github.com/magicmemories/puppet-auth0/fork) and open a\n[Pull Request](https://github.com/magicmemories/puppet-auth0/pulls).\n\nTo be able to run the spec suite during development, first install the necessary dependencies:\n\n    bundle install\n\nThen, run the spec suite:\n\n    bundle exec rake spec","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagicmemories%2Fpuppet-auth0","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmagicmemories%2Fpuppet-auth0","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagicmemories%2Fpuppet-auth0/lists"}