docs: update and enhance oidc documentation #2142

georglauterbach · 2021-07-02T11:41:48Z

Since there is no PR template - strangely enough - I will use the one we use over at docker-mailserver/docker-mailserver. Feel free to copy it :).

Description

This PR enhances, extends and updates the OIDC section in the documentation. Changes include

updated descriptions of the individual options when configuring OIDC options
added some examples and encouraged readers to participate (making it easier for everyone to find information about their application)
updated options to explain how to create them
added small hints for K8s
added a "Currently Tested Applications" heading to show what is currently worked on (shall be expanded in the future)

Context: #189

Type of change

Improvement (non-breaking change that does improve existing functionality)
This change is a documentation update

Checklist:

My code follows the style guidelines of this project
I have performed a self-review of my own code
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation (README.md or the documentation under docs/)
If necessary I have added tests that prove my fix is effective or that my feature works
New and existing unit tests pass locally with my changes

authelia · 2021-07-02T11:41:51Z

Thanks for choosing to contribute @georglauterbach. We lint all PR's with golangci-lint and eslint, I may add a review to your PR with some suggestions.

You are free to apply the changes if you're comfortable, alternatively you are welcome to ask a team member for advice.

Artifacts

These changes once approved by a team member will be published for testing on Buildkite, DockerHub and GitHub Container Registry.

Docker Container

docker pull authelia/authelia:PR2142
docker pull ghcr.io/authelia/authelia:PR2142

georglauterbach · 2021-07-02T11:43:06Z

Not sure whether there is a documentation preview set up for this project. If there is, please provide me with a link so I can have a look at a deployed version myself. Please have an maintainer label this accordingly and put it into the OIDC project :)

PS: Sorry for the force-push (I know, it's discouraged). Had to do it because of the GPG signature (changed recently and wasn't updated properly).

…dc-docs

james-d-elliott · 2021-07-02T12:09:02Z

PS: Sorry for the force-push (I know, it's discouraged). Had to do it because of the GPG signature (changed recently and wasn't updated properly).

No worries! We mainly prefer it to keep a reasonable history of the progression of a PR if necessary.

Not sure whether there is a documentation preview set up for this project. If there is, please provide me with a link so I can have a look at a deployed version myself. Please have an maintainer label this accordingly and put it into the OIDC project :)

There currently isn't, but we have a JTD testing area which I can push these changes to and you can see how it looks. We're probably going to have to discuss some of these changes internally since they differ from a thorough configuration doc restyle recently. I'm about to sleep so will take a closer look in about 9 hours.

georglauterbach · 2021-07-02T12:16:09Z

There currently isn't, but we have a JTD testing area which I can push these changes to and you can see how it looks.

SGTM 👍🏼

We're probably going to have to discuss some of these changes internally since they differ from a thorough configuration doc restyle recently. I'm about to sleep so will take a closer look in about 9 hours.

Alright, I already anticipated that there is some sort of style guideline. I may have overlooked them. But of course, these changes are open for discussion. Just reach back to me :)

james-d-elliott · 2021-07-02T21:01:52Z

https://authelia.github.io/jtd-test/?random=1231278978744

Here's a preview of that page with some easy to notice differences. Grafana has also been tested and works as expected.

georglauterbach · 2021-07-02T23:18:10Z

https://authelia.github.io/jtd-test/?random=1231278978744

Here's a preview of that page with some easy to notice differences. Grafana has also been tested and works as expected.

Nice! I noticed some small mistakes that I will correct soon. Won‘t have time on the weekend though. Reach back to me if there are style adjustments or things you’d like to see changed. I will most likely be able to correct them on Monday.

docs/configuration/identity-providers/oidc.md

Co-authored-by: Clément Michaud <clement.michaud34@gmail.com>

codecov · 2021-07-05T09:20:52Z

Codecov Report

Merging #2142 (4a70cde) into master (907680c) will increase coverage by 0.09%.
The diff coverage is n/a.

❗ Current head 4a70cde differs from pull request most recent head fffca37. Consider uploading reports for the commit fffca37 to get more accurate results

@@            Coverage Diff             @@
##           master    #2142      +/-   ##
==========================================
+ Coverage   69.63%   69.73%   +0.09%     
==========================================
  Files         176      176              
  Lines        5148     5148              
  Branches      200      200              
==========================================
+ Hits         3585     3590       +5     
+ Misses       1287     1282       -5     
  Partials      276      276

Flag	Coverage Δ
backend	`71.47% <ø> (ø)`
frontend	`62.24% <ø> (+0.51%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
web/src/hooks/IntermittentClass.ts	`82.35% <0.00%> (+29.41%)`	⬆️

georglauterbach · 2021-07-06T16:41:23Z

@james-d-elliott @clems4ever Ready for review with suggestions incorporated. I know that the command / pipe for creating the secrets (especially in K8s) seems overkill, but this solution does not rely on openssl but only on standard Linux programs / files. I can add the openssl command back in if you would like to see that too (again), but I prefer urandom | tr | base64 over openssl rand -base64 | base64.

georglauterbach · 2021-07-11T15:05:54Z

Resolved the conflicts, this is ready again to be merged :)

james-d-elliott · 2021-07-11T20:22:58Z

Resolved the conflicts, this is ready again to be merged :)

Thanks! I'll take a look today. We've all been very busy sorry.

james-d-elliott

Mostly LGTM, few suggestions.

docs/community/oidc-integrations.md

docs/configuration/identity-providers/oidc.md

nightah

There's a small typo in your latest update.

docs/configuration/identity-providers/oidc.md

docs/configuration/secrets.md

Co-authored-by: Amir Zarrinkafsh <nightah@me.com>

Co-authored-by: James Elliott <james-d-elliott@users.noreply.github.com>

georglauterbach · 2021-07-12T09:32:53Z

Thanks for the type hint @nightah. @james-d-elliott I incorporated your suggestions :)

clems4ever

I like the changes you've made so far!
Only few tiny remaining things to fix.

docs/community/oidc-integrations.md

docs/configuration/identity-providers/oidc.md

docs/configuration/secrets.md

docs/faq.md

Co-authored-by: Clément Michaud <clement.michaud34@gmail.com>

clems4ever

LGTM

james-d-elliott

LGTM! ~~just need to merge master into it so we can merge this. Typically we recommend people give us access when they create a PR (so we can easily merge), though it's not required.~~ Cancel that, you did give us access.

james-d-elliott · 2021-07-14T00:08:03Z

docs/configuration/identity-providers/oidc.md

 default: 30d
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>

-The maximum lifetime of a refresh token. This should typically be slightly more the other token lifespans. This is 


Not sure why the comment about how long the token should be was removed. However I can just add it back later in another paragraph. Other than that LGTM!

georglauterbach changed the title ~~update and enhance OIDC documentation~~ [OIDC/docs] Update and enhance OIDC documentation Jul 2, 2021

georglauterbach and others added 4 commits July 2, 2021 13:59

update and enhance OIDC documentation

a5b5339

Merge branch 'master' into update-oidc-docs

d19d70b

Merge branch 'master' into update-oidc-docs

a97d065

Merge remote-tracking branch 'origin/update-oidc-docs' into update-oi…

9c71384

…dc-docs

nightah changed the title ~~[OIDC/docs] Update and enhance OIDC documentation~~ docs: update and enhance oidc documentation Jul 3, 2021

Merge branch 'master' into update-oidc-docs

23580da

clems4ever requested changes Jul 3, 2021

View reviewed changes

clems4ever reviewed Jul 3, 2021

View reviewed changes

docs/configuration/identity-providers/oidc.md Outdated Show resolved Hide resolved

clems4ever reviewed Jul 3, 2021

View reviewed changes

docs/configuration/identity-providers/oidc.md Outdated Show resolved Hide resolved

georglauterbach and others added 2 commits July 5, 2021 11:02

Update docs/configuration/identity-providers/oidc.md

1694d8b

Co-authored-by: Clément Michaud <clement.michaud34@gmail.com>

Update docs/configuration/identity-providers/oidc.md

4a70cde

Co-authored-by: Clément Michaud <clement.michaud34@gmail.com>

georglauterbach added 2 commits July 5, 2021 11:37

updateddocs according to @clems4ever's suggestions

fffca37

Merge branch 'master' into update-oidc-docs

109dcfe

georglauterbach requested a review from clems4ever July 5, 2021 09:57

georglauterbach added 2 commits July 5, 2021 14:26

add tr command in pipe to remove newline which could cause confusion

4b27c4b

a bit of Bash fetishism

7380e74

georglauterbach added 3 commits July 6, 2021 18:53

Merge branch 'master' into update-oidc-docs

2a0909b

Merge branch 'master' into update-oidc-docs

365216c

Merge branch 'master' into update-oidc-docs

4c33b6a

james-d-elliott reviewed Jul 11, 2021

View reviewed changes

nightah requested changes Jul 11, 2021

View reviewed changes

docs/configuration/identity-providers/oidc.md Outdated Show resolved Hide resolved

docs/configuration/secrets.md Outdated Show resolved Hide resolved

georglauterbach and others added 5 commits July 12, 2021 11:14

Update docs/configuration/identity-providers/oidc.md

862ba89

Co-authored-by: Amir Zarrinkafsh <nightah@me.com>

Update docs/configuration/secrets.md

6063ba6

Co-authored-by: Amir Zarrinkafsh <nightah@me.com>

Update docs/community/oidc-integrations.md

0711d2d

Co-authored-by: James Elliott <james-d-elliott@users.noreply.github.com>

Update docs/community/oidc-integrations.md

226e7c7

Co-authored-by: James Elliott <james-d-elliott@users.noreply.github.com>

incorporated suggestions

f4009f9

clems4ever requested changes Jul 12, 2021

View reviewed changes

georglauterbach and others added 11 commits July 13, 2021 11:05

Update docs/configuration/identity-providers/oidc.md

5b18300

Co-authored-by: Clément Michaud <clement.michaud34@gmail.com>

Update docs/configuration/identity-providers/oidc.md

041810c

Co-authored-by: Clément Michaud <clement.michaud34@gmail.com>

Update docs/configuration/identity-providers/oidc.md

0e28050

Co-authored-by: Clément Michaud <clement.michaud34@gmail.com>

Update docs/configuration/identity-providers/oidc.md

5f3c274

Co-authored-by: Clément Michaud <clement.michaud34@gmail.com>

Update docs/configuration/identity-providers/oidc.md

6745134

Co-authored-by: Clément Michaud <clement.michaud34@gmail.com>

Update docs/configuration/identity-providers/oidc.md

bc26b21

Co-authored-by: Clément Michaud <clement.michaud34@gmail.com>

Update docs/configuration/identity-providers/oidc.md

744cd45

Co-authored-by: Clément Michaud <clement.michaud34@gmail.com>

Update docs/configuration/secrets.md

bd81219

Co-authored-by: Clément Michaud <clement.michaud34@gmail.com>

Update docs/faq.md

5113aa8

Co-authored-by: Clément Michaud <clement.michaud34@gmail.com>

replace all old links

1fb000c

Merge branch 'master' into update-oidc-docs

3c8e993

georglauterbach requested review from james-d-elliott, clems4ever and nightah July 13, 2021 09:09

clems4ever approved these changes Jul 13, 2021

View reviewed changes

Merge branch 'master' into update-oidc-docs

bf0af03

james-d-elliott approved these changes Jul 14, 2021

View reviewed changes

james-d-elliott merged commit 9d7cfb8 into authelia:master Jul 14, 2021

georglauterbach deleted the update-oidc-docs branch July 14, 2021 07:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: update and enhance oidc documentation #2142

docs: update and enhance oidc documentation #2142

georglauterbach commented Jul 2, 2021

authelia bot commented Jul 2, 2021

georglauterbach commented Jul 2, 2021 •

edited

Loading

james-d-elliott commented Jul 2, 2021

georglauterbach commented Jul 2, 2021

james-d-elliott commented Jul 2, 2021 •

edited

Loading

georglauterbach commented Jul 2, 2021 •

edited

Loading

codecov bot commented Jul 5, 2021 •

edited

Loading

georglauterbach commented Jul 6, 2021 •

edited

Loading

georglauterbach commented Jul 11, 2021 •

edited

Loading

james-d-elliott commented Jul 11, 2021

james-d-elliott left a comment

nightah left a comment

georglauterbach commented Jul 12, 2021

clems4ever left a comment

clems4ever left a comment

james-d-elliott left a comment •

edited

Loading

james-d-elliott Jul 14, 2021

docs: update and enhance oidc documentation #2142

docs: update and enhance oidc documentation #2142

Conversation

georglauterbach commented Jul 2, 2021

Description

Type of change

Checklist:

authelia bot commented Jul 2, 2021

Artifacts

Docker Container

georglauterbach commented Jul 2, 2021 • edited Loading

james-d-elliott commented Jul 2, 2021

georglauterbach commented Jul 2, 2021

james-d-elliott commented Jul 2, 2021 • edited Loading

georglauterbach commented Jul 2, 2021 • edited Loading

codecov bot commented Jul 5, 2021 • edited Loading

Codecov Report

georglauterbach commented Jul 6, 2021 • edited Loading

georglauterbach commented Jul 11, 2021 • edited Loading

james-d-elliott commented Jul 11, 2021

james-d-elliott left a comment

Choose a reason for hiding this comment

nightah left a comment

Choose a reason for hiding this comment

georglauterbach commented Jul 12, 2021

clems4ever left a comment

Choose a reason for hiding this comment

clems4ever left a comment

Choose a reason for hiding this comment

james-d-elliott left a comment • edited Loading

Choose a reason for hiding this comment

james-d-elliott Jul 14, 2021

Choose a reason for hiding this comment

georglauterbach commented Jul 2, 2021 •

edited

Loading

james-d-elliott commented Jul 2, 2021 •

edited

Loading

georglauterbach commented Jul 2, 2021 •

edited

Loading

codecov bot commented Jul 5, 2021 •

edited

Loading

georglauterbach commented Jul 6, 2021 •

edited

Loading

georglauterbach commented Jul 11, 2021 •

edited

Loading

james-d-elliott left a comment •

edited

Loading