Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Re-write README #259

Merged
merged 2 commits into from
Sep 28, 2020
Merged

Re-write README #259

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ca561a6
Update readme with external submission guidelines, links to documenta…
joshcanhelp Sep 28, 2020
674deb6
README tweaks
joshcanhelp Sep 28, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
177 changes: 53 additions & 124 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,146 +1,75 @@
Auth0 Rules Repository
Auth0 Rule Templates
=====

[![CircleCI](https://circleci.com/gh/auth0/rules.svg?style=svg)](https://circleci.com/gh/auth0/rules)

Rules are code snippets written in JavaScript that are executed as part of the authentication pipeline in [Auth0](https://www.auth0.com). This happens every time a user authenticates to an application. __Rules__ enable very powerful customizations and extensions to be easily added to Auth0.

![](https://docs.google.com/drawings/d/16W_hTS_u2CeDFXkD2PlfituFl7b74EQ6HE_XYn3TdD0/pub?w=891&h=283)

An App initiates an authentication request to Auth0 (__Step 1__), Auth0 routes the request to an Identity Provider through a configured connection (__Step 2__). The user authenticates successfully (__Step3__), the `user` object that represents the logged in user is then passed through the rules pipeline and returned to the app (__Step 4__).

A rule will run on Step 4 and this is the information each rule will get:

* `user`: user object as it comes from the identity provider. It has the following properties:
* `app_metadata`: custom fields that store info about a user that influences the user's access, such as support plan, security roles, or access control groups.
* `created_at`: timestamp indicating when the user profile was first created
* `email`: (unique) user's email address
* `email_verified`: indicates whether the user has verified their email address
* `family_name`: user's family name
* `given_name`: users's given name
* `identities`: Contains info retrieved from the identity provider with which the user originally authenticates. Users may also link their profile to multiple identity providers; those identities will then also appear in this array. In some cases, it will also include an API Access Token to be used with the provider. The contents of an individual identity provider object varies by provider, but it will typically include the following:
* `connection`: name of the Auth0 connection used to authenticate the user
* `isSocial`: indicates whether the connection is a social one
* `provider`: name of the entity that is authenticating the user, such as Facebook, Google, etc.
* `user_id`: user's unique identifier for this connection/provider
* `profileData`: user information associated with the connection. When profiles are linked, it is populated with the associated user info for secondary accounts.
* `last_password_reset`: timestamp indicating the last time the user's password was reset/changed. At user creation, this field does not exist.
* `multifactor`: array/list of MFA providers with which the user is enrolled. This array is updated when the user logs in with MFA successfully for the first time, and is not updated when enrollment is completed or when an administrator resets a user's MFA.
* `name`: user's full name
* `nickname`: user's nickname
* `permissions`: permissions assigned to the user's ID token
* `phone_number`: user's phone number. Only valid for users with SMS connections.
* `phone_verified`: indicates whether the user has verified their phone number. Only valid for users with SMS connections.
* `picture`: URL pointing to the user's profile picture
* `updated_at`: timestamp indicating when the user's profile was last updated/modified. Changes to `last_login` are considered updates, so most of the time, `updated_at` will match `last_login`.
* `user_id`: (unique) The user's unique identifier
* `user_metadata`: custom fields that store information about a user that does not impact what they can or cannot access, such as work address, home address, or user preferences
* `username`: (unique) user's username
* `context`: object containing contextual information of the current authentication transaction. It has the following properties:
* `tenant`: string containing the name of the tenant
* `clientID`: client id of the application the user is logging in to
* `clientName`: name of the application (as defined on the dashboard)
* `client_metadata`: object for holding other application properties that are key/value strings
* `connection`: name of the connection used to authenticate the user (e.g.: `twitter` or `some-google-apps-domain`)
* `connectionID`: string containing the connection's unique identifier
* `connectionStrategy`: type of connection. For social connection `connectionStrategy` === `connection`. For enterprise connections, the strategy will be `waad` (Windows Azure AD), `ad` (Active Directory/LDAP), `auth0` (database connections), etc.
* `connectionOptions`: object representing the options defined on the connection. `connectionOptions.tenant_domain` is a string containing the domain being used for authentication when using an Enterprise connection. `connectionOptions.domain_aliases` is an array containing the optional domains registered as aliases in addition to the primary domain (specified in the `connectionOptions.tenant_domain` property).
* `connectionMetadata`: object representing metadata defined on the connection that are key/value strings
* `protocol`: authentication protocol. Possible values: `oidc-basic-profile` (most used, web-based login), `oidc-implicit-profile` (used on mobile devices and single page apps), `oauth2-resource-owner` (user/password login typically used on database connections), `samlp` (SAML protocol used on SaaS apps), `wsfed` (Ws-Federation used on Microsoft products like Office365), `wstrust-usernamemixed` (Ws-trust user/password login used on CRM and Office365)), `delegation` (during the exchange for a delegation token).
* `stats`: object containing specific user stats, like `stats.loginsCount`. Note that any of the counter variables returned as part of the `stats` object do not increase during silent authentication (as when `prompt=none`). There are also scenarios where the counter variables might increase yet a rule or set of rules do not execute, as in the case of a successful cross-origin authentication followed by a failed token request.
* `sso`: this object will contain information about the Single Sign-on (SSO) transaction (if available). It has the following properties:
* `with_auth0`: when a user signs in with SSO to an application where the `Use Auth0 instead of the IdP to do Single Sign-On`
* `with_dbconn`: SSO login for a user that logged in through a database connection
* `current_clients`: client IDs using SSO
* `accessToken`: object representing the options defined on the Access Token. You can use this object to add custom namespaced claims to the Access Token. `context.accessToken.scope` can be used to change the Access Token's returned scopes. When provided, it is an array containing permissions in string format.
* `idToken`: object representing the options defined on the ID Token. Used to add custom namespaced claims to the ID Token
* `original_protocol`: After a redirect rule has executed and the authentication transaction is resumed, this property will be populated with the original protocol used to initiate the transaction
* `multifactor`: object representing the multifactor settings used in implementing contextual MFA
* `redirect`: object used to implement the redirection of a user from a rule
* `sessionID`: internal identification for the authentication session. Value is kept only if `prompt=none` is used in the authorization request. Note that the session ID can change **after** rule execution on other flows, so the value available in `context.sessionID` might not match the new session ID that the user will receive. This makes this value only meaningful when `prompt=none` is used.
* `request`: object containing useful information of the request. It has the following properties:
* `query`: querystring properties of the login transaction sent by the application
* `body`: body of the POST request on login transactions used on `oauth2-resource-owner` or `wstrust-usernamemixed` protocols.
* `userAgent`: user-agent of the client that is trying to log in
* `ip`: originating IP address of the user trying to log in
* `hostname`: hostname that is being used for the authentication flow
* `geoip`: an object containing geographic IP information. It has the following properties:
* `country_code`: two-character code for the country associated with the IP address
* `country_code3`: three-character code for the country associated with the IP address
* `country_name`: country name associated with the IP address
* `city_name`: city or town name associated with the IP address
* `latitude`: latitude associated with the IP address
* `longitude`: longitude associated with the IP address
* `time_zone`: timezone associated with the IP address
* `continent_code`: two-character code for the continent associated with the IP address
* `primaryUser`: unique user id of the primary account for the user. Used to link user accounts from various identity providers
* `authentication`: object containing information related to the authentication transaction with the following properties:
* `methods`: an array of objects containing the authentication methods a user has completed during their session. This opbject contains the following properties:
* `name`: a string representing the name of the authentication method that has been completed. It can be one of the following values:
* `federated`: social or enterprise connection was used to authenticate the user
* `pwd`: database connection was used to authenticate the user
* `sms`: SMS connection was used to authenticate the user
* `email`: Passwordless Email connection was used to authenticate the user
* `mfa`: the user completed a mulifactor authentication
* `timestamp`: an integer indicating the time in seconds at which the authentication method took place in Unix Epoch time. You can see a sample use case of the `context.authentication.methods` property in the [Require MFA once per session Rule](https://github.com/auth0/rules/blob/master/src/rules/require-mfa-once-per-session.js).
* `authorization`: object containing information related to the authorization transaction with the following properties:
* `roles`: an array of strings containing the names of a user's assigned roles. You can see a sample use case using the `context.authorization.roles` property to add roles to tokens in [Sample Use Cases: Rules with Authorization](https://auth0.com/docs/authorization/concepts/sample-use-cases-rules#add-user-roles-to-tokens).
* `samlConfiguration`: an object that controls the behavior of the SAML and WS-Fed endpoints. Useful for advanced claims mapping and token enrichment (only available for `samlp` and `wsfed` protocol).

Note that rules will also have access to several modules defined globally, including `auth0`, referring to https://github.com/auth0/node-auth0. Other modules available within rules are defined at https://auth0.com/docs/appliance/modules (relevant to both appliance and cloud)

This is the rules editor inside Auth0:

![](http://cdn.auth0.com/docs/img/rules-editor.png)

---
### Available Modules

* [Webtask modules](https://tehsis.github.io/webtaskio-canirequire/)
* [Additional modules](https://auth0.com/docs/appliance/modules)

---
## Contributing
This repo contains Rule templates that appear in the Auth0 Dashboard when you create a new Rule.

## Table of Contents

### Project Structure
- [Documentation](#documentation)
- [Contributing](#contributing)
- [Support + Feedback](#support--feedback)
- [Vulnerability Reporting](#vulnerability-reporting)
- [What is Auth0](#what-is-auth0)
- [License](#license)

Important files/directories:
## Documentation

#### rules.json
- [Rule basics](https://auth0.com/docs/rules)
- [Rule best practices](https://auth0.com/docs/best-practices/rules-best-practices)
- [Using Rule configuration for secrets and other values](https://auth0.com/docs/rules/configuration)
- [Working with metadata in Rules](https://auth0.com/docs/rules/metadata)
- The [`user` object](https://auth0.com/docs/rules/user-object-in-rules) and [`context` object](https://auth0.com/docs/rules/context-object)
- [Redirect users from witihin Rules](https://auth0.com/docs/rules/redirect-users)
- [Debugging Rules](https://auth0.com/docs/rules/debug-rules)
- [NPM modules available in all Rules](https://auth0-extensions.github.io/canirequire/)
- [Rules utility library](https://github.com/auth0/rule-utilities/)

## Contributing

This is the data store that contains the templates that is shown on the rules template dashboard.
It is stored on the CDN and pulled in by the dashboard to display the list.
We appreciate feedback and contribution to this repo! Before you get started, please see the following:

#### src/rules/*.js
- [Auth0's general contribution guidelines](https://github.com/auth0/.github/blob/master/CONTRIBUTING.md)
- [Auth0's code of conduct guidelines](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)

All js files here are scanned during the build. It's JSDocs are read and the attributes such as `@gallery boolean` is used to determine whether or not to add it to the `rules.json` file. Other attributes are used to build the metadata used in `rules.json`.
If you're considering developing a new Rule template, please submit an [Issue](https://github.com/auth0/rules/issues) to discuss with our team. If you'd like to write an integration for the [Auth0 Marketplace](https://marketplace.auth0.com/), please see our [Partners page](https://auth0.com/partners) to get started.

#### redirect-rules/
0. Read the **Contributing** guidelines above
1. Make your changes in `src/rules` by changing an existing template or by adding a new file for a new template
2. If you're adding a new Rule, include the following metadata at the top:
- `@title` 3-5 word title of the rule
- `@overview` brief, one-sentence description of the rule.
- `@gallery` set to `true`
- `@category` use "access control", "enrich profile", "multifactor", "guardian", "debugging", "saml", or "default"
- A detailed, multi-line, Markdown-enabled description of the rule, including any required configuration keys
3. Ensure tests run in both Node v8 and Node v12 using a tool like `nvm`
4. Make sure to test your Rule in Auth0 directly to make sure it can be saved without errors and that it does what you expect during login
5. Submit your PR following the "fork and pull" workflow [described here](https://github.com/auth0/.github/blob/master/CONTRIBUTING.md#submitting-pull-requests)
6. Fill out the PR template completely and our team will review as soon as we're able

These are here for examples and references, not used in the dashboard.
## Support + Feedback

### Developing
- Use the [Support Center](https://support.auth0.com/) for questions on implementation and issues with a Rule installed in your tenant
- Use [Issues](https://github.com/auth0/rules/issues) here for code-level support and bug reports within the templates

1. Update the `src/rules/*.js` files.
2. Ensure tests are passing in `test/` directory. Tests may run on multiple node versions as specified in the circleci build matrix.
3. Bump the version
```bash
npm version [patch|minor|major] --no-git-tag-version
```
4. Push the changes to a branch/PR
5. To deploy the change, create a git tag with the format of `v*`. This will trigger a build and release of the `rules.json` to the CDN.
6. To verify, check the [circleci build](https://circleci.com/gh/auth0/rules). Give the CDN some time to propagate and this should be available in all regions.
## Vulnerability Reporting

---
Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/responsible-disclosure-policy) details the procedure for disclosing security issues.

## Issue Reporting
## What is Auth0?

If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/whitehat) details the procedure for disclosing security issues.
Auth0 helps you to easily:

## Author
- implement authentication with multiple identity providers, including social (e.g., Google, Facebook, Microsoft, LinkedIn, GitHub, Twitter, etc), or enterprise (e.g., Windows Azure AD, Google Apps, Active Directory, ADFS, SAML, etc.)
- log in users with username/password databases, passwordless, or multi-factor authentication
- link multiple user accounts together
- generate signed JSON Web Tokens to authorize your API calls and flow the user identity securely
- access demographics and analytics detailing how, when, and where users are logging in
- enrich user profiles from other data sources using customizable JavaScript rules

[Auth0](auth0.com)
[Why Auth0?](https://auth0.com/why-auth0)

## License

This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.
These Rule templates are licensed under MIT - [LICENSE](LICENSE)