1 | # Auth0 Deploy
|
2 |
|
3 | A module which allows easy convention-based deployment of Auth0 components
|
4 |
|
5 | ### Supported Components
|
6 |
|
7 | Currently the module supports the following components:
|
8 |
|
9 | - Clients (with client grants) - Create/Update
|
10 | - Resource Servers (API) - Create/Update
|
11 | - Connections - Create/Update
|
12 | - Rules - Create/Update
|
13 |
|
14 | ## Installation
|
15 |
|
16 | ```javascript
|
17 | npm install -g auth0-deploy
|
18 | ```
|
19 |
|
20 | # Usage (CLI)
|
21 |
|
22 | To create components in Auth0 you must create a folder for each
|
23 | component, with the folder name corresponding to the component name.
|
24 |
|
25 | Each component is grouped under a component type folder.
|
26 |
|
27 | The following is an example structure of components:
|
28 |
|
29 | ```
|
30 | components
|
31 | ├── clients
|
32 | │ └── my-client
|
33 | │ ├── config.json
|
34 | │ └── grants.json
|
35 | ├── connections
|
36 | │ └── member-idp
|
37 | │ ├── config.json
|
38 | │ └── login.js
|
39 | ├── rules
|
40 | │ └── member-rule
|
41 | │ ├── config.json
|
42 | │ └── rule.js
|
43 | └── resource-servers
|
44 | └── members
|
45 | └── config.json
|
46 |
|
47 | ```
|
48 |
|
49 | Each component type has its own folder. Within this folder are folders corresponding to the names of each component of that type.
|
50 |
|
51 | In the above example we expect the following components:
|
52 |
|
53 | - Client
|
54 | - my-client
|
55 | - Connection
|
56 | - member-idp
|
57 | - Resource Server
|
58 | - members
|
59 | - Rules
|
60 | - member-rule
|
61 |
|
62 | ### Common Conventions
|
63 |
|
64 | 1. The **name** of a component is determined by its folder name
|
65 | 2. The options for the component are specified via a `config.json` in the components folder
|
66 | - The `config.json` should match the JSON body format for the component as described in the [Management API](https://auth0.com/docs/api/management/v2#!/Connections/post_connections)
|
67 | - Each component has sensible defaults for the JSON body, properties included in `config.json` override the defaults
|
68 |
|
69 | ### General CLI Usage
|
70 |
|
71 | ```bash
|
72 | auth0-deploy <component-type> [name] [options]
|
73 | ```
|
74 |
|
75 | **component-type** : Can be any of the following: `resource`, `connection`, `client`, `rule`
|
76 |
|
77 | **options**
|
78 |
|
79 | ```
|
80 | Options:
|
81 |
|
82 | -h, --help output usage information
|
83 | -V, --version output the version number
|
84 | -t, --token <token> Auth0 Management API token
|
85 | -c, --client-id <id> Auth0 Client ID
|
86 | -s, --client-secret <secret> Auth0 Client Secret
|
87 | -d, --auth0-domain <domain> Auth0 Domain
|
88 | -w, --working-dir <workingdir> working directory for auth0 components (defaults to current working directory)
|
89 | ```
|
90 |
|
91 | Specifying the name of the component is optional. If the name is not specified, all components under the component type's folder will be
|
92 | created/updated.
|
93 |
|
94 | **Authorization**
|
95 |
|
96 | In order to allow the API calls to the management API to succeed you must:
|
97 |
|
98 | - Create a client which has grants for the appropriate scopes (see: [Auth0 Deploy Cli](https://github.com/auth0/auth0-deploy-cli#to-create-client-by-hand))
|
99 | - Specify `--client-id` and `--client-secret` via cli
|
100 | - Specify Auth0 Domain for the account via `--auth0-domain`
|
101 |
|
102 | **OR**
|
103 |
|
104 | - Create a token from the Management API page with appropriate scopes
|
105 | - Specify `token` via cli
|
106 | - Specify Auth0 Domain for the account via `--auth0-domain`
|
107 |
|
108 | ### Scopes
|
109 |
|
110 | The client/token used with the tool must have the following scopes:
|
111 |
|
112 | ```
|
113 | # For Resource Servers
|
114 | read:resource_servers
|
115 | update:resource_servers
|
116 | create:resource_servers
|
117 |
|
118 | # For connections
|
119 | read:connections
|
120 | update:connections
|
121 | create:connections
|
122 |
|
123 | # For Clients
|
124 | read:clients
|
125 | update:clients
|
126 | create:clients
|
127 |
|
128 | read:client_grants
|
129 | update:client_grants
|
130 | create:client_grants
|
131 | delete:client_grants
|
132 |
|
133 | read:rules
|
134 | update:rules
|
135 | create:rules
|
136 | ```
|
137 |
|
138 | ## Connections
|
139 |
|
140 | In addition to the common conventions, creation of connection resources allows specification of custom script code.
|
141 |
|
142 | In order for your custom scripts to be included as a part of the connection creation, you must create
|
143 | `.js` files corresponding to the custom script.
|
144 |
|
145 | The following scripts are supported:
|
146 |
|
147 | - **Login** -> login.js
|
148 | - **Create** -> create.js
|
149 | - **Verify** -> verify.js
|
150 | - **Change** Password -> change_password.js
|
151 | - **Delete** -> delete.js
|
152 | - **Get User** -> get_user.js
|
153 |
|
154 | From the above example, you can see that only the `login.js` custom script is specified.
|
155 | Any of the scripts which are specified will be added to the connection during creation.
|
156 |
|
157 | Example `config.json`
|
158 |
|
159 | ```json
|
160 | {
|
161 | "options": {
|
162 | "bareConfiguration":{
|
163 | "hostname": "https://myidpurl.com"
|
164 | }
|
165 | }
|
166 | }
|
167 | ```
|
168 |
|
169 | The above `config.json` specifies some configuration properties for the custom scripts to access
|
170 |
|
171 | ### Command
|
172 |
|
173 | Change directory to components folder (ie. your folder should contain `connections`, `clients`, etc.
|
174 |
|
175 | ```bash
|
176 | auth0-deploy connection --token <your-access-token> --auth0-domain <yourhost.auth0.com>
|
177 | ```
|
178 |
|
179 | The above example uses the token Authorization method
|
180 |
|
181 | ## Resource Servers
|
182 |
|
183 | To create a resource server you must specify a `config.json` which describes the body of the resource for the management API.
|
184 |
|
185 | Lets say we have the following directory structure:
|
186 |
|
187 | ```
|
188 | components
|
189 | ├── resource-servers
|
190 | │ └── members
|
191 | │ └── config.json
|
192 |
|
193 | ```
|
194 |
|
195 |
|
196 | An example `config.json` would look like:
|
197 |
|
198 | ```json
|
199 | {
|
200 | "identifier": "https://members.mydomain.com",
|
201 | "scopes": [
|
202 | {"value": "read:email"},
|
203 | {"value": "read:friends"}
|
204 | ],
|
205 | "signing_alg": "RS256"
|
206 | }
|
207 | ```
|
208 |
|
209 | This would create a resource named `members` with scopes: `read:email` and `read:friends`
|
210 |
|
211 | ```bash
|
212 | auth0-deploy resource --token <your-access-token> --auth0-domain <yourhost.auth0.com>
|
213 | ```
|
214 |
|
215 | ## Client
|
216 |
|
217 | Clients follow the same convention as resources except you can specify **client-grants** via
|
218 | the file `grants.json`
|
219 |
|
220 | This file must consist of an array of grants which conform to the grant body as per the [Management API](https://auth0.com/docs/api/management/v2#!/Client_Grants/post_client_grants) requirements.
|
221 | Each grant must omit the `client_id` property as this will be automatically filled based on the given client.
|
222 |
|
223 | An example `grants.json` would look like:
|
224 |
|
225 | ```json
|
226 | [
|
227 | {
|
228 | "audience": "https://some-host.auth0.com/api/v2/",
|
229 | "scope": [
|
230 | "read:users"
|
231 | ]
|
232 | }
|
233 | ]
|
234 | ```
|
235 |
|
236 | As you can see, the grant specifies the `audience` and `scope`, but not the `client_id`
|
237 |
|
238 | ```bash
|
239 | auth0-deploy client --token <your-access-token> --auth0-domain <yourhost.auth0.com>
|
240 | ```
|
241 |
|
242 | ## Rule
|
243 |
|
244 | To create rules you must specify a `rule.js` file which contains your rule code. In addition to the `rule.js`
|
245 | you can also specify a `config.json` similar to other components.
|
246 |
|
247 | An example `config.json` would look like:
|
248 |
|
249 | ```json
|
250 | {
|
251 | "order": 2,
|
252 | "stage": "login_success"
|
253 | }
|
254 | ```
|
255 |
|
256 |
|
257 | ```bash
|
258 | auth0-deploy rule --token <your-access-token> --auth0-domain <yourhost.auth0.com>
|
259 | ```
|
260 |
|
261 |
|
262 | ## Environment specific overrides
|
263 |
|
264 | You may want to have differing values for certain configuration options based on the environment you
|
265 | are deploying to.
|
266 |
|
267 | For example, if we want to create a connection which contacts our own IDP server to authenticate users, you
|
268 | may want to specify different URIs for the IDP server for each environment.
|
269 |
|
270 | To do so, you can add placeholders to your `config.json` files in the form: `@@PLACEHOLDER_NAME@@`
|
271 |
|
272 | Going back to the connection example, lets look at an example `config.json`
|
273 |
|
274 | ### Environment Specific config
|
275 |
|
276 | ```json
|
277 | {
|
278 | "options": {
|
279 | "bareConfiguration":{
|
280 | "hostname": "@@IDP_URI@@"
|
281 | }
|
282 | }
|
283 | }
|
284 | ```
|
285 |
|
286 | Here we have a placeholder for the value of the `hostname` config property.
|
287 | The placeholders name is `IDP_URI`
|
288 |
|
289 | To specify values for this placeholder you can:
|
290 |
|
291 | - Export an environment variable with the name `IDP_URI` before executing the deploy command
|
292 |
|
293 | **OR**
|
294 |
|
295 | - Specify an argument `--IDP_URI <uri>` with the deploy command
|
296 |
|
297 | Example:
|
298 |
|
299 | ```bash
|
300 | auth0-deploy connection --token <your-access-token> --auth0-domain <yourhost.auth0.com> --IDP_URI https://myidp.organization.com
|
301 | ```
|
302 |
|
303 | The above command will replace all instances of the placeholder `IDP_URI` with the given url (which may be specific to the environment)
|
304 |
|
305 |
|
306 | # Usage (as a node module)
|
307 |
|
308 | ...
|