Tectonic Identity docs revision #33

zbwright · 2017-09-22T21:44:09Z

I'm taking a pretty heavily editorial pass through all existing Tectonic Identity docs. I've rearranged all content, created some new pages, and combined others, and renamed all the files for clarity. This PR, and this new folder, will become the new 'User Management' docs on the site. We'll remove all the old docs.

robszumski · 2017-10-06T00:14:06Z

Documentation/users/creating-accounts.md

+1. Select the access level for the Role Binding:
+ * *Namespace Role Bindings* grant access only within the listed namespace.
+ * *Cluster-wide Role Bindings* grant access across the Tectonic cluster.
+While a Cluster Role may be bound down the hierarchy to a Namespace Role Binding, a Namespace Role can't be promoted up the hierarchy to be bound to a Cluster Role Binding.


I think we can strike this completely. It's more confusing that it seems and it makes sense when you are looking at real data in the UI for roles you have created.

robszumski · 2017-10-06T00:14:28Z

Documentation/users/creating-accounts.md

+ * *Cluster-wide Role Bindings* grant access across the Tectonic cluster.
+While a Cluster Role may be bound down the hierarchy to a Namespace Role Binding, a Namespace Role can't be promoted up the hierarchy to be bound to a Cluster Role Binding.
+what does that mean? - beth
+Namespace users and groups have read-access to Pods. Admins have full control over all resources. (is that true? read-only? - beth)


what are you referencing here?

robszumski · 2017-10-06T00:43:10Z

Documentation/users/creating-accounts.md

+
+## Removing Access
+
+Changes to a Role or Role Binding will take place immediately. Revoking access to a user may not be fully complete until the user's session token expires. The default expriation time is 24 hours.


need to check on this

robszumski · 2017-10-06T00:53:26Z

Documentation/users/creating-roles.md

+
+## Assign Users to Roles
+
+To grant your users access to Roles, [use a Role Binding][insert].


insert link

robszumski · 2017-10-06T00:53:34Z

Documentation/users/creating-roles.md

+
+Once the Role is created, click its *Name* in the *Roles* page, then click *Add Rule* to open the *Create Access Rule* page.
+
+<Create Access Rule page>


i assume this is an image?

yah - I removed it. Had it there just for me to look at while I was listing out all the options. I don't think the image of that page is valuable.

robszumski · 2017-10-06T01:19:38Z

Documentation/users/creating-service-accounts.md

+  namespace: default
+```
+
+Read up on how [create a roles][create-roles] and create a [Role Binding][insert] to associate it with your Service Account.


joshix · 2017-10-11T19:25:17Z

related: #13

robszumski · 2017-10-11T19:25:45Z

Documentation/users/tectonic-identity-config.md

+To add a static user, update the Tectonic Identity `ConfigMap` with a new `staticPasswords` entry.
+
+```yaml
+    staticPasswords:


incorrect indention

robszumski · 2017-10-11T19:25:53Z

Documentation/users/tectonic-identity-config.md

+To change the password of an existing user, generate a bcrypt hash for the new password (using [coreos/bcrypt-tool](https://github.com/coreos/bcrypt-tool/releases/tag/v1.0.0)) and add this value to the Tectonic Identity `ConfigMap` for the selected user.
+
+```yaml
+    staticPasswords:


incorrect indention

robszumski · 2017-10-11T19:26:15Z

Documentation/users/saml-integration.md

+Replace `example.com` with your IdP domain name, and `tectonic-domain` with your Tectonic domain name.
+
+```yaml
+  connectors:


incorrect indention

ericchiang

left a bunch of comments. Sorry for taking so long to review this.

ericchiang · 2017-10-11T22:40:30Z

Documentation/users/creating-accounts.md

+## Using kubectl to create ClusterRoleBindings
+
+`ClusterRoles` grant access to types of objects in any namespace in the cluster. Tectonic offers three default `ClusterRoles`:
+* user


Can we switch the for the upstream roles https://kubernetes.io/docs/admin/authorization/rbac/#user-facing-roles

* view * edit * admin * cluster-admin

yes. when these options are exposed in Console, we'll switch to whatever it lists, if necessary.

ericchiang · 2017-10-11T22:41:17Z

Documentation/users/creating-accounts.md

+Then, use kubectl to apply the `ClusterRoleBinding` RBAC resource definition, and create the account:
+
+```
+$ kubectl create -f user admin-test.yaml


you've got a extra user here should be

kubectl create -f admin-test.yaml

ericchiang · 2017-10-11T22:43:12Z

Documentation/users/creating-accounts.md

+
+```yaml
+kind: ClusterRoleBinding
+apiVersion: rbac.authorization.k8s.io/v1alpha1


please switch this to

rbac.authorization.k8s.io/v1beta1

ericchiang · 2017-10-11T22:43:37Z

Documentation/users/creating-accounts.md

+
+```
+$ kubectl create -f user admin-test.yaml
+user "admin-test" created


This would be

$ kubectl create -f admin-test.yaml clusterrolebinding "admin-test" created

ericchiang · 2017-10-11T22:44:51Z

Documentation/users/creating-roles.md

+  namespace: default
+rules:
+  - apiGroups:
+      - ''


nit: add a comment here explaining why the empty string is used

rules: - apiGroups: - '' # '' means the core API group.

ericchiang · 2017-10-11T23:10:54Z

Documentation/users/rbac-config.md

+
+A Role Binding can reference both Roles and Cluster Roles to grant permissions to resources. This allows administrators to define a set of common roles for the entire cluster, then reuse them within multiple namespaces. For example, the `view` Cluster Role referred to in the following Role Binding grants read-only permission to `[email protected]` but denies access to that user in the `kube-system` namespace.
+
+(this doesn't make sense, given the example - beth)


Maybe

For examplem creating a Role Binding in the dev namespace that binds a user to the edit Cluster Role won't have any impact outside of the dev namespace, even though it references a Cluster Role.

Diagrams might help

ericchiang · 2017-10-11T23:11:59Z

Documentation/users/saml-integration.md

+
+The table below describes the parameters that configure Tectonic Identity federation with IdPs:
+
+question: are these platform agnostic? in which case, i want to pull them from here, and add them to tectonic-identity-config.md - beth


These are platform agnostic but really cryptic. Let me take a second pass at the SAML section in another review.

ericchiang · 2017-10-11T23:18:05Z

Documentation/users/tectonic-identity-overview.md

+
+The three major components of Tectonic Identity are the API server, Tectonic Console, and kubectl.
+
+this doesn't make sense. these three aren't 'components' of TI - I think this means to list three things that 'access' TI. I also think this section should refer to 'Tectonic Identity', and not 'Dex' when describing these connections. - beth


I think this section could probably just use a diagram that we then break down.

Tectonic Identity - logs users into cooperate identity systems (LDAP, SAML, etc.) and issues credentials.

Kubernetes API server - will authenticate user credentials against Tectonic Identity.

Tectonic Console - requests credentials on the user's behalf from Tectonic Identity.

kubectl - users can download credentials from Tectonic Console to use with kubectl when issuing commands to the Kubernetes API server.

ericchiang · 2017-10-11T23:18:28Z

Documentation/users/tectonic-identity-overview.md

+
+In case of LDAP, Tectonic Console logs the user in to a LDAP server. LDAP through Dex issues a ID Token. Tectonic on behalf of the user call kubectl with the ID Token. Kubectl connects to the API Server and verify the validity of the ID Token and authenticity of the user. Once authorized API server returns a response to kubectl.
+
+ - can we make this IdP agnostic? isn't the connection sequence the same for both LDAP and SAML ? - beth


Yes. Let's only briefly mention SAML, LDAP, etc. in this doc.

ericchiang · 2017-10-11T23:18:46Z

Documentation/users/user-auth.md

+
+However, the original example and LDAP server output, shown earlier in this document, qualify members based on `DN` rather than `mail`.
+
+This doesn't make sense. we've told users they must use the email address for usernames, yet here it's pointing it out as an error? - beth


Tried to answer that above.

zbwright · 2017-10-12T20:59:30Z

general question: do we want to point readers down into the Dex repo? for example, do we want to say, For more information, see https://github.com/coreos/dex/blob/master/Documentation/ldap-connector.md ? I'm conflicted on this.

zbwright · 2017-10-16T21:11:52Z

@robszumski @ericchiang @rithujohn191 I believe with one more review pass, we could publish these to the site. Does anyone have time this week for a read through?

ericchiang

Couple nits but this is already much better than what we have today so lets get it merged and submit follow ups.

Just so I remember, these are some things we might want to follow up with:

Encourage not granting roles to the default service account (containers that need permissions should have a unique service account).
More LDAP schema -> config mappings?
Follow up on SAML docs.

ericchiang · 2017-10-20T17:14:15Z

Documentation/users/ldap-integration.md

+
+The following examples demonstrate mapping LDAP schema to Tectonic Identity configurations.
+
+### User LDAP schema and Tectonic mapping


nit: this section and the one below are both examples of the same functionality: determining what group a user's in. Maybe combine the two sections?

i don't think i understand LDAP schema well enough to make a clean attempt at this. Do the two LDAP snippets both show a member definition at the top:

dn: cn=john,dc=people,dc=example,dc=org objectClass: person cn: jane email: [email protected]

followed by a group definition at the bottom:

dn: cn=developers,dc=groups,dc=example,dc=org objectClass: group cn: developers member: jane

that is, are these simply two different ways to define group affiliations?

ericchiang · 2017-10-20T17:15:04Z

Documentation/users/rbac-config.md

+
+Tectonic Console and `kubectl` now reflect the updated role and binding:
+
+< i can insert an image here, if we think it's useful. i'm not convinced - beth >


nit: remove this before pushing final docs?

rithujohn191 · 2017-10-20T17:25:32Z

Documentation/users/tectonic-identity-config.md

+# Existing user entry.
+- email: "[email protected]"
+  hash: "$2a$10$TcWtvcw0N8.xK8nKdBw80uzYij6cJwuQhtfYnEf/hEC9bRTzlWdIq"
+    # newly generated bcrypt hash


This comment is slightly confusing. Maybe add it to the line above and re-align it?

rithujohn191 · 2017-10-20T17:28:42Z

Documentation/users/tectonic-identity-config.md

+  userID: "1d55c7c4-a76d-4d74-a257-31170f2c4845"
+```
+
+After the config changes are applied, the user can log in to the Console using the new password.


I wonder if we should highlight that applying the ConfigMap changes does not mean that a new Dex instance will roll out. The user will have to manually bring up the identity Pod with the new config changes.

👍 yeah, great point.

rithujohn191 · 2017-10-20T17:57:11Z

Documentation/users/user-auth.md

+memberOf: cn=tectonic_users,ou=Users,o=5866a86d3187bc712e435b35,dc=example,dc=org
+```
+
+Use the email address as the name attribute for the account:


Changing this to "Use the email address as the name attribute for RoleBinding definition for the account" would make it more clear

docs: more tectonic identity work docs: sunday edits clarify users/groups/svc accounts Update creating-roles.md Update creating-service-accounts.md docs: review changes docs: fix indent docs: clarify ldap and saml docs: tweaks

rithujohn191 · 2017-10-20T23:59:03Z

Documentation/users/tectonic-identity-config.md

+
+When generating Tectonic Console passwords with `bcrypt-tool`, using values higher than the default of `-cost=10` may result in timeouts. bcrypt also imposes a maximum password length of 56 bytes.
+
+To ensure the static user has been added successfully, log in to Tectonic Console using the static user's username and password.


Please do add the same condition here that the user needs to bring up the identity pod again

zbwright · 2017-10-25T18:45:46Z

@joshix I know I confirmed that this is ready for your review verbally. Adding a note here as well for tracking purposes. If you would like to go through these, have at it, please.

ericchiang

lgtm

[WIP] docs: redo tectonic identity docs

d24d3d9

ericchiang assigned ericchiang and rithujohn191 and unassigned ericchiang and rithujohn191 Sep 22, 2017

ericchiang requested review from ericchiang and rithujohn191 September 22, 2017 21:45

robszumski reviewed Oct 6, 2017

View reviewed changes

robszumski reviewed Oct 11, 2017

View reviewed changes

ericchiang reviewed Oct 11, 2017

View reviewed changes

ericchiang reviewed Oct 20, 2017

View reviewed changes

rithujohn191 reviewed Oct 20, 2017

View reviewed changes

docs: rewrite tectonic identity docs

10c8ad2

docs: more tectonic identity work docs: sunday edits clarify users/groups/svc accounts Update creating-roles.md Update creating-service-accounts.md docs: review changes docs: fix indent docs: clarify ldap and saml docs: tweaks

zbwright force-pushed the tectonic-identity branch from 2822ee2 to 10c8ad2 Compare October 20, 2017 18:28

zbwright changed the title ~~[WIP] Tectonic Identity docs revision~~ Tectonic Identity docs revision Oct 20, 2017

rithujohn191 reviewed Oct 20, 2017

View reviewed changes

zbwright added 3 commits October 23, 2017 09:28

docs: add bring up pod

15cf0ab

docs: standardize comments

2024c32

Update tectonic-identity-config.md

fa46d1e

joshix self-requested a review October 23, 2017 22:13

ericchiang approved these changes Oct 25, 2017

View reviewed changes

zbwright merged commit 205021f into coreos:master Oct 25, 2017

zbwright deleted the tectonic-identity branch October 26, 2017 00:28


		## Removing Access

		Changes to a Role or Role Binding will take place immediately. Revoking access to a user may not be fully complete until the user's session token expires. The default expriation time is 24 hours.


		## Assign Users to Roles

		To grant your users access to Roles, [use a Role Binding][insert].


		Once the Role is created, click its Name in the Roles page, then click Add Rule to open the Create Access Rule page.

		<Create Access Rule page>


		A Role Binding can reference both Roles and Cluster Roles to grant permissions to resources. This allows administrators to define a set of common roles for the entire cluster, then reuse them within multiple namespaces. For example, the `view` Cluster Role referred to in the following Role Binding grants read-only permission to `[email protected]` but denies access to that user in the `kube-system` namespace.

		(this doesn't make sense, given the example - beth)


		The table below describes the parameters that configure Tectonic Identity federation with IdPs:

		question: are these platform agnostic? in which case, i want to pull them from here, and add them to tectonic-identity-config.md - beth


		The three major components of Tectonic Identity are the API server, Tectonic Console, and kubectl.

		this doesn't make sense. these three aren't 'components' of TI - I think this means to list three things that 'access' TI. I also think this section should refer to 'Tectonic Identity', and not 'Dex' when describing these connections. - beth


		In case of LDAP, Tectonic Console logs the user in to a LDAP server. LDAP through Dex issues a ID Token. Tectonic on behalf of the user call kubectl with the ID Token. Kubectl connects to the API Server and verify the validity of the ID Token and authenticity of the user. Once authorized API server returns a response to kubectl.

		- can we make this IdP agnostic? isn't the connection sequence the same for both LDAP and SAML ? - beth


		However, the original example and LDAP server output, shown earlier in this document, qualify members based on `DN` rather than `mail`.

		This doesn't make sense. we've told users they must use the email address for usernames, yet here it's pointing it out as an error? - beth


		The following examples demonstrate mapping LDAP schema to Tectonic Identity configurations.

		### User LDAP schema and Tectonic mapping


		Tectonic Console and `kubectl` now reflect the updated role and binding:

		< i can insert an image here, if we think it's useful. i'm not convinced - beth >


		When generating Tectonic Console passwords with `bcrypt-tool`, using values higher than the default of `-cost=10` may result in timeouts. bcrypt also imposes a maximum password length of 56 bytes.

		To ensure the static user has been added successfully, log in to Tectonic Console using the static user's username and password.

Tectonic Identity docs revision #33

Tectonic Identity docs revision #33

Conversation

zbwright commented Sep 22, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joshix commented Oct 11, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericchiang left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zbwright commented Oct 12, 2017

zbwright commented Oct 16, 2017

ericchiang left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zbwright commented Oct 25, 2017

ericchiang left a comment

Choose a reason for hiding this comment