Authentication Documentation (AthenZ#1025)

ashwintumma23 · Jul 20, 2020 · 841f3c6 · 841f3c6
1 parent 3b5bcdf
commit 841f3c6
Show file tree

Hide file tree

Showing 31 changed files with 1,551 additions and 44 deletions.
diff --git a/docs/aws_temp_creds.md b/docs/aws_temp_creds.md
diff --git a/docs/aws_zms_setup.md b/docs/aws_zms_setup.md
@@ -212,7 +212,7 @@ Create another bucket for audit logs having the following bucket policy:
         "Effect": "Allow",
         "Principal": {
             "AWS": [
-                "arn:aws:iam::488664618023:role/athenz.zms-service"
+                "arn:aws:iam::<account-id>:role/athenz.zms-service"
             ]
         },
         "Action": [

diff --git a/docs/images/aws-ec2-setup.png b/docs/images/aws-ec2-setup.png
diff --git a/docs/images/aws-service-authorize-2.png b/docs/images/aws-service-authorize-2.png
diff --git a/docs/images/aws-service-authorize-ecs.png b/docs/images/aws-service-authorize-ecs.png
diff --git a/docs/images/aws-service-authorize.png b/docs/images/aws-service-authorize.png
diff --git a/docs/images/aws-service-register.png b/docs/images/aws-service-register.png
diff --git a/docs/images/aws_add_member.png b/docs/images/aws_add_member.png
diff --git a/docs/images/aws_athenz_policy_create.png b/docs/images/aws_athenz_policy_create.png
diff --git a/docs/images/aws_athenz_role_create.png b/docs/images/aws_athenz_role_create.png
diff --git a/docs/images/aws_trust_setup.png b/docs/images/aws_trust_setup.png
diff --git a/docs/images/aws_trust_setup_duration.png b/docs/images/aws_trust_setup_duration.png
diff --git a/docs/images/aws_trust_setup_external_id.png b/docs/images/aws_trust_setup_external_id.png
diff --git a/docs/images/create_sub_domain.png b/docs/images/create_sub_domain.png
diff --git a/docs/images/iam-lambda-role-setup-1.png b/docs/images/iam-lambda-role-setup-1.png
diff --git a/docs/images/iam-lambda-role-setup-2.png b/docs/images/iam-lambda-role-setup-2.png
diff --git a/docs/images/iam-lambda-role-setup-3.png b/docs/images/iam-lambda-role-setup-3.png
diff --git a/docs/images/iam-role-setup-1.png b/docs/images/iam-role-setup-1.png
diff --git a/docs/images/iam-role-setup-2.png b/docs/images/iam-role-setup-2.png
diff --git a/docs/images/iam-role-setup-3.png b/docs/images/iam-role-setup-3.png
diff --git a/docs/images/service_add.png b/docs/images/service_add.png
diff --git a/docs/images/service_add_public_key.png b/docs/images/service_add_public_key.png
diff --git a/docs/images/service_delete_public_key.png b/docs/images/service_delete_public_key.png
diff --git a/docs/reg_service_guide.md b/docs/reg_service_guide.md
@@ -1,82 +1,90 @@
-# Registering ZMS Service Identity
-----------------------------------
-
-* [Key Generation](#key-generation)
-    * [Private Keys](#private-keys)
-    * [Key Rotation](#key-rotation)
-* [Service Identity Registration](#service-identity-registration)
-
 Once a domain has been registered in Athenz, the administrator will
 register service identities that are specified in domain roles and
 policy assertions. The latter can reference those roles having access to
-specified resources.
+specified resources. Athenz supports service authentication with
+two types of credentials:
+
+- X.509 Certificates (preferred approach) [Instructions](service_x509_credentials.md)
+- Public/Private Key Pairs
 
 Before you can register the service identity, you'll need to generate
-keys. We'll cover how to create the keys and register the service
-identity next.
+keys. In this section we'll cover how to create the keys and register the service
+identity.
 
 ## Key Generation
-----------------
 
 The registration process requires the domain administrator to generate a
-private/public RSA key pair (recommended to be at least 2048 bit)
-for the service. Athenz also supports EC keys.
+private/public RSA key pair (must be at least 2048 bit) for the service.
 
 The following are the keys and the services that use those keys:
 
--   **private key** - The service agent uses the private key to generate a
+-   **private key** - The SIA server/utility uses the private key to generate a
     `ServiceToken` identifying the service.
 -   **public key** - ZMS/ZTS then use the public key to validate the
-    `ServiceToken` generated by service agent.
+    `ServiceToken` generated by SIA.
 
 The `openssl` command-line utility is used to generate the key pair:
 
-    $ openssl genrsa -out service_private.pem 2048
-    $ openssl rsa -in service_private.pem -pubout > service_public.pem
-
+```
+    $ umask 077
+    $ openssl genrsa -out service_private.key 2048
+    $ openssl rsa -in service_private.key -pubout > service_public.key
+```
 
-The zms-cli client utility requires that the public key have an extension
-of .pem.
+If using the [zms-cli](zms_client.md) client utility to register the service identity,
+the public key file must have an extension of .pem or .key.
 
 ### Private Keys
-----------------
 
-The private key file must be installed on all hosts where the client
-service will be running.
+The private key file must be installed on all hosts where the service
+will be running. The reason the use of X.509 Certificates is the
+preferred approach is because to securely install the private key
+on all hosts presents a challenge. 
 
 Each key pair has a key identifier that will be included in the
-generated `ServiceTokens (NToken)` as the value of the `k` component. If
-the service’s private key has been compromised or the service has a policy
+generated `ServiceTokens` as the value of the `k` component. If the
+service’s private key has been compromised or the service has a policy
 to periodically rotate the keys, the service administrator will generate
 a new key pair, remove the public key with the old identifier, and
 register a new public key with a different key identifier. Typically, a
 service would start with "0" as its first identifier and increment when
 required.
 
 ### Key Rotation
-----------------
 
 If the service’s private key has been compromised or the service has a
 policy to periodically rotate the keys, the service administrator will
 generate a new key pair, remove the public key with identifier 0 and
-register a new public key with a different key identifier as shown
-below:
+register a new public key with a different key identifier. As mentioned above,
+the key identifier is included in generated Service Tokens as the value
+of the `k` component. See the instructions below how to add and delete
+public keys for a service.
 
-    $ zms-cli -d <domain> delete-public-key <service> 0
-    $ zms-cli -d <domain> add-public-key <service> 1 new_service_public.pem
+## Service Identity Registration
 
-As mentioned above, the key identifier is included in generated Service
-Tokens as the value of the `k` component.
+To register a new service identity, select your domain in Athenz UI
+and choose the `Services` tab. Select `Add Service` link on the left
+side of the screen underneath the Roles/Services/Policies tabs. Enter
+the Service name, and optional description, the public key ID, and
+the actual public key contents in pem format:
 
-## Service Identity Registration
---------------------------------
+![Add Service](images/service_add.png)
+
+### Add new public key
+
+Once the services view is displayed, Select the `Public Keys` icon on
+the same line as the service to see all the registered public key.
+Once that view is open, click on the `Add Key` link on the right hand
+side. Enter the Key Id and the Key Value which must be a PEM encoded
+public key. Click `Submit` to complete your update.
 
-To create a service identity object in ZMS with the generated public key:
+![Add Service Public Key](images/service_add_public_key.png)
 
-    $ zms-cli -d <domain> add-service <service> <key-id> <service_public.pem>
+### Delete an existing public key
 
-For example, to register the service "storage" in the domain ``athenz`` 
-with the key identifier ``0`` and the public key stored in the file ``storage_public.pem``, 
-run the following ``zms-cli`` command:
+Once the services view is displayed, Select the `Public Keys` icon on
+the same line as the service to see all the registered public key.
+Once that view is open, click on the `Delete` trash can icon on the
+right hand side of the public key.
 
-    $ zms-cli -d athenz add-service storage 0 ./storage_public.pem
+![Delete Service Public Key](images/service_delete_public_key.png)
diff --git a/docs/service_x509_credentials.md b/docs/service_x509_credentials.md
@@ -0,0 +1,101 @@
+Once a domain has been registered in Athenz, the administrator will
+register service identities that are specified in domain roles and
+policy assertions. The latter can reference those roles having access to
+specified resources. Athenz supports service authentication with
+two types of credentials:
+
+- X.509 Certificates (preferred approach)
+- Public/Private Key Pairs [Instructions](reg_service_guide.md)
+
+To contact Athenz Services (ZMS/ZTS) or other Athenz Enabled services,
+the client service must first obtain an Athenz CA issued X.509 certificate.
+In this section we'll cover how to register the service identity and
+obtain X.509 certificates based on what environment your service will be running in.
+
+## Use Case 1: Service Running in AWS EC2
+
+If the service is running in AWS, Service Identity Agent (SIA) running on the
+instance is responsible for generating a private key for the service and
+obtaining a x.509 certificate from ZTS Service. The files are located in
+the following locations:
+
+```
+    private-key: /var/lib/sia/keys/<domain>.<service>.key.pem
+    certificate: /var/lib/sia/certs/<domain>.<service>.cert.pem
+```
+
+The certificate is valid for 30 days and SIA agent automatically
+will refresh the certificate daily. Follow [these steps](service_x509_credentials_aws.md) for
+full details how to configure SIA agent running in AWS as part
+of the foundation image.
+
+## Use Case 2: Service running on-prem within an Athenz Enabled Framework (K8S)
+
+If the service is running within an Athenz enabled framework then it
+must already have access to service identity x.509 certificate that
+was generated for the service. Refer to the documentation provided
+by the framework to see where the files are located.
+
+## Use Case 3: Service Running in AWS ECS (Elastic Container Service)
+
+If the service is running in AWS ECS, Service Identity Agent (SIA) included
+in your image is responsible for generating a private key for the service and
+obtaining a x.509 certificate from ZTS Service. The files are located in
+the following locations:
+
+```
+    private-key: /var/lib/sia/keys/<domain>.<service>.key.pem
+    certificate: /var/lib/sia/certs/<domain>.<service>.cert.pem
+```
+
+The certificate is valid for 30 days and SIA agent automatically
+will refresh the certificate daily. Follow [these steps](service_x509_credentials_aws_ecs.md) for
+full details how to configure SIA agent running in AWS as part of your image.
+
+## Use Case 4: Service Running in AWS Lambda Function
+
+If the service is running in AWS Lambda function, the function being invoked will be
+responsible for generating a private key and then a csr for its request. It will submit
+that request to the ZTS Server to retrieve its X.509 certificate which then it
+can use  along with its generated private key to establish TLS connections to
+other Athenz enabled services. Athenz Team provides functions/methods in Go
+and Java programming languages to quickly generate a private key and request its
+corresponding X.509 certificate from ZTS Server.
+
+The certificate is valid for 30 days. The short lifetime and stateless nature of
+the function means it cannot rotate its certificates. It just gets new ones when needed.
+
+Follow [these steps](service_x509_credentials_aws_lambda.md) for
+full details how to obtain service x.509 credentials within your function.
+
+## Use Case 5: Service Running in AWS Fargate
+
+If the service is running in AWS Fargate, Service Identity Agent (SIA) included
+in your image is responsible for generating a private key for the service and
+obtaining a x.509 certificate from ZTS Service. The files are located in
+the following locations:
+
+```
+    private-key: /var/lib/sia/keys/<domain>.<service>.key.pem
+    certificate: /var/lib/sia/certs/<domain>.<service>.cert.pem
+```
+
+The certificate is valid for 7 days and SIA agent automatically
+will refresh the certificate daily. Follow [these steps](service_x509_credentials_aws_fargate.md) for
+full details how to configure SIA agent running in AWS as part of your image.
+
+## Use Case 6: Service Running in AWS EKS
+
+If the service is running in AWS EKS, Service Identity Agent (SIA) included
+in your image is responsible for generating a private key for the service and
+obtaining a x.509 certificate from ZTS Service. The files are located in
+the following locations:
+
+```
+    private-key: /var/lib/sia/keys/<domain>.<service>.key.pem
+    certificate: /var/lib/sia/certs/<domain>.<service>.cert.pem
+```
+
+The certificate is valid for 7 days and SIA agent automatically
+will refresh the certificate daily. Follow [these steps](service_x509_credentials_aws_eks.md) for
+full details how to configure SIA agent running in AWS as part of your image.