diff --git a/docs/ecosystem/contributing.md b/docs/ecosystem/contributing.md index 6a8d2ab6d9..52abd9d86c 100644 --- a/docs/ecosystem/contributing.md +++ b/docs/ecosystem/contributing.md @@ -5,184 +5,208 @@ title: Contribute to Ory This document explains how you can contribute to Ory. -If have have ideas to improve it, please have a look at the[ main template](https://github.com/ory/docs/blob/master/docs/ecosystem/contributing.md). +If have have ideas to improve it, please have a look at the [template](https://github.com/ory/docs/blob/master/docs/ecosystem/contributing.md). ## Introduction -You can contribute in many ways beyond writing code. The goal of this document is to provide a high-level overview of how you can -get involved. +_Please note_: We take Ory's security and our users' trust very +seriously. If you believe you have found a security issue in Ory , +please disclose it by contacting us at security@ory.sh. -_Please note_: We are serious about Ory's security and our users' trust. If you believe you have found a security issue in Ory, -please disclose by contacting us at security@ory.sh. +There are many ways in which you can contribute. The goal of this document is to +provide a high-level overview of how you can get involved in Ory. -First: As a potential contributor, your changes and ideas are welcome at any hour of the day or night, weekdays, weekends, and -holidays. Please do not ever hesitate to ask a question or send a pull request. +As a potential contributor, your changes and ideas are welcome at any hour of +the day or night, on weekdays, weekends, and holidays. Please do not ever +hesitate to ask a question or send a pull request. -If you are unsure, just ask or submit the issue or pull request anyways. You won't be yelled at for giving it your best effort. -The worst that can happen is that you'll be asked to change something. We appreciate any sort of contributions, and don't want a -wall of rules to get in the way of that. +If you are unsure, just ask or submit the issue or pull request anyways. You +won't be yelled at for giving it your best effort. The worst that can happen is +that you'll be politely asked to change something. We appreciate any sort of +contributions and don't want a wall of rules to get in the way of that. -That said, if you want to ensure that a pull request is going to be merged, talk to us! You can find out our thoughts and ensure -that your contribution won't clash with Ory's normal direction. A great way to do this is via GitHub Discussions -(([Ory Network](https://github.com/ory/network/discussions), [Ory Kratos](https://github.com/ory/kratos/discussions), -[Ory Hydra](https://github.com/ory/kratos/discussions), [Ory Keto](https://github.com/ory/kratos/discussions), -[Ory Oathkeeper](https://github.com/ory/kratos/discussions))) or the [Ory Chat](https://www.ory.sh/chat). +That said, if you want to ensure that a pull request is likely to be merged, +talk to us! You can find out our thoughts and ensure that your contribution +won't clash with Ory's direction. A great way to +do this is via +[Ory Discussions](https://github.com/discussions?discussions_q=org%3Aory+sort%3Aupdated-desc) +or the [Ory Chat](https://www.ory.sh/chat). -## Frequently asked questions +## FAQ - I am new to the community. Where can I find the - [Ory Community Code of Conduct?](https://github.com/ory/kratos/blob/master/CODE_OF_CONDUCT.md) + [Ory Community Code of Conduct?](https://github.com/$REPOSITORY/blob/master/CODE_OF_CONDUCT.md) -- I have a question. Where can I get [answers to questions?](#communication) +- I have a question. Where can I get + [answers to questions regarding Ory?](#communication) -- I would like to contribute but I am not sure how. Are there [easy ways to contribute?](#how-can-i-contribute) +- I would like to contribute but I am not sure how. Are there + [easy ways to contribute?](#how-can-i-contribute) [Or good first issues?](https://github.com/search?l=&o=desc&q=label%3A%22help+wanted%22+label%3A%22good+first+issue%22+is%3Aopen+user%3Aory+user%3Aory-corp&s=updated&type=Issues) -- I want to talk to other Ory users. [How can I become a part of the community?](#communication) +- I want to talk to other Ory users. + [How can I become a part of the community?](#communication) -- I would like to know what I am agreeing to when I contribute to Ory. Does Ory have - [a Contributors License Agreement?](https://cla-assistant.io/ory/) +- I would like to know what I am agreeing to when I contribute to Ory + .Does Ory have + [a Contributors License Agreement?](https://cla-assistant.io/ory/kratos) - I would like updates about new versions of Ory. - [How are new releases announced?](https://ory.us10.list-manage.com/subscribe?u=ffb1a878e4ec6c0ed312a3480&id=f605a41b53) + [How are new releases announced?](https://www.ory.sh/l/sign-up-newsletter) ## How can I contribute? -If you want to start contributing code right away, we have a -[list of good first issues](https://github.com/ory/kratos/labels/good%20first%20issue). +If you want to start to contribute code right away, take a look at the +[list of good first issues](https://github.com/$REPOSITORY/labels/good%20first%20issue). -You can contribute without writing any code in multiple ways . Here are a few things you can do to help out: +There are many other ways you can contribute. Here are a few things you can do +to help out: -- **Give us a star.** It may not seem like much, but it really makes a difference. This is something that everyone can do to help - out Ory. Github stars help the project gain visibility and stand out. +- **Give us a star.** It may not seem like much, but it really makes a + difference. This is something that everyone can do to help out Ory. + Github stars help the project gain visibility and stand out. -- **Join the community.** Sometimes helping people can be as easy as listening to their problems and offering a different - perspective. Join our Slack, have a look at discussions on GitHub and take part in events like the Community Calls. More info on - this in [Communication](#communication). +- **Join the community.** Sometimes helping people can be as easy as listening + to their problems and offering a different perspective. Join our Slack, have a + look at discussions in the forum and take part in community events. More info + on this in [Communication](#communication). -- **Helping with open issues.** We have a lot of open issues for Ory and some of them may lack necessary information, some are - duplicates of older issues. You can help out by guiding people through the process of filling out the issue template, asking for - clarifying information, or pointing them to existing issues that match their description of the problem. +- **Answer discussions.** At all times, there are several unanswered discussions + on GitHub. You can see an + [overview here](https://github.com/discussions?discussions_q=is%3Aunanswered+org%3Aory+sort%3Aupdated-desc). + If you think you know an answer or can provide some information that might + help, please share it! Bonus: You get GitHub achievements for answered + discussions. -- **Reviewing documentation changes.** Most documentation just needs a review for proper spelling and grammar. If you think you - can improve a document in any way, feel free to hit the `edit` button at the top of the page. More info on contributing to - documentation [here](#documentation). +- **Help with open issues.** We have a lot of open issues for Ory and + some of them may lack necessary information, some are duplicates of older + issues. You can help out by guiding people through the process of filling out + the issue template, asking for clarifying information or pointing them to + existing issues that match their description of the problem. -- **Help with tests.** Some pull requests may lack proper tests or test plans. These are needed for the change to be implemented. +- **Review documentation changes.** Most documentation just needs a review for + proper spelling and grammar. If you think a document can be improved in any + way, feel free to hit the `edit` button at the top of the page. More info on + contributing to the documentation [here](#contribute-documentation). + +- **Help with tests.** Pull requests may lack proper tests or test plans. These + are needed for the change to be implemented safely. ## Communication -We use [Slack](https://www.ory.sh/chat). You are welcome to drop in and ask questions, discuss bugs and feature requests, talk to -other users of Ory, etc. +We use [Slack](https://www.ory.sh/chat). You are welcome to drop in and ask +questions, discuss bugs and feature requests, talk to other users of Ory, etc. -Check out discussions for [Ory Network](https://github.com/ory/network/discussions), -[Ory Kratos](https://github.com/ory/kratos/discussions), [Ory Hydra](https://github.com/ory/kratos/discussions), -[Ory Keto](https://github.com/ory/kratos/discussions), [Ory Oathkeeper](https://github.com/ory/kratos/discussions), and -[more](https://github.com/ory/kratos/discussions). This is a great place for in-depth discussions and lots of code examples, logs -and similar data. +Check out [Ory Discussions](https://github.com/discussions?discussions_q=org%3Aory+sort%3Aupdated-desc). This is a great place for +in-depth discussions and lots of code examples, logs and similar data. -You can also join our community hangout, if you want to speak to the Ory team directly or ask some questions. You can find more -info on the hangouts in [Slack](https://www.ory.sh/chat). +You can also join our community calls if you want to speak to the Ory team +directly or ask some questions. You can find more info and participate in +[Slack](https://www.ory.sh/chat) in the #community-call channel. -If you want to receive regular notifications about updates to Ory, consider joining the mailing list. We will _only_ send you -vital information on the projects that you are interested in. +If you want to receive regular notifications about updates to Ory, +consider joining the mailing list. We will _only_ send you vital information on +the projects that you are interested in. -Also [follow us on twitter](https://twitter.com/orycorp). +Also, [follow us on Twitter](https://twitter.com/orycorp). -## Conduct +## Contribute examples or community projects -Whether you are a regular contributor or a newcomer, we care about making this community a safe place for you and we've got your -back. +One of the most impactful ways to contribute is by adding code examples or other +Ory-related code. You can find an overview of community code in the +[awesome-ory](https://github.com/ory/awesome-ory) repository. -- We are committed to providing a friendly, safe and welcoming environment for all, regardless of gender, sexual orientation, - disability, ethnicity, religion, or similar personal characteristic. -- Please avoid using nicknames that might detract from a friendly, safe and welcoming environment for all. -- Be kind and courteous. Don't be mean or rude. -- We will exclude you from interaction if you insult, demean or harass anyone. In particular, we do not tolerate behavior that - excludes people in socially marginalized groups. -- Private harassment is also unacceptable. No matter who you are, if you feel you have been or are being harassed or made - uncomfortable by a community member, please contact a member of the Ory team. -- Likewise any spamming, trolling, flaming, baiting or other attention-stealing behavior is not welcome. +_If you would like to contribute a new example, we would love to hear from you!_ -We welcome discussion about creating a welcoming, safe, and productive environment for the community. If you have any questions, -feedback, or concerns [please let us know](https://www.ory.sh/chat). +Please [open a pull request at awesome-ory](https://github.com/ory/awesome-ory/) +to add your example or Ory-related project to the awesome-ory README. -## Contributing Code +## Contribute code -Unless you are fixing a known bug, we **strongly** recommend discussing it with the core team via a GitHub issue or -[in our chat](https://www.ory.sh/chat) before getting started to ensure your work is consistent with Ory's road map and -architecture. +Unless you are fixing a known bug, we **strongly** recommend discussing it with +the core team via a GitHub issue or [in our chat](https://www.ory.sh/chat) +before getting started to ensure your work is consistent with Ory's +roadmap and architecture. -All contributions are made via pull requests. To make a pull request, you will need a GitHub account; if you are unclear on this -process, see GitHub's documentation on [forking](https://help.github.com/articles/fork-a-repo) and -[pull requests](https://help.github.com/articles/using-pull-requests). Pull requests should be targeted at the `master` branch. -Before creating a pull request, go through this checklist: +All contributions are made via pull requests. To make a pull request, you will +need a GitHub account; if you are unclear on this process, see GitHub's +documentation on [forking](https://help.github.com/articles/fork-a-repo) and +[pull requests](https://help.github.com/articles/using-pull-requests). Pull +requests should be targeted at the `master` branch. Before creating a pull +request, go through this checklist: 1. Create a feature branch off of `master` so that changes do not get mixed up. -1. [Rebase](http://git-scm.com/book/en/Git-Branching-Rebasing) your local changes against the `master` branch. -1. Run the full project test suite with the `go test -tags sqlite ./...` (or equivalent) command and confirm that it passes. -1. Run `make format` if a `Makefile` is available, `gofmt -s` if the project is written in Go, `npm run format` if the project is - written for Node.js. -1. Ensure that each commit has a descriptive prefix. This ensures a uniform commit history and helps structure the changelog. - Please refer to this [list of prefixes for Kratos](https://github.com/ory/kratos/blob/master/.github/semantic.yml) for an - overview. -1. Sign-up with CircleCI so that it has access to your repository with the branch containing your PR. Simply creating a CircleCI - account is sufficient for the CI jobs to run, you do not need to setup a CircleCI project for the branch. +1. [Rebase](http://git-scm.com/book/en/Git-Branching-Rebasing) your local + changes against the `master` branch. +1. Run the full project test suite with the `go test -tags sqlite ./...` (or + equivalent) command and confirm that it passes. +1. Run `make format` +1. Add a descriptive prefix to commits. This ensures a uniform commit history + and helps structure the changelog. Please refer to this + [Convential Commits configuration](https://github.com/$REPOSITORY/blob/master/.github/workflows/conventional_commits.yml) + for the list of accepted prefixes. You can read more about the Conventional + Commit specification + [at their site](https://www.conventionalcommits.org/en/v1.0.0/). If a pull request is not ready to be reviewed yet [it should be marked as a "Draft"](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request). Before your contributions can be reviewed you need to sign our -[Contributor License Agreement](https://cla-assistant.io/ory/kratos). +[Contributor License Agreement](https://cla-assistant.io/$REPOSITORY). -This agreement defines the terms under which your code is contributed to Ory. More specifically it declares that you have the -right to, and actually do, grant us the rights to use your contribution. You can see the Apache 2.0 license under which our -projects are published [here](https://github.com/ory/meta/blob/master/LICENSE). +This agreement defines the terms under which your code is contributed to Ory. +More specifically it declares that you have the right to, and actually do, grant +us the rights to use your contribution. You can see the Apache 2.0 license under +which our projects are published +[here](https://github.com/ory/meta/blob/master/LICENSE). -When pull requests fail testing, authors are expected to update their pull requests to address the failures until the tests pass. +When pull requests fail the automated testing stages (for example unit or E2E +tests), authors are expected to update their pull requests to address the +failures until the tests pass. Pull requests eligible for review 1. follow the repository's code formatting conventions; -2. include tests which prove that the change works as intended and does not add regressions; +2. include tests that prove that the change works as intended and does not add + regressions; 3. document the changes in the code and/or the project's documentation; 4. pass the CI pipeline; -5. have signed our [Contributor License Agreement](https://cla-assistant.io/ory/kratos); +5. have signed our + [Contributor License Agreement](https://cla-assistant.io/$REPOSITORY); 6. include a proper git commit message following the [Conventional Commit Specification](https://www.conventionalcommits.org/en/v1.0.0/). -If all of these items are checked, the pull request is ready to be reviewed and you should change the status to "Ready for review" -and +If all of these items are checked, the pull request is ready to be reviewed and +you should change the status to "Ready for review" and [request review from a maintainer](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review). Reviewers will approve the pull request once they are satisfied with the patch. -## Documentation - -Please provide documentation when changing, removing, or adding features. Documentation resides in the -[Ory docs repository](https://github.com/ory/docs/tree/master/docs) folder. +## Contribute documentation -For further instructions please head over to [docs/README.md](https://github.com/ory/docs/blob/master/README.md). +Please provide documentation when changing, removing, or adding features. All +Ory Documentation resides in the +[Ory documentation repository](https://github.com/ory/docs/). For further +instructions please head over to the Ory Documentation +[README.md](https://github.com/ory/docs/blob/master/README.md). ## Disclosing vulnerabilities -Please disclose vulnerabilities to [security@ory.sh](mailto:security@ory.sh). Do not use GitHub issues. +Please disclose vulnerabilities exclusively to +[security@ory.sh](mailto:security@ory.sh). Do not use GitHub issues. -## Code Style +## Code style -Please follow these guidelines when formatting source code: +Please run `make format` to format all source code following the Ory standard. -- Go code should match the output of `gofmt -s` and pass `golangci-lint run`. -- Format Node.js and JavaScript code using `npm run format` where appropriate. +### Working with forks -### Working with Forks - -```shell +```bash # First you clone the original repository -git clone git@github.com:ory/ory/kratos.git +git clone git@github.com:ory/$REPOSITORY.git # Next you add a git remote that is your fork: -git remote add fork git@github.com:/ory/kratos.git +git remote add fork git@github.com:/$REPOSITORY.git # Next you fetch the latest changes from origin for master: git fetch origin @@ -202,459 +226,13 @@ git push -u fork my-feature-branch Now go to the project's GitHub Pull Request page and click "New pull request" -This document is a work in progress and documents the inner workings of the Ory GitHub ecosystem and project structures, as well -as providing more in-depth tips & guides to contributors. If you feel there is something missing or should be added, please open -an issue in [ory/docs](https://github.com/ory/docs) or contact us in the [Ory Chat](https://www.ory.sh/chat). We also offer -discussions on GitHub for all major projects: [Ory Kratos](https://github.com/ory/kratos/discussions), -[Ory Hydra](https://github.com/ory/hydra/discussions), [Ory Keto](https://github.com/ory/keto/discussions), -[Ory Oathkeeper](https://github.com/ory/oathkeeper/discussions/), as well as one for all other Ory projects, events and content: -[Ory Meta discussions](https://github.com/ory/meta/discussions). - -## Releasing Software - -To release a project, run the following bash command in the root of the project you would like to release. The first argument can -be one of: - -- `patch` bumps `v1.2.3` to `v1.2.4` (doesn't work for pre-releases such as `v1.2.3-beta.1`) -- `minor` bumps `v1.2.3` to `v1.3.0` (doesn't work for pre-releases such as `v1.2.3-beta.1`) -- `major` bumps `v1.2.3` to `v2.0.0` (doesn't work for pre-releases such as `v1.2.3-beta.1`) -- Any [semver-valid](https://semver.org) version, for example `v1.2.3-beta.1` - -```shell script -release_as=v1.2.3 -bash <(curl -s https://raw.githubusercontent.com/ory/meta/master/scripts/release.sh) $release_as -``` - -### Defining Release Config - -For the scripts to work, the project must be located in a directory structure that reflects the GitHub organization and repository -name, for example: `path/to/ory/hydra`. - -#### Goreleaser - -We use [goreleaser](https://github.com/goreleaser/goreleaser/releases). - -The listed configuration options should be included in every `.goreleaser.yml` config. Make sure you set env vars and -`go mod download` and run e.g. packr2 and other tools first: - -```yaml title=".goreleaser.yml" -env: - - GO111MODULE=on - -before: - hooks: - - go mod download - # - go install github.com/gobuffalo/packr/v2/packr2 - # - packr2 -``` - -Tag `-alpha.1` and other pre-release tags as pre-release on GitHub: - -```yaml -release: - prerelease: auto -``` - -Name snapshot releases `-next`: - -```yaml -snapshot: - name_template: "{{ .Tag }}-_next" -``` - -If you create a new goreleaser config, you may also want to create the following empty GitHub repositories: - -Build and publish on Docker. You need to create a repository on Docker Hub first! - -```yaml -# Build dockerfiles -dockers: - - dockerfile: Dockerfile - binaries: - - $PROJECT_NAME - image_templates: - - "oryd/$PROJECT_NAME:v{{ .Major }}" - - "oryd/$PROJECT_NAME:v{{ .Major }}.{{ .Minor }}" - - "oryd/$PROJECT_NAME:v{{ .Major }}.{{ .Minor }}.{{ .Patch }}" - - "oryd/$PROJECT_NAME:latest" -``` - -If you add [Scoop](https://scoop.sh) (Homebrew for Windows) you must also create a GitHub repository under the `ory` org named -`scoop-$PROJECT_NAME` (e.g. `scoop-hydra`). - -```yaml -scoop: - bucket: - owner: ory - name: scoop-$PROJECT_NAME - homepage: https://www.ory.sh - commit_author: - name: aeneasr - email: aeneas@ory.sh -``` - -If you add [Homebrew](https://brew.sh) you must also create a GitHub repository under the `ory` org named `homebrew-$PROJECT_NAME` -(e.g. `homebrew-hydra`). - -```yaml -brews: - - github: - owner: ory - name: homebrew-$PROJECT_NAME - ids: - - <> - homepage: https://www.ory.sh - commit_author: - name: aeneasr - email: aeneas@ory.sh -``` - -We use the following replacements: - -```yaml -archives: - - replacements: - darwin: macOS - 386: 32-bit - amd64: 64-bit - format_overrides: - - goos: windows - format: zip -``` - -### Update install script - -When you have finalized changes to the `.goreleaser.yml`, run: - -```shell -GO111MODULES=off go get -u github.com/goreleaser/godownloader -godownloader .goreleaser.yml --repo=$(basename $(dirname $(pwd)))/$(basename $(pwd)) > ./install.sh -``` - -## CI - -[Ory CI](http://github.com/ory/ci): - -### ory/nancy - -Enables nancy vulnerability scanning for the repository. - -```yml -orbs: - nancy: ory/nancy@0.0.9 - -workflows: - test: - jobs: - - nancy/test: - filters: - tags: - only: /.*/ -``` - -## Toolchain - -### Checking for vulnerabilities - -#### Node.js - -This is done automatically by GitHub - -#### Go - -```go -# Outside of a go module-enabled project: - go get -u github.com/sonatype-nexus-community/nancy - -# Inside your go module-enabled project: - go mod list -m all | nancy -``` - -### Pinning indirect go module dependencies - -Sometimes a project has an indirect dependency (another dependency requires that dependency) which doesn't pass, for example, -`nancy` vulnerability scanning. Because it's not possible to pin this dependency to a specific version, we need to explicitly -require it. But because it's not directly required by our code, it will be pruned when using `go mod tidy`. To prevent that, -create a file which imports the dependency without use: - -```title="go_mod_indirect_pins.go -// +build go_mod_indirect_pins - -package main - -import _ "github.com/my/dependency" -``` - -You would do the same if the project uses dev tools such as `packr2`, `goimports`, `goreturns`, `swagutil`, ... as part of e.g. -the Makefile or other scripts. - -## Development - -### DBAL gobuffalo/pop - -#### Table Names - -Please define custom table names for all table structs. Keep in mind that `TableName()` must be a value receiver, not a pointer -receiver, for slices `[]Model` to work properly: - -```diff --func (m *Model) TableName(ctx context.Context) string { -+func (m Model) TableName(ctx context.Context) string { - return "foo" -} -``` - -### SQL Migrations - -Ory uses a lightweight DBAL across all projects that require a database. This DBAL is typically stored in the `persistence/` -directory. Since we just support SQL at the moment - there are no plans to add new databases and contributions won't be accepted -due to maintenance effort - you will find the implementation in `persistence/sql`. - -:::info - -This section just applies to Ory Kratos and Ory Keto. Ory Hydra is using an approach that doesn't rely on fizz migrations. Please -discuss with maintainers before making changes to the Ory Hydra SQL schemata. - -::: - -In order to provide a process to upgrade SQL schemata, we use migrations. These migrations are generated using the -[fizz language](https://github.com/gobuffalo/fizz) and then rendered to SQL using the Ory CLI. - -This is necessary because there are differences between the SQL "dialects" of SQLite (doesn't support certain `ALTER TABLE` -statements for example), PostgreSQL, MySQL, and CockroachDB. - -To change the schema, create a new fizz template using: - -```shell -# In the project root - e.g. /kratos - make .bin/ory - -# If make .bin/ory fails use: -# make .bin/cli -# -# and replace `.bin/ory` with `.bin/cli`. -# We're working on streamlining this -# across all repos. - - .bin/ory dev pop migration create persistence/sql/migrations/templates descriptive_change -``` - -This will create two new files: - -```shell - ls -la persistence/sql/migrations/templates | tail -n 2 --rw-r--r-- 1 foobar staff 0 Apr 28 17:25 20210428172500_descriptive_change.down.fizz --rw-r--r-- 1 foobar staff 0 Apr 28 17:25 20210428172500_descriptive_change.up.fizz -``` - -Add you fizz migrations there. The `up` file is for applying your schema changes, the `down` file for reverting them. - -Once your migrations are added, it's time to render them to SQL. Make sure that Docker is running and execute: - -```shell - .bin/ory dev pop migration render persistence/sql/migrations/templates persistence/sql/migrations/sql -``` - -If you encounter errors you can also try running this with the `--replace` option but please let maintainers know that you used -`--replace` in your PR: - -```shell - .bin/ory dev pop migration render --replace persistence/sql/migrations/templates persistence/sql/migrations/sql -``` - -This will render your migrations to SQL files. Add them to git (`git add -A`) and commit them. - -Next, you need to update the migration tests. To do so, run the sync command: - -```shell - .bin/ory dev pop migration sync persistence/sql/migrations/templates persistence/sql/migratest/testdata -``` - -This will add create a new SQL file: - -```shell - ls -la persistence/sql/migratest/testdata | tail -n 1 --rw-r--r-- 1 foobar staff 0 Apr 28 17:28 20210428172500_testdata.sql -``` - -Add an `INSERT` or `UPDATE` or `DELETE` statement that reflects the changes you have made to the schema to the file. Let's say you -added a new column `new_column` to table `bar`. In that case, write an `INSERT` statement that reflects this: - -```sql -INSERT INTO bar (old_column, new_column) VALUES ('foo', 'bar'); -``` - -Next, execute the tests: - -```go -cd persistence/sql/migratest -go test -tags sqlite ./... -``` - -The tests will probably fail because the fixtures need to be updated. To update them, run: - -```go -cd persistence/sql/migratest -go test -tags sqlite,refresh -short . -``` - -You might need to run the `go test` command two or three times before all fixtures have been updated. - -That's it! :) - -## OpenAPI Spec and Go Swagger - -We use [go-swagger](https://goswagger.io) to generate OpenAPI Spec from source code. Here you can find conventions we use across -the code base. - -### Models - -Models should have a descriptive title, a body, and be camelCase. It's good practice to scope the model where needed. - -```go -package some - -// Title -// -// A description with a trailing dot. -// -// swagger:model someSpecificModel -type SpecificModel struct {} -``` - -### Routes - -Routes should use tags for versioning. If a route is accessible through a privileged port (e.g. admin) it should be prefixed with -`admin`. - -```go -// swagger:route POST /identities v0alpha1 adminCreateIdentity -``` - -Public endpoints don't need a prefix. - -```go -// swagger:route POST /something-public v0alpha1 somethingPublic -``` - -#### Parameters - -Parameters for routes should have the same name as the route. If they have a body, you must not use an embedded struct and the -struct's model name should be suffixed `Body`: - -```go - -// swagger:parameters adminCreateIdentity -// nolint:deadcode,unused -type adminCreateIdentity struct { - // in: body - Body adminCreateIdentityBody -} - -// swagger:model adminCreateIdentityBody -type adminCreateIdentityBody struct { - // SchemaID is the ID of the JSON Schema to be used for validating the identity's traits. - // - // required: true - SchemaID string `json:"schema_id"` - - // Traits represent an identity's traits. The identity is able to create, modify, and delete traits - // in a self-service manner. The input will always be validated against the JSON Schema defined - // in `schema_url`. - // - // required: true - Traits json.RawMessage `json:"traits"` -} - -// swagger:route POST /identities v0alpha1 adminCreateIdentity -``` - -#### Responses - -Where possible use models for responses. - -```shell -// A list of identities. -// swagger:model identityList -// nolint:deadcode,unused -type identityList []Identity - -// swagger:route GET /identities v0alpha0 adminListIdentities -// -// List Identities -// -// Lists all identities. Doesn't support search at the moment. -// -// Learn how identities work in [Ory Kratos' User And Identity Schema Documentation](https://www.ory.sh/docs/next/kratos/concepts/identity-user-model). -// -// Produces: -// - application/json -// -// Schemes: http, https -// -// Responses: -// 200: identityList -// 500: jsonError -``` - -## IDE Tips - -### Goland - -#### Goland Tests - -While running tests inside the IDE make sure you have the tag `-tags sqlite` in the "Go Tool Arguments". In the example screenshot -we're looking at `login_test.go` and add it to the Run/Debug Configurations. - -![Go Tool Arguments Configuration Screenshot](./_static/contributing/goland-config.png) - -### Jetbrains - -#### Debugging Tests - -Jetbrains IDEs have an SQL debugger, that can open sqlite files. When debugging tests, you can set a bool flag to use an sqlite -file instead of in-mem and then debug after the test failed. -[Example](https://github.com/ory/keto/pull/638/files#diff-19d74043bd6f4fd4ffaf6dee2895a42da0a754b6135339343117614974ff6182R84): - -```go -func GetSqlite(t testing.TB, mode sqliteMode) *DsnT { - dsn := &DsnT{ - MigrateUp: true, - MigrateDown: false, - } - - switch mode { - case SQLiteMemory: - dsn.Name = "memory" - dsn.Conn = fmt.Sprintf("sqlite://file:%s?_fk=true&cache=shared&mode=memory", t.Name()) - case SQLiteFile: - t.Cleanup(func() { - _ = os.Remove("TestDB.sqlite") - }) - fallthrough - case SQLiteDebug: - dsn.Name = "sqlite" - dsn.Conn = "sqlite://file:TestDB.sqlite?_fk=true" - } - - return dsn -} -``` - -![Screenshot of Jetbrains SQL debugger, Fast!](./_static/contributing/jetbrains-config.png) - -To transfer the above to Kratos: - -- Change the DSN to the following: `dsn.Conn = "sqlite://file:TestDB.sqlite?_fk=true"`. -- `mode=memory`. -- In case you have an sqlite file, migrators aren't automatically applied. Run them manually first with the - [CLI](https://www.ory.sh/kratos/docs/cli/kratos-migrate-sql). +## Conduct -### VS Code +Whether you are a regular contributor or a newcomer, we care about making this +community a safe place for you and we've got your back. -#### VS Code Tests +[Ory Community Code of Conduct](https://github.com/$REPOSITORY/blob/master/CODE_OF_CONDUCT.md) -- Under Settings, search for `Go: Test Tags`. -- Click Edit in `settings.json`. ![Screenshot of VSCode Search](./_static/contributing/vscode-search.png) -- Add the following KV to the `settings.json`: `"go.testTags": "sqlite",`. - ![Screenshot of VScode settings.json](./_static/contributing/vscode-settings.png) +We welcome discussion about creating a welcoming, safe, and productive +environment for the community. If you have any questions, feedback, or concerns +[please let us know](https://www.ory.sh/chat). \ No newline at end of file diff --git a/docs/getting-started/integrate-auth/35_react-native.mdx b/docs/getting-started/integrate-auth/35_react-native.mdx index 06a4d26918..dea22ab388 100644 --- a/docs/getting-started/integrate-auth/35_react-native.mdx +++ b/docs/getting-started/integrate-auth/35_react-native.mdx @@ -19,8 +19,7 @@ This guide is perfect for you if: :::info -You can find the code of the sample application [here](https://github.com/ory/kratos-selfservice-ui-react-native). The application -is also available to download from the [Apple App Store](https://apps.apple.com/pl/app/ory-profile-app/id1536546333). +You can find the code of the sample application [here](https://github.com/ory/kratos-selfservice-ui-react-native). ::: diff --git a/docs/getting-started/ory-network-oauth2.mdx b/docs/getting-started/ory-network-oauth2.mdx index acda791f28..068458cde2 100644 --- a/docs/getting-started/ory-network-oauth2.mdx +++ b/docs/getting-started/ory-network-oauth2.mdx @@ -6,9 +6,9 @@ sidebar_label: Try it # Try common OAuth2 Grants -[Ory OAuth2 & OpenID Connect](https://www.ory.sh/federated-identity-management/) (based on -[Ory Hydra](https://github.com/ory/hydra)) is available in the Ory Network out of the box. This means that you can use OIDC, -Authorization Code Grant, Client Credentials Grant, and more, without additional configuration. +[Ory OAuth2 & OpenID Connect](https://www.ory.sh/hydra) (based on [Ory Hydra](https://github.com/ory/hydra)) is available in the +Ory Network out of the box. This means that you can use OIDC, Authorization Code Grant, Client Credentials Grant, and more, +without additional configuration. Following this guide allows you to experience the most commonly used OAuth2 flows and see how they work in Ory Network. The examples will take you through the following steps: diff --git a/docs/hydra/guides/cors.mdx b/docs/hydra/guides/cors.mdx index 2c493a0632..b401bca8d7 100644 --- a/docs/hydra/guides/cors.mdx +++ b/docs/hydra/guides/cors.mdx @@ -4,7 +4,7 @@ title: Setting up cross-origin resource sharing (CORS) --- Both Ory Hydra's Admin and Public endpoints support CORS. For detailed information, head over to the exemplary -[config file](https://github.com/ory/hydra/blob/master/docs/config.yaml). +[config file](https://github.com/ory/hydra/blob/master/.schema/config.schema.json). For CORS to work properly, we encourage to set the following values: diff --git a/docs/hydra/self-hosted/hsm-support.md b/docs/hydra/self-hosted/hsm-support.md index 8acf34e53e..6be63902af 100644 --- a/docs/hydra/self-hosted/hsm-support.md +++ b/docs/hydra/self-hosted/hsm-support.md @@ -133,44 +133,8 @@ Public Key Object; RSA 4096 bits ## Testing with SoftHSM -[SoftHSM](https://www.opendnssec.org/softhsm/) is an implementation of a cryptographic store accessible through a PKCS #11 -interface. You can use it to explore PKCS#11 without having a Hardware Security Module. It's being developed as a part of the -OpenDNSSEC project. - -[Follow these instructions to build SoftHSM from source.](https://wiki.opendnssec.org/display/SoftHSMDOCS/SoftHSM+Documentation+v2) - -### Install SoftHSM/OpenSC on Mac OSX - -```sh -ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" 2> /dev/null -``` - -```sh -brew install softhsm -``` - -```sh -ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" 2> /dev/null -``` - -```sh -brew install opensc -``` - -### Install SoftHSM/OpenSC on Ubuntu - -```sh -sudo apt update -``` - -```sh -sudo apt install softhsm opensc -``` - -### Install SoftHSM/OpenSC on Windows - -Follow these instructions to install [SoftHSM](https://github.com/disig/SoftHSM2-for-Windows) and -[OpenSC](https://github.com/OpenSC/OpenSC/wiki) on windows. +[SoftHSM](https://www.softhsm.org/) is an implementation of a cryptographic store accessible through a PKCS #11 interface. You can +use it to explore PKCS#11 without having a Hardware Security Module. It's being developed as a part of the OpenDNSSEC project. ### Run Ory Hydra with HSM using Docker diff --git a/docs/kratos/organizations/organizations.mdx b/docs/kratos/organizations/organizations.mdx index 50e786a812..d19f3aebbf 100644 --- a/docs/kratos/organizations/organizations.mdx +++ b/docs/kratos/organizations/organizations.mdx @@ -389,48 +389,3 @@ local claims = std.extVar('claims'); }, } ``` - -### SAML via BoxyHQ - -:::note - -Previously a third party integration provided SAML SSO in Ory Network. The third party BoxyHQ integration is still supported for -backwards compatibility, but the native SAML support in Ory Network is recommended for new projects. Please contact us -[Ory Support](mailto:support@ory.sh) for any questions. - -::: - -#### Prerequisites - -Before proceeding, ensure you have the following: - -- Access to [Ory Network](https://console.ory.sh/) -- An active account with [BoxyHQ](https://app.eu.boxyhq.com/auth/join) -- [Ory CLI](../../guides/cli/installation) - -#### Configuration - -To set up the integration, you'll need to get your Ory Network session token: - -- [Install the Ory CLI](../../guides/cli/installation) on your system. -- Run `ory auth` to sign into your Ory Network account. -- Locate the session token in the `.ory-cloud.json` file in your home folder. This token starts with the prefix `ory_st`. You can - use `cat ~/.ory-cloud.json | grep 'ory_st'` to find it. - -You'll also need your Ory Project ID. You can find this in your -[Ory Network settings](https://console.ory.sh/projects/current/settings). - -Next, you'll configure the session token and Project ID in BoxyHQ. - -Follow these steps: - -- Log into your [BoxyHQ account](https://app.boxyhq.com/). -- Create a new Product if you haven't already. -- Navigate to Settings > Ory Integration. -- Paste your session token and Project ID into the respective input fields and save the configuration. - -Once configured, the integration between BoxyHQ and Ory Network will automatically set up a new Organization and a generic OIDC -connection whenever you create a new SSO connection on BoxyHQ. All user management will then flow through Ory Network. - -To verify the integration, navigate to your Ory Account Experience UI and enter an email associated with the domain you -configured. If successful, the "Sign in with SSO" button should appear. diff --git a/docs/kratos/social-signin/60_twitch.mdx b/docs/kratos/social-signin/60_twitch.mdx index cd16b8718a..3702175a97 100644 --- a/docs/kratos/social-signin/60_twitch.mdx +++ b/docs/kratos/social-signin/60_twitch.mdx @@ -39,10 +39,9 @@ Follow these steps to add Twitch as a social sign-in provider to your project us :::info - [Twitch provides an OIDC discovery URL](https://accounts.Twitch.com/.well-known/openid-configuration), but it doesn't support - the `openid` claim and returns an `access_token` only. Ory sends requests to - [Twitch's /me API](https://developer.Twitch.com/documentation/web-api/reference/#/operations/get-current-users-profile) and - adds the user info to `std.extVar('claims')`. + [Twitch provides an OIDC discovery URL](https://id.twitch.tv/oauth2/.well-known/openid-configuration), but it doesn't support + the `openid` claim and returns an `access_token` only. Ory sends requests to Twitch's /me API and adds the user info to + `std.extVar('claims')`. ::: diff --git a/docs/kratos/social-signin/70_yandex.mdx b/docs/kratos/social-signin/70_yandex.mdx index 2cf10ce793..c9f4e30dcc 100644 --- a/docs/kratos/social-signin/70_yandex.mdx +++ b/docs/kratos/social-signin/70_yandex.mdx @@ -8,7 +8,7 @@ sidebar_label: Yandex Follow these steps to add Yandex as a social sign-in provider to your project using the Ory CLI: -1. [Create a Yandex OAuth2 Application](https://yandex.com/dev/oauth/doc/dg/tasks/register-client.html). +1. [Create a Yandex OAuth2 Application](https://yandex.com/dev/id/doc/en/register-client). 2. In the created app, set the redirect URI to: ```shell @@ -33,9 +33,8 @@ Follow these steps to add Yandex as a social sign-in provider to your project us :::info - [Yandex](https://yandex.com/dev/oauth/doc/dg/concepts/about.html) returns an `access_token` but doesn't return an `id_token`. - Ory sends requests to [Yandex's API](https://yandex.com/dev/passport/doc/dg/reference/request.html) and adds the user info to - `std.extVar('claims')`. + [Yandex](https://yandex.com/dev/id/doc/en/) returns an `access_token` but doesn't return an `id_token`. Ory sends requests to + Yandex's API and adds the user info to `std.extVar('claims')`. ::: diff --git a/docs/oathkeeper/index.md b/docs/oathkeeper/index.md index 6e3ed44511..16073f2b3b 100644 --- a/docs/oathkeeper/index.md +++ b/docs/oathkeeper/index.md @@ -15,8 +15,8 @@ While Ory Oathkeeper works well with Ory OAuth2 & OpenID Connect (Ory Hydra) and and alongside other stacks with adjacent problem domains (Keycloak, Gluu, Vault). Ory Oathkeeper's Access Control Decision API works with -- [Ambassador](https://github.com/datawire/ambassador) via - [auth service](https://www.getambassador.io/reference/services/auth-service) +- [Emissary-ingress](https://github.com/emissary-ingress/emissary) via + [auth service](https://www.getambassador.io/docs/edge-stack/latest/topics/running/services/auth-service) - [Envoy](https://www.envoyproxy.io) via the [External Authorization HTTP Filter](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/security/ext_authz_filter.html) - AWS API Gateway via diff --git a/docs/open-source/guidelines/rest-api-guidelines.md b/docs/open-source/guidelines/rest-api-guidelines.md index 83b63e51f4..b2e8d43d69 100644 --- a/docs/open-source/guidelines/rest-api-guidelines.md +++ b/docs/open-source/guidelines/rest-api-guidelines.md @@ -10,7 +10,7 @@ Generator. This document standardizes Ory's V1 API contract. Ory has an established API and SDK generation system consisting of four parts: -1. Extraction of code comments from Go Code using [Go Swagger](https://goswagger.io/generate/spec.html) +1. Extraction of code comments from Go Code using [Go Swagger](https://goswagger.io/go-swagger/generate-spec/) ([example](https://github.com/ory/kratos/blob/bd4af9ab9f872b5dacf6e7abaf2cad5ffc83ddd6/Makefile#L89-L93)); 2. Conversion of Swagger 2.0 to OpenAPI Spec 3.0 and applying JsonPatch documents to improve the OpenAPI 3.0 file ([example](https://github.com/ory/kratos/blob/bd4af9ab9f872b5dacf6e7abaf2cad5ffc83ddd6/Makefile#L96-L109)); @@ -53,7 +53,7 @@ This section discusses how Ory uses OpenAPI 3.0. ### Routes Routes are the functions of an RPC infrastructure and are annotated using -[`swagger:route`](https://goswagger.io/use/spec/route.html): +[`swagger:route`](https://goswagger.io/go-swagger/reference/annotations/route/): ```go // swagger:route [method] [path pattern] [?tag1 tag2 tag3] [operation id] diff --git a/docs/polis/container-signing.mdx b/docs/polis/container-signing.mdx index 573fc5ae34..85aec9ddef 100644 --- a/docs/polis/container-signing.mdx +++ b/docs/polis/container-signing.mdx @@ -9,7 +9,7 @@ Ory Polis container images are signed and can be verified using [cosign](https:/ ## Fetching public key You can use [oras](https://oras.land) (or a similar OCI artifacts tool) to fetch the public key or download it from the website -[here](https://ory.sh/.well-known/cosign.pub). +[here](https://boxyhq.com/.well-known/cosign.pub). ```bash oras pull ghcr.io/boxyhq/cosign.pub:latest diff --git a/docs/security-model.mdx b/docs/security-model.mdx index 6e4b6a2e50..fc990247d5 100644 --- a/docs/security-model.mdx +++ b/docs/security-model.mdx @@ -164,7 +164,7 @@ To learn how to use Session to JWT, read the [Session to JWT documentation](./id ## Can I use OAuth 2.0 / OpenID Connect? Ory is fully compliant with OAuth 2.0 and OpenID Connect. If you are interested to use OAuth 2.0 / OpenID Connect for advanced use -cases, check out [Ory OAuth 2.0 and OpenID](https://www.ory.sh/federated-identity-management/) documentation. +cases, check out [Ory OAuth 2.0 and OpenID](https://www.ory.sh/hydra) documentation. :::tip @@ -175,13 +175,13 @@ for you. ::: At Ory, we believe that OAuth 2.0 and OpenID Connect isn't a one-size-fits-all solution. In fact, we think that you probably don't -need to use such complicated protocols at all! We recommend using -[Ory OAuth2 & OpenID](https://www.ory.sh/federated-identity-management/) for targeted use cases only, such as providing -third-party integration with your application (for example, in the form of the familiar "Sign in with [PROVIDER_NAME]" button). +need to use such complicated protocols at all! We recommend using [Ory OAuth2 & OpenID](https://www.ory.sh/hydra) for targeted use +cases only, such as providing third-party integration with your application (for example, in the form of the familiar "Sign in +with [PROVIDER_NAME]" button). ## What about access tokens / refresh tokens? -You can generate access and refresh tokens using [Ory OAuth2 & OpenID](https://www.ory.sh/federated-identity-management/). We do -not recommend using access and refresh tokens for session management! Visit +You can generate access and refresh tokens using [Ory OAuth2 & OpenID](https://www.ory.sh/hydra). We do not recommend using access +and refresh tokens for session management! Visit [ Why you probably do not need OAuth2 / OpenID Connect](https://www.ory.sh/oauth2-openid-connect-do-you-need-use-cases-examples/) to read more about it. diff --git a/src/components/ConfigMarkdown/index.tsx b/src/components/ConfigMarkdown/index.tsx index 5e83a54e83..60485c82fe 100644 --- a/src/components/ConfigMarkdown/index.tsx +++ b/src/components/ConfigMarkdown/index.tsx @@ -236,7 +236,7 @@ export default function ConfigMarkdown(props: { src: string; binary: string }) {

To find out more about edge cases like setting string array values - through environmental variables head to the + through environmental variables head to the{" "} Configuration section.