diff --git a/README.md b/README.md index ec2c1fcb3..2d63141b5 100644 --- a/README.md +++ b/README.md @@ -12,25 +12,6 @@ Pomerium can be used to: - aggregate access logs and telemetry data. - a **VPN alternative**. -## Architecture - -pomerium architecture diagram - -## Demo - -To make this a bit more concrete, see the following: - -1. An **unauthorized** user authenticating with their corporate single-sign-on provider (in this case Google) -2. The **unauthorized** user being blocked from a protected resource. -3. The **unauthorized** user signing out from their session. -4. An **authorized** user authenticating with their corporate single-sign-on provider. -5. Pomerium delegating and grating access to the requested resource. -6. The **authorized** user inspecting their user details including group membership. - - - ## Docs For comprehensive docs, and tutorials see our [documentation]. diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 7cc2d96b4..9c5f7d459 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -22,16 +22,8 @@ module.exports = { lastUpdated: "Last Updated", nav: [ { text: "Documentation", link: "/docs/" }, + { text: "Recipes", link: "/recipes/" }, { text: "Community", link: "/community/" } - - // { - // text: "Versions", - // items: [ - // { text: "v0.1.0", link: "https://v0-1-0.docs.pomerium.io/" }, - // { text: "v0.0.5", link: "https://v0-0-5.docs.pomerium.io/" }, - // { text: "v0.0.4", link: "https://v0-0-4.docs.pomerium.io/" } - // ] - // } ], sidebar: { @@ -104,6 +96,16 @@ module.exports = { "security" ] } + ], + "/recipes/": [ + { + title: "Recipes", + type: "group", + + collapsable: false, + sidebarDepth: 1, + children: ["", "vs-code-server"] + } ] } } diff --git a/docs/.vuepress/theme/styles/index.styl b/docs/.vuepress/theme/styles/index.styl index 316359f43..2ffb25bd5 100644 --- a/docs/.vuepress/theme/styles/index.styl +++ b/docs/.vuepress/theme/styles/index.styl @@ -68,7 +68,9 @@ body border-radius 4px img - max-width 100% + display: block; + margin: 0 auto; + max-width 92% {$contentClass}.custom padding 0 diff --git a/docs/community/contributing.md b/docs/community/contributing.md index b6337e8a2..86371f4e8 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -11,7 +11,7 @@ You can have a direct impact on the project by helping with its code or document ## Code -We hold contributions to a high standard for quality :bowtie:, so don't be surprised if we ask for revisions--even if it seems small or insignificant. Please don't take it personally. :wink: If your change is on the right track, we can guide you to make it mergable. +We try to hold contributions to a high standard for quality, so don't be surprised if we ask for revisions--even if it seems small or insignificant. Please don't take it personally. If your change is on the right track, we can guide you to make it mergable. Here are some of the expectations we have of contributors: diff --git a/docs/docs/reference/examples/config/config.visual-studio-code.yaml b/docs/docs/reference/examples/config/config.visual-studio-code.yaml new file mode 100644 index 000000000..d74ba29e5 --- /dev/null +++ b/docs/docs/reference/examples/config/config.visual-studio-code.yaml @@ -0,0 +1,15 @@ +# See detailed configuration settings : https://www.pomerium.io/reference/ +authenticate_service_url: https://authenticate.corp.domain.example +authorize_service_url: https://authorize.corp.domain.example + +# identity provider settings : https://www.pomerium.io/docs/identity-providers.html +idp_provider: google +idp_client_id: REPLACE_ME +idp_client_secret: REPLACE_ME + +policy: + - from: https://code.corp.domain.example + to: http://codeserver:8443 + allowed_users: + - some.user@domain.example + allow_websockets: true diff --git a/docs/recipes/img/vscode-helloworld.png b/docs/recipes/img/vscode-helloworld.png new file mode 100644 index 000000000..cc8a2ce5d Binary files /dev/null and b/docs/recipes/img/vscode-helloworld.png differ diff --git a/docs/recipes/img/vscode-pomerium.png b/docs/recipes/img/vscode-pomerium.png new file mode 100644 index 000000000..a1f8e856c Binary files /dev/null and b/docs/recipes/img/vscode-pomerium.png differ diff --git a/docs/recipes/readme.md b/docs/recipes/readme.md new file mode 100644 index 000000000..e26a08235 --- /dev/null +++ b/docs/recipes/readme.md @@ -0,0 +1,3 @@ +# Overview + +This section contains applications, and scenario specific guides for Pomerium. diff --git a/docs/recipes/vs-code-server.md b/docs/recipes/vs-code-server.md new file mode 100644 index 000000000..fb7f12ae1 --- /dev/null +++ b/docs/recipes/vs-code-server.md @@ -0,0 +1,108 @@ +--- +title: VS Code Server +lang: en-US +meta: + - name: keywords + content: pomerium identity-access-proxy visual-studio-code visual studio code authentication authorization +description: >- + This guide covers how to add authentication and authorization to a hosted, fully, online instance of visual studio code. +--- + +# Securing Visual Studio Code Server + +## Background + +This guide covers using Pomerium to secure an instance of [Visual Studio Code Server]. Pomerium is an identity-aware access proxy that can add single-sign-on / access control to any service, including visual studio code. + +### Visual Studio Code + +[Visual Studio Code] is an open source code editor by Microsoft that has become [incredibly popular](https://insights.stackoverflow.com/survey/2019#technology-_-most-popular-development-environments) in the last few years. For many developers, [Visual Studio Code] hits the sweet spot between no frills editors like vim/emacs and full feature IDE's like Eclipse and IntelliJ. VS Code offers some of the creature comforts like intellisense, git integration, and plugins, while staying relatively lightweight. + +One of the interesting attributes of [Visual Studio Code] is that it is built on the [Electron]() framework which uses a headless instance of Chrome rendered as a desktop application. It didn't take long for folks to realize that if we already had this great IDE written in Javascript, it may be possible to make [Visual Studio Code] run remotely. + +> "Any application that can be written in JavaScript, will eventually be written in JavaScript." — [Jeff Atwood](https://blog.codinghorror.com/the-principle-of-least-power/) + +### VS Code Server + +[Visual Studio Code Server] is an open-source project that allows you to run [Visual Studio Code] on a **remote** server, through the browser. For example, this is a screenshot taken at the end of this tutorial. + +![visual studio code building pomerium](./img/vscode-pomerium.png) + +## Pre-requisites + +This guide assumes you have already completed one of the [quick start] guides, and have a working instance of Pomerium up and running. For purpose of this guide, I'm going to use docker-compose, though any other deployment method would work equally well. + +## Configure + +### Pomerium Config + +<<< @/docs/docs/reference/examples/config/config.visual-studio-code.yaml + +### Docker-compose + +```yaml +codeserver: + image: codercom/code-server:latest + restart: always + ports: + - 8443:8443 + volumes: + - ./code-server:/home/coder/project + command: --allow-http --no-auth --disable-telemetry +``` + +Note we are mounting a directory called`./code-server`. Be sure to give the default docker user write permissions to that folder by running `chown -R 1000:1000 code-server/`. + +### That's it! + +Simply navigate to your domain (e.g. `https://code.corp.domain.example`). + +![visual studio code pomerium hello world](./img/vscode-helloworld.png) + +### (Example) Develop Pomerium in Pomerium + +As a final touch, now that we've done all this work we might as well use our new development environment to write some real, actual code. And what better project is there than Pomerium? 😉 + +To build Pomerium, we must [install go](https://golang.org/doc/install) which is as simple as running the following commands in the [integrated terminal]. + +```bash +wget https://dl.google.com/go/go1.12.7.linux-amd64.tar.gz +sudo tar -C /usr/local -xzf go1.12.7.linux-amd64.tar.gz +``` + +Then add Go to our [PATH]. + +```bash +# add the following to $HOME/.bashrc +export PATH=$PATH:/usr/local/go/bin +export PATH=$PATH:$(go env GOPATH)/bin +``` + +Reload [PATH] by opening the [integrated terminal] and sourcing the updated `.bashrc` file. + +```bash +source $HOME/.bashrc +``` + +Finally, now that we've got Go all we need to go is grab the latest source and build. + +```bash +# get the latest source +$ git clone https://github.com/pomerium/pomerium.git +# grab make +$ sudo apt-get install make +# build pomerium +$ make build +# run pomerium! +$ ./bin/pomerium --version +v0.2.0+e1c00b1 +``` + +Happy remote hacking!!!😁 + +[visual studio code server]: https://github.com/cdr/code-server +[visual studio code]: https://code.visualstudio.com/ +[synology nas]: ../docs/quick-start/synology.md +[quick start]: ../docs/quick-start +[integrated terminal]: https://code.visualstudio.com/docs/editor/integrated-terminal +[path]: https://en.wikipedia.org/wiki/PATH_(variable)