Skip to content

Update session secret doc #281

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
adellape merged 1 commit into from
Apr 8, 2015
Merged

Update session secret doc #281

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 24 additions & 7 deletions architecture/authentication.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -262,7 +262,11 @@ oauthConfig:

=== Session options

The OAuth server uses a cookie-based session during login and redirect flows.
The OAuth server uses a signed and encrypted cookie-based session during login and redirect flows.

If no `sessionSecretsFile` is specified, a random signing and encryption secret is generated at each start of the master server. This means that any logins in progress will have their sessions invalidated if the master is restarted. It also means that if multiple masters are configured, they will not be able to decode sessions generated by one of the other masters.

To specify the signing and encryption secret to use, specify a `sessionSecretsFile`. This allows you separate secret values from the config file, and keep the config file distributable for debugging, etc.

Master config:
----
Expand All @@ -271,12 +275,25 @@ oauthConfig:
sessionConfig:
sessionMaxAgeSeconds: 300 <1>
sessionName: ssn <2>
sessionSecrets: <3>
- authentication: ... <4>
encryption: ... <5>
sessionSecretsFile: "..." <3>
----
<1> Controls the maximum age of a session (sessions auto-expire once a token request is complete). If auto-grant is not enabled, sessions must last as long as the user is expected to take to approve or reject a client authorization request.
<2> Name of the cookie used to store the session.
<3> List of secrets used to authenticate and encrypt cookie sessions. Multiple secrets are allowed to enable rotation.
<4> Signing secret, used to authenticate sessions using HMAC. Recommended to use a secret with 32 or 64 bytes.
<5> Encrypting secret, used to encrypt sessions. Must be 16, 24, or 32 characters long, to select AES-128, AES-192, or AES-256.
<3> Filename containing serialized SessionSecrets object. If empty, a random signing and encryption secret is generated at each server start.

Multiple secrets can be specified in the `sessionSecretsFile` to enable rotation. New sessions are signed and encrypted using the first secret in the list. Existing sessions are decrypted/authenticated by each secret until one succeeds.

Session secret config:
----
apiVersion: v1
kind: SessionSecrets
secrets: <1>
- authentication: "..." <2>
encryption: "..." <3>
- authentication: "..."
encryption: "..."
...
----
<1> List of secrets used to authenticate and encrypt cookie sessions. At least one secret must be specified. Each secret must set an authentication and encryption secret.
<2> Signing secret, used to authenticate sessions using HMAC. Recommended to use a secret with 32 or 64 bytes.
<3> Encrypting secret, used to encrypt sessions. Must be 16, 24, or 32 characters long, to select AES-128, AES-192, or AES-256.