ewilliams28/releases
1
0
Fork 0
mirror of https://github.com/open-policy-agent/opa.git synced 2026-08-13 03:42:35 -06:00
Code Issues Packages Projects Releases Wiki Activity

Rename examples to tutorials

Browse Source
This commit is contained in:
Torin Sandall
2017-05-11 07:30:58 -07:00
parent df336bfded
commit bb399bc9e4
8 changed files with 81 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files
site/_includes/nav-examples.html
-32
View File
@@ -1,32 +0,0 @@
{% assign xmp_repl = false %}
{% assign xmp_auth = false %}
{% for page in site.pages %}
{% case page.xmp_id %}
{% when 'WORKING_WITH_THE_OPA_REPL' %}
{% assign xmp_repl = page %}
{% when 'DOCKER_AUTHORIZATION' %}
{% assign xmp_auth = page %}
{% when 'HTTP_API_AUTHORIZATION' %}
{% assign xmp_http_api_auth = page %}
{% when 'SSH_SUDO_AUTHORIZATION' %}
{% assign xmp_ssh_sudo_auth = page %}
{% endcase %}
{% endfor %}
<nav class="opa-header--abstract--nav">
<ul class="opa-header--abstract--nav-list">
<li class="opa-header--abstract--nav-item{% if page.xmp_id == xmp_repl.xmp_id %}--selected{% endif %}">
{% if page.xmp_id != xmp_repl.xmp_id %}<a class="opa-header--abstract--nav-link" href="{{xmp_repl.url}}">{{ xmp_repl.title }}</a>{% else %}{{ xmp_repl.title }}{% endif %}
</li>
<li class="opa-header--abstract--nav-item{% if page.xmp_id == xmp_auth.xmp_id %}--selected{% endif %}">
{% if page.xmp_id != xmp_auth.xmp_id %}<a class="opa-header--abstract--nav-link" href="{{xmp_auth.url}}">{{ xmp_auth.title }}</a>{% else %}{{ xmp_auth.title }}{% endif %}
</li>
<li class="opa-header--abstract--nav-item{% if page.xmp_id == xmp_http_api_auth.xmp_id %}--selected{% endif %}">
{% if page.xmp_id != xmp_http_api_auth.xmp_id %}<a class="opa-header--abstract--nav-link" href="{{xmp_http_api_auth.url}}">{{ xmp_http_api_auth.title }}</a>{% else %}{{ xmp_http_api_auth.title }}{% endif %}
</li>
<li class="opa-header--abstract--nav-item{% if page.xmp_id == xmp_ssh_sudo_auth.xmp_id %}--selected{% endif %}">
{% if page.xmp_id != xmp_ssh_sudo_auth.xmp_id %}<a class="opa-header--abstract--nav-link" href="{{xmp_ssh_sudo_auth.url}}">{{ xmp_ssh_sudo_auth.title }}</a>{% else %}{{ xmp_ssh_sudo_auth.title }}{% endif %}
</li>
</ul>
</nav>
site/_includes/nav-main.html
+6 -6
View File
@@ -1,7 +1,7 @@
{% assign page_top = false %}
{% assign page_get = false %}
{% assign page_doc = false %}
{% assign page_xmp = false %}
{% assign page_tutorial = false %}
{% assign page_com = false %}
{% for page in site.pages %}
@@ -14,9 +14,9 @@
{% if page.doc_id == 'WHAT_IS_POLICY_ENABLEMENT' %}
{% assign page_doc = page %}
{% endif %}
{% when 'MAIN_EXAMPLES' %}
{% if page.xmp_id == 'WORKING_WITH_THE_OPA_REPL' %}
{% assign page_xmp = page %}
{% when 'MAIN_TUTORIALS' %}
{% if page.tutorial_id == 'WORKING_WITH_THE_OPA_REPL' %}
{% assign page_tutorial = page %}
{% endif %}
{% when 'MAIN_COMMUNITY' %}
{% assign page_com = page %}
@@ -34,8 +34,8 @@
<li class="opa-nav-main--item{% if page.nav_id == page_doc.nav_id %}--selected{% endif %}">
{% if page.nav_id != page_doc.nav_id %}<a class="opa-nav-main--link" href="{{page_doc.url}}">Documentation</a>{% else %}Documentation{% endif %}
</li>
<li class="opa-nav-main--item{% if page.nav_id == page_xmp.nav_id %}--selected{% endif %}">
{% if page.nav_id != page_xmp.nav_id %}<a class="opa-nav-main--link" href="{{page_xmp.url}}">Examples</a>{% else %}Examples{% endif %}
<li class="opa-nav-main--item{% if page.nav_id == page_tutorial.nav_id %}--selected{% endif %}">
{% if page.nav_id != page_tutorial.nav_id %}<a class="opa-nav-main--link" href="{{page_tutorial.url}}">Tutorials</a>{% else %}Tutorials{% endif %}
</li>
<li class="opa-nav-main--item{% if page.nav_id == page_com.nav_id %}--selected{% endif %}">
{% if page.nav_id != page_com.nav_id %}<a class="opa-nav-main--link" href="{{page_com.url}}">Community</a>{% else %}Community{% endif %}
site/_includes/nav-tutorials.html
+34
View File
@@ -0,0 +1,34 @@
{% assign tutorial_repl = false %}
{% assign tutorial_auth = false %}
{% assign tutorial_http_api_auth = false %}
{% assign tutorial_ssh_sudo_auth = false %}
{% for page in site.pages %}
{% case page.tutorial_id %}
{% when 'WORKING_WITH_THE_OPA_REPL' %}
{% assign tutorial_repl = page %}
{% when 'DOCKER_AUTHORIZATION' %}
{% assign tutorial_auth = page %}
{% when 'HTTP_API_AUTHORIZATION' %}
{% assign tutorial_http_api_auth = page %}
{% when 'SSH_SUDO_AUTHORIZATION' %}
{% assign tutorial_ssh_sudo_auth = page %}
{% endcase %}
{% endfor %}
<nav class="opa-header--abstract--nav">
<ul class="opa-header--abstract--nav-list">
<li class="opa-header--abstract--nav-item{% if page.tutorial_id == tutorial_repl.tutorial_id %}--selected{% endif %}">
{% if page.tutorial_id != tutorial_repl.tutorial_id %}<a class="opa-header--abstract--nav-link" href="{{tutorial_repl.url}}">{{ tutorial_repl.title }}</a>{% else %}{{ tutorial_repl.title }}{% endif %}
</li>
<li class="opa-header--abstract--nav-item{% if page.tutorial_id == tutorial_auth.tutorial_id %}--selected{% endif %}">
{% if page.tutorial_id != tutorial_auth.tutorial_id %}<a class="opa-header--abstract--nav-link" href="{{tutorial_auth.url}}">{{ tutorial_auth.title }}</a>{% else %}{{ tutorial_auth.title }}{% endif %}
</li>
<li class="opa-header--abstract--nav-item{% if page.tutorial_id == tutorial_http_api_auth.tutorial_id %}--selected{% endif %}">
{% if page.tutorial_id != tutorial_http_api_auth.tutorial_id %}<a class="opa-header--abstract--nav-link" href="{{tutorial_http_api_auth.url}}">{{ tutorial_http_api_auth.title }}</a>{% else %}{{ tutorial_http_api_auth.title }}{% endif %}
</li>
<li class="opa-header--abstract--nav-item{% if page.tutorial_id == tutorial_ssh_sudo_auth.tutorial_id %}--selected{% endif %}">
{% if page.tutorial_id != tutorial_ssh_sudo_auth.tutorial_id %}<a class="opa-header--abstract--nav-link" href="{{tutorial_ssh_sudo_auth.url}}">{{ tutorial_ssh_sudo_auth.title }}</a>{% else %}{{ tutorial_ssh_sudo_auth.title }}{% endif %}
</li>
</ul>
</nav>
site/_layouts/examples.html → site/_layouts/tutorials.html
+1 -1
View File
@@ -9,7 +9,7 @@
<div class="opa-content">
<div class="opa-header--abstract">
{% include nav-examples.html %}
{% include nav-tutorials.html %}
{% contentblock header %}
</div>
site/examples/docker-authorization/index.md → site/tutorials/docker-authorization/index.md
+12 -12
View File
@@ -1,8 +1,8 @@
---
sort_order: 1001
nav_id: MAIN_EXAMPLES
xmp_id: DOCKER_AUTHORIZATION
layout: examples
nav_id: MAIN_TUTORIALS
tutorial_id: DOCKER_AUTHORIZATION
layout: tutorials
title: Docker Authorization
---
@@ -20,7 +20,7 @@ This is an excellent opportunity to see how to policy enable an existing service
## Goals
This example helps you get started with OPA and introduces you to core concepts in OPA, including Rego the language used to define policies.
This tutorial helps you get started with OPA and introduces you to core concepts in OPA, including Rego the language used to define policies.
> Policy enabling an application decouples the policy implementation from the business logic so that administrators can define policy without changing the application while still keeping up with the size, complexity, and dynamic nature of modern applications.
{: .opa-tip}
@@ -30,12 +30,12 @@ Although there are a multitude of desirable access control policies, for demonst
* Containers with insecure configurations.
* Users modifying the system without sufficient read+write access.
This example illustrates two key concepts:
This tutorial illustrates two key concepts:
1. OPA policy definition is decoupled from the implementation of the service (in this case Docker). The administrator is empowered to define and manage policies without requiring changes to any of the apps.
2. Both the data relevant to policy and the policy definitions themselves can change rapidly.
Once you finish this example, you will be familiar with:
Once you finish this tutorial, you will be familiar with:
* Running OPA as a server/daemon.
* Loading policy definitions and data via the REST APIs.
@@ -44,12 +44,12 @@ Once you finish this example, you will be familiar with:
## Prerequisites
This example requires:
This tutorial requires:
* Docker Engine 1.11 or newer
* `root` or `sudo` access
The example has been tested on the following platforms:
The tutorial has been tested on the following platforms:
* Ubuntu 16.04 (64-bit)
@@ -77,7 +77,7 @@ $ chmod u+x opa
$ ./opa run --server --log-level debug
```
OPA will run until it receives a signal to stop. Open another terminal to continue with the rest of the example.
OPA will run until it receives a signal to stop. Open another terminal to continue with the rest of the tutorial.
### 4. Download the [open-policy-agent/opa-docker-authz](https://github.com/open-policy-agent/opa-docker-authz) executable.
@@ -233,11 +233,11 @@ Congratulations! You have successfully prevented containers from running without
So far, the policy has been defined in terms of input data from the plugin. In many cases, it's necessary to write policies against multiple data sources.
The rest of the example shows how you can grant fine grained access to specific clients. To do so, we will insert fake user data into OPA to simulate an authentication system.
The rest of the tutorial shows how you can grant fine grained access to specific clients. To do so, we will insert fake user data into OPA to simulate an authentication system.
### <a name="identify-user"></a> 12. Identify the user in Docker requests.
> Back up your existing Docker configuration, just in case. You can replace your original configuration after you are done with the example.
> Back up your existing Docker configuration, just in case. You can replace your original configuration after you are done with the tutorial.
{: .opa-tip}
```shell
@@ -257,7 +257,7 @@ $ cat >~/.docker/config.json <<EOF
EOF
```
Docker does not currently provide a way to authenticate clients. But in Docker 1.12, clients can be authenticated using TLS and there are plans to include other means of authentication. For the purpose of this example, we assume that an authentication system is place.
Docker does not currently provide a way to authenticate clients. But in Docker 1.12, clients can be authenticated using TLS and there are plans to include other means of authentication. For the purpose of this tutorial, we assume that an authentication system is place.
### 13. Add user data directly to OPA.
site/examples/http-api-authorization/index.md → site/tutorials/http-api-authorization/index.md
+9 -9
View File
@@ -1,8 +1,8 @@
---
sort_order: 1002
nav_id: MAIN_EXAMPLES
xmp_id: HTTP_API_AUTHORIZATION
layout: examples
nav_id: MAIN_TUTORIALS
tutorial_id: HTTP_API_AUTHORIZATION
layout: tutorials
title: HTTP API Authorization
---
@@ -18,22 +18,22 @@ Anything that exposes an HTTP API (whether an individual microservice or an appl
## Goals
In this example, you'll use a simple HTTP web server that accepts any HTTP GET
In this tutorial, you'll use a simple HTTP web server that accepts any HTTP GET
request that you issue and echoes the OPA decision back as text. Both OPA and
the web server will be run as containers.
For this example, our desired policy is:
For this tutorial, our desired policy is:
* People can see their own salaries (`GET /finance/salary/{user}` is permitted for `{user}`)
* A manager can see their direct reports' salaries (`GET /finance/salary/{user}` is permitted for `{user}`'s manager)
## Prerequisites
This example requires [Docker Compose](https://docs.docker.com/compose/install/) to run a demo web server along with OPA.
This tutorial requires [Docker Compose](https://docs.docker.com/compose/install/) to run a demo web server along with OPA.
## Steps
### 1. Bootstrap the example environment using Docker Compose.
### 1. Bootstrap the tutorial environment using Docker Compose.
First, create a docker-compose.yml file that runs OPA and the demo web server.
@@ -175,7 +175,7 @@ curl --user frank:password localhost:5000/finance/salary/frank
## Wrap Up
Congratulations for finishing the example!
Congratulations for finishing the tutorial!
You learned a number of things about API authorization with OPA:
@@ -185,7 +185,7 @@ You learned a number of things about API authorization with OPA:
* You can import external data into OPA and write policies that depend on
that data.
The code for this example can be found in the
The code for this tutorial can be found in the
[open-policy-agent/contrib](https://github.com/open-policy-agent/contrib)
repository.
site/examples/ssh-sudo-authorization/index.md → site/tutorials/ssh-sudo-authorization/index.md
+12 -12
View File
@@ -1,8 +1,8 @@
---
sort_order: 1003
nav_id: MAIN_EXAMPLES
xmp_id: SSH_SUDO_AUTHORIZATION
layout: examples
nav_id: MAIN_TUTORIALS
tutorial_id: SSH_SUDO_AUTHORIZATION
layout: tutorials
title: SSH and sudo Authorization
---
@@ -11,9 +11,9 @@ title: SSH and sudo Authorization
# SSH and sudo Authorization
Enforcing access controls at the host-level is an important part of every
organization's security strategy. Using [Linux-PAM](http://tldp.org/HOWTO/User-Authentication-HOWTO/x115.html) and OPA we can extend
policy-based access control to SSH and sudo.
Host-level access controls are an important part of every organization's
security strategy. Using [Linux-PAM](http://tldp.org/HOWTO/User-Authentication-HOWTO/x115.html) and OPA
we can extend policy-based access control to SSH and sudo.
{% endcontentfor %}
@@ -21,15 +21,15 @@ policy-based access control to SSH and sudo.
## Goals
This example shows how you can use OPA and Linux-PAM to enforce fine-grained,
This tutorial shows how you can use OPA and Linux-PAM to enforce fine-grained,
host-level access controls over SSH and sudo.
Linux-PAM can be configured to delegate authorization decisions to plugins
(shared libraries). In this case, we have created an OPA-based plugin that can
be configured to authorize SSH and sudo access. The OPA-based Linux-PAM plugin
used in this example can be found at [open-policy-agent/contrib](https://github.com/open-policy-agent/contrib).
used in this tutorial can be found at [open-policy-agent/contrib](https://github.com/open-policy-agent/contrib).
For this example, our desired policy is:
For this tutorial, our desired policy is:
* Admins can SSH into any host and run sudo commands.
* Normal users can SSH into hosts that they have *contributed* to.
@@ -42,7 +42,7 @@ Furthermore, we'll assume we have the following set of users and hosts:
* `ops` is an administrator for the organization.
Authentication (verifying user identity) is outside the scope of OPA's
responsibility so this example relies on identities being statically
responsibility so this tutorial relies on identities being statically
defined. In real-world scenarios authentication can be delegated to SSH itself
(authorized_keys) or other identity management systems.
@@ -50,7 +50,7 @@ Let's get started.
## Prerequisites
This example requires [Docker Compose](https://docs.docker.com/compose/install/) to run dummy SSH hosts along
This tutorial requires [Docker Compose](https://docs.docker.com/compose/install/) to run dummy SSH hosts along
with OPA. The dummy SSH hosts are just containers running sshd inside.
## Steps
@@ -204,7 +204,7 @@ curl -X PUT localhost:8181/v1/data/hosts -d \
### 3. Prepare SSH key to login to hosts.
This example uses a special Docker image named `openpolicyagent/demo-pam` to simulate an SSH server. This image contains:
This tutorial uses a special Docker image named `openpolicyagent/demo-pam` to simulate an SSH server. This image contains:
1. Pre-created Linux accounts for our users.
2. Pre-populated authorized_keys files for our users.
site/examples/working-with-the-opa-repl/index.md → site/tutorials/working-with-the-opa-repl/index.md
+7 -7
View File
@@ -1,8 +1,8 @@
---
sort_order: 1000
nav_id: MAIN_EXAMPLES
xmp_id: WORKING_WITH_THE_OPA_REPL
layout: examples
nav_id: MAIN_TUTORIALS
tutorial_id: WORKING_WITH_THE_OPA_REPL
layout: tutorials
title: Working with the OPA REPL
---
@@ -19,7 +19,7 @@ REPLs are great for learning new languages and running quick experiments. You ca
## Goals
This example helps you get started with OPA's interactive shell or [REPL (read-eval-print loop)](https://en.wikipedia.org/wiki/Read–eval–print_loop)
This tutorial helps you get started with OPA's interactive shell or [REPL (read-eval-print loop)](https://en.wikipedia.org/wiki/Read–eval–print_loop)
To introduce the REPL, we will use dummy data and an example policy. In English, the policy can be stated as follows:
@@ -27,15 +27,15 @@ To introduce the REPL, we will use dummy data and an example policy. In English,
We will use the REPL to define rules that codify the policy stated above.
Once you finish this example, you will be familiar with:
Once you finish this tutorial, you will be familiar with:
* Running OPA as an interactive shell/REPL.
* Writing ad-hoc queries in [Rego](/docs/lang.html).
## Prerequisites
* This example requires that you have the latest version of OPA. You can download the latest version of OPA at [openpolicyagent.org](/get-opa/).
* This example assumes you have the OPA executable in your `$PATH`.
* This tutorial requires that you have the latest version of OPA. You can download the latest version of OPA at [openpolicyagent.org](/get-opa/).
* This tutorial assumes you have the OPA executable in your `$PATH`.
## Steps