Let's improve the docs!

[aeneasr]

It's awesome to see how Hydra is attracting more and more users, and that we're seeing production deployments pop up! We are really close to releasing the 1.0.0 version (officially stable) as we are observing a steadily declining bug report frequency.

One large issue still open is the documentation. OAuth2 can be very overwhelming and the consent flow is an additional complexity people have to understand. The policy concept adds another mandatory "you have to understand this".

I would like to ask you, the community, what problems you faced when you first read the docs. Maybe you have ideas to improve that? Or better examples?

You could even create a PR - the docs are here. To run them, do:

npm i -g gitbook-cli
gitbook serve -http

To do

• document all special scopes (offline, hydra, openid)
• example with force-consent scope (maybe @waynerobinson could help here)
• write walkthrough for GKE
• document groups

[ysaakpr]

How the warden groups are getting used. I could not find any kind of document related to that. is it related to something the policy subjects .

For example : if subject: "user:1" is belong to group admin
and a policy with subject "group:admin" will allow warden request if the subject is "user:1"

[ysaakpr]

And informations about limitations while using Different Storage implementation.
Which DB supports all features ? Even though RethinkDB which hydra uses by default I did see that few functionalities wont works in RethinkDB and Redis.

Any performance benchmark against using different supported storage (out of this scope, but still will be very helpful for people to decide on what and why to choose hydra with specific storage...again its up to user)
It will be very good to suggest whats suggested storage for hydra, and limitations of using other storage.

[aeneasr]

Even though RethinkDB which hydra uses by default I did see that few functionalities wont works in RethinkDB and Redis.

RethinkDB is not the default storage, MySQL and Postgres are the only officialy supported and maintained adapters.

Any performance benchmark against using different supported storage

Good idea!

[aeneasr]

Outline for blog post on deploying hydra on google container engine with google cloud sql, follow up to
#330 (comment)

THIS IS WORK IN PROGRESS! The idea is to have a guide that is specifically targeted at kubernetes, but also includes some general advice on getting hydra up and running.

Notes

• Don't use : in client ids as it will trip basic auth (see so)

Setting up GCE and GCSQL

Pretty straight forward, maybe include screens.

• Allow GCE to access SQL: https://cloud.google.com/sql/docs/mysql/connect-container-engine
• Make sure the database exists

Setting up pods

Hydra

hydra.deploy.yaml

Setting log level to debug helps finding bugs. We use http because of tls edge termination (could be more sophisticated). Also note that replicas could be anything.

apiVersion: v1
kind: Deployment
metadata:
  name: hydra
spec:
  replicas: 1
  template:
    metadata:
      labels:
        service: hydra
    spec:
      containers:
      - env:
        - name: LOG_LEVEL
          value: debug
        - name: CONSENT_URL
          value: !!!!!!!!!!!!!!!!!! TO BE DONE !!!!!!!!!!!!!!!!!!!!!!
        image: oryd/hydra:v0.7.7-http
        name: hydra
        resources: {}
      restartPolicy: Always
status: {}

hydra.secret.yaml

apiVersion: v1
kind: Secret
metadata:
  name: hydra
type: Opaque
data:
  SYSTEM_SECRET: somesecret
  DATABASE_URL: !!!!!!!!!!!!!!!!!! TO BE DONE !!!!!!!!!!!!!!!!!!!!!!
  FORCE_ROOT_CLIENT_CREDENTIALS: !!!!!!!!!!!!!!!!!! TO BE DONE !!!!!!!!!!!!!!!!!!!!!!

Consent app

consent.deploy.yaml

TO BE DONE

Deploy secrets & pods

kubectl apply -f hydra.deploy.yaml

Configure hydra

Consent app client

Create

Policies

Resource provider client

Create

Policies

Third-party OAuth2 client

Create

Policies

Protect resource provider

Perform auth code flow

[therebelrobot]

One thing I found was missing documentation on what type of authorization header was needed when swapping out the authorization code for access or refresh token, I finally landed on a base64'd client_id:client_secret (or maybe it was documented somewhere else?)

[therebelrobot]

Also, the format of multiple scopes in the cli, I tried scope1 scope2 scope3, then scope1|scope2|scope3, and finally landed on scope1,scope2,scope3

[therebelrobot]

List and explanation of the available grant types would be extremely helpful, still not sure what every single one does yet.

[therebelrobot]

Also, sometimes when searching in the docs, the page freezes and needs to be killed... kinda weird.

[aeneasr]

Thanks for the feedback, I'll try to incorporate the feedback as best as possible. The freezing pages are unfortunately out of my control :/

By the way, you can always create a PR for the docs, they're located here: https://github.com/ory/hydra/tree/master/docs

[Moggers]

I would like some documentation on the different policy resources and their meanings. What clients should and should not be given access to to complete the different auth flows.