From d8834d91761fd8898ece241185c087ca26c7cb40 Mon Sep 17 00:00:00 2001 From: Eric Tune Date: Thu, 25 Aug 2016 09:30:56 -0700 Subject: [PATCH] Expand OIDC docs. --- docs/admin/authentication.md | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/docs/admin/authentication.md b/docs/admin/authentication.md index b4f7d8c639..bbceb4f818 100644 --- a/docs/admin/authentication.md +++ b/docs/admin/authentication.md @@ -45,8 +45,13 @@ with the request: All values are opaque to the authentication system and only hold significance when interpreted by an [authorizer](/docs/admin/authorization/). -Multiple authentication methods may be enabled at once. In these cases, the first -authenticator to successfully authenticate the request short-circuits evaluation. +You can enable multiple authentication methods at once. You should usually use at least two methods: + + - service account tokens for service accounts + - at least one other method for user authentication. + +When multiple are enabled, the first authenticator module +to successfully authenticate the request short-circuits evaluation. The API server does not guarantee the order authenticators run in. ### X509 Client Certs @@ -189,7 +194,9 @@ verify ID token's signature and determine the end users identity. To enable the plugin, pass the following required flags: * `--oidc-issuer-url` URL of the provider which allows the API server to discover -public signing keys. Only URLs which use the `https://` scheme are accepted. +public signing keys. Only URLs which use the `https://` scheme are accepted. This is typically +the provider's URL without a path, for example "https://accounts.google.com" or "https://login.salesforce.com". + * `--oidc-client-id` A client id that all tokens must be issued for. Importantly, the API server is not an OAuth2 client, rather it can only be @@ -212,6 +219,17 @@ other claims, such as `email`, depending on their provider. * `--oidc-groups-claim` JWT claim to use as the user's group. If the claim is present it must be an array of strings. +Kubernetes does not provide an OpenID Connect Identity Provider. +You can use an existing public OpenID Connect Identity Provider (such as Google, or [others](http://connect2id.com/products/nimbus-oauth-openid-connect-sdk/openid-connect-providers)). +Or, you can run your own Identity Provider, such as CoreOS [dex](https://github.com/coreos/dex), [Keycloak](https://github.com/keycloak/keycloak) or CloudFoundary [UAA](https://github.com/cloudfoundry/uaa). + +The provider needs to support [OpenID connect discovery]https://openid.net/specs/openid-connect-discovery-1_0.html); not all do. + +Setup instructions for specific systems: + +- [UAA]: http://apigee.com/about/blog/engineering/kubernetes-authentication-enterprise +- [Dex]: https://speakerdeck.com/ericchiang/kubernetes-access-control-with-dex + ### Webhook Token Authentication Webhook authentication is a hook for verifying bearer tokens.