diff --git a/content/sass/_index.md b/content/sass/_index.md index ff32c6cc3c..73ba37b053 100644 --- a/content/sass/_index.md +++ b/content/sass/_index.md @@ -11,4 +11,5 @@ draft = false identifier = "chef_infra/Overview" parent = "chef_saas" weight = 10 -+++ \ No newline at end of file ++++ + diff --git a/content/sass/get_started.md b/content/sass/get_started.md index af6feadd85..0c8005751d 100644 --- a/content/sass/get_started.md +++ b/content/sass/get_started.md @@ -9,3 +9,121 @@ draft = false parent = "chef_saas" weight = 20 +++ + +This guide is a quick start for Chef SaaS. + +## Quick Start for Automate SAAS + +Steps to start your Automate SaaS journey is given below: + +{{< note >}} Prerequisites: Workstation setup already installed. {{< /note >}} + +1. Once you have the credentials, verify it by logging in to the environment through the Automate user interface. + +1. Once you have logged in, test the `admin` user and connect their Workstation to SaaS. + +If you do not have a workstation setup, follow the steps given below: + +1. [Install](https://downloads.chef.io/tools/workstation) Chef Workstation. + +1. You will receive an e-mail in your provided mail id. The e-mail contains the server information. Use the server information to create your connection to Automate SaaS. + +1. Once you are connected, start connecting the nodes to Automate SaaS. + +## Workstation Test + +To start with the Workstation Test, go through the [Getting Started](https://docs.chef.io/workstation/getting_started/) section of Workstation. + +### Configure Your User Credentials File + +Your `.chef` directory contains a credentials file for communicating with the **Chef Infra Server**. You can generate the `.chef` file by running Knife Configure or by following the prompts. + +The knife configure command requires the following values: + +* **Chef Server URL:** The full URL to your Chef Infra Server including the `org`. +* **Client Name:** The client name of the Server Administrator created for you. + +Your Chef administrator should provide the following information: + +```sh +current_dir = File.dirname(__FILE__) +log_level :info +log_location STDOUT +node_name "hshefu" +client_key "#{current_dir}/hshefu.pem" +chef_server_url https://api.chef.io/organizations/4thcafe-web-team +cookbook_path ["#{current_dir}/../cookbooks"] +``` + +Use the `chef_server_url` and `node_name` values from the file when running knife configure. + +## Verify Client-to-Server Communication + +To verify that the Chef Workstation can connect to the Chef Infra Server: + +Run the following command on the command line: + +### Knife Client List + +### Workstation Setup + +1. To set up the workstation on your instance follow these steps: + + * Install the latest version of Chef Workstation on the Ubuntu system. Install the version using the command shown below: + + ```sh + wget https://packages.chef.io/files/stable/chef-workstation/21.2.524/ubuntu/20.04/chef-workstation_21.2.524-1_amd64.deb + ``` + + * For Deb packaging run the following command: + + ```sh + dpkg -i chef-workstation_21.2.524-1_amd64.deb + ``` + + * Verify installation by running the following command: + + ```sh + chef -v + ``` + + For additional information refer to the [Install Workstation](https://docs.chef.io/workstation/install_workstation/) page. + + * Generate `chef-repo` using the following command: + + ```sh + chef generate repo chef-repo + ``` + + For additional information refer to the [Getting Started](https://docs.chef.io/workstation/getting_started/) page of Workstation. + + * Paste the `pem` file of user inside `/root/.chef/`. + + * Paste the `pem` file of node you want to bootstrap inside `/root/.ssh/`. + + * Edit credentials file using the following command: + + ```sh + vi /root/.chef/credentials + ``` + + Provide the name of the user created in **chef_server**, the correct path of `pem` file of the user, and the chef server URL and organization name. + + ```sh + [default] + client_name = "" + client_key = "/root/.chef/" + chef_server_url = "https://demo-server.saas.chef.io/organizations//" + ``` + + * Run bootstrap command using the following command: + + ```sh + knife bootstrap -i ~/ -U ubuntu -N --sudo + ``` + +* **Public IP**: Public IP is the IP address of node which we are bootstrapping. + +* **pem_file_of_node**: `pem` file of node which we have saved at `/root/.ssh/`. + +* **name_of_node**: You can provide any name to your node. diff --git a/content/sass/sso.md b/content/sass/sso.md index ce02cafa26..bd56584e12 100644 --- a/content/sass/sso.md +++ b/content/sass/sso.md @@ -10,3 +10,353 @@ draft = false weight = 40 +++ +Single sign-on (SSO) is an authentication method that enables you to securely authenticate and use all services with just one set of credentials. The steps are as follows: + +1. Login to automate. Once done, open the **https://your_automate_url/sso** URL in new tab. + +2. The above URL will redirect you to the SAML setup page where the you(admin) can set up the Single sign-on configuration using the UI provided. + +3. The Chef SaaS SSO feature supports only SAML-based IDP authentication as of now and will support IDPs according to the [Automate Documentation](https://docs.chef.io/automate/saml/). + +## IDP Configuration + +Chef SaaS SSO feature supports major SAML authentication as per the current supported IDP of Automate. Following are the sample steps to configure the IDPs based on the tried test use cases: + +* [OKTA IDP configuration for SSO](https://chefio.atlassian.net/wiki/spaces/CPSK/pages/2720694589/OKTA+IDP+configuration+for+SSO) + +* [Microsoft 365 and Azure AD IDP configuration for SSO](https://chefio.atlassian.net/wiki/spaces/CPSK/pages/2712142486/Azure+AD+and+Microsoft+365+IDP+configuration+for+SSO) + +## User SSO integration Journey + +### Prerequisites + +Only SaaS admins will be able to access this feature. + +Supported IDP is up and ready + +How to enable SSO for Chef-SaaS + +To access the Single Sign-on UI navigate to https://your_automate_url. + +Log in as an admin user. + +Modify your browser URL with sso. + +Remove everything after https://your_automate_url/ from your automate url and add /sso +ex :- https://your_automate_url/dashboard/event-feed will become https://your_automate_url/sso + +On navigating to https://your_automate_url/sso you will be authenticated and authorized for admin-level privileges and redirected to the Chef-SaaS SSO UI. + + + +Fill the form fields with the values provided by your IDP + +SSO URL - Single Sign-On URL is provided by your IDP. + +Email Attribute - The attribute setup in IDP for user email. + +Username Attribute - The attribute setup in IDP for the username. + +Entity Issuer URL- This value will be https://your_automate_url/dex/callback + +CA Certificate - Ca certificate provided by your IDP. This value should include the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- markers. +Certificate will be validated for syntactical or semantical errors before submitting the config. + +Please refer to this link in case of any errors or validation failures. + +Click on Submit to set the SSO config. Submit button will be enabled if and only if form validation passes. + +An indication icon will run until setup process is completed. + + + +When the request is completed, you will be able to see if your set up is complete or if there are errors with the configuration. + +If request completes user will see SSO Request is complete. Config applied successfully. + +If the request fails user will see SSO Request Failed with an appropriate message. + +How to Delete the SSO integration + +Remove Configuration button will be enabled once config is present. Click on it to remove the config. + +A popup will appear to confirm if user wants to remove config or not. + + + +Click on Remove to start the config removal process. + +An indication icon will be present until configuration is removed. Admin will see SSO request is complete Config removed Successfully. + +In case of error admin will see SSO Request Failed with an appropriate message. + +Click on Cancel to avoid config removal. + +Assuming that the admin has set up its IDP, the admin can go ahead and provide the necessary information on the SSO UI page. + +SSO URL * - Single Sign-On URL is provided by your IDP. Ensure that this is a valid URL. + +Email Attribute * - It is used to refer to the user’s email. The attribute configured in IDP for user email can be passed here. + +Username Attribute * - It is used to refer to a username. The attribute configured in IDP for the username can be passed here. + +Entity Issuer URL * - It contains the value of the Identifier (Entity ID). This should be your automate URL with dex callback. Ensure that this is a valid url. +Ex- https://your_automate_url/dex/callback + +CA Certificate * - This is the (Base64) Certificate value generated by your IDP on app configuration. Ensure that this certificate has -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- markers. This value should be used as it is and should not contain /n sequences. + +Group Attribute - This field is optional, but if not provided, users authenticating via SSO will not be members of any teams. + +Allowed Groups - This field is optional. It provides a Single sign-in for members of the listed groups and discards all user groups that are not on the list. Groups must be on the allowed_groups list to access Chef Automate. + +Name Id Policy Format - When provided, Chef Automate will request a name ID of the configured format in the SAML AuthnRequest. +This is a mandatory field for Microsoft365 and Azure AD IDPs +Defaults to urn:oasis:names:tc:SAML:2.0:nameid-format:persistent. + +Fields marked with * are mandatory fields. + +How to undo your changes + +Admins can click on Cancel used to override the field data that was edited. + + + + + +For use with Okta + + + +Visit https://okta.com and login into your account. + +Click on Applications to create your SAML application. + +Click on Create App Integration. + + + +Select SAML 2.0, and click next. + +You will be redirected to page where you can create your app. + + + +Fill in the config information as shown in the below image and click next. + +Single sign on URL: This should be the URL for your automate server plus /dex/callback. Example: https://your_automate_url/dex/callback + +Audience URI: This will be the same URL as the Single sign-on URL + +Default RelayState should be blank + +Name ID Format should be Unspecified + +Application Username should be Email + +Under attributes you’ll want to create two: + +Name: email +Value: user.email + +Name: username +Value: user.login + + + +Select I'm an Okta customer adding an internal app and click on finish. + +Add users who can login using this app. + +Click on Assignments then Click on Assign and then to assign to people. Select users from list to add users on the app. + + + +Your app will be created click on view SAML setup instruction as shown in below image + + + + + +Your Okta account is setup now. You can use config provided by okta to setup SAML on automate. + +Multiple options can be selected. + + + +For use with Azure AD + + + +Before You Start + +This guide assumes you have the following set up: + +Azure AD / Microsoft 365 with Azure AD access + +Admin Rights to the Instance + +Chef Automate 2.0 or later version + +Steps + +1.Creating the App in Azure + +Go azure AD portal ([https://portal.azure.com]) and login into it. + +Then under Enterprise applications. + +Select New application and then select Create your own application to create a new application. + +Provide name for application. + +Select Non-Gallery Application option. + +After creating it, click on single sign-on and select SAML + + + + + +Under the Single Sign-On option, fill out the following information: + +In section 1 – Basic SAML Configuration, enter following: + + + + + +Identifier (Entity ID): https://{your-chef-automate-fqdn}/dex/callback + +Reply URL (Assertion Consumer Service URL): +https://{your-chef-automate-fqdn}/dex/callback + +In section 2: User Attributes and Claims, check the defaults that are there: + + + + + +Required Claim: + +Unique User Identifier (Name ID) + +Source attribute: user.userprincipalname + +Additional Claims + +givenname + +Namespace: http://schemas.xmlsoap.org/ws/2005/05/identity/claims + +Source attribute: user:givenname + +name + +Namespace: http://schemas.xmlsoap.org/ws/2005/05/identity/claims + +Source attribute: user:userprincipalname + +surname + +Namespace: http://schemas.xmlsoap.org/ws/2005/05/identity/claims + +Source attribute: user:surname + +Add the following additional claims (may need to delete existing entries for emailaddress and username if they already exist). + +emailaddress + +Namespace: leave namespace blank + +Source attribute: user.mail + +username + +Namespace: leave namespace blank + +Source attribute: user.mail + +In section 3 – SAML Signing certificate. + + + + + +Download the certificate (Base64). + +Note the following values from Section 4: + + + + + +Login URL. + +Azure AD Identifier. + +Logout URL. + +After setup, go to Users and groups for assigning users and groups to the application. + + + +Click on Add user/group to assign users and groups to the application. + +2.Configuring SAML on the Chef Automate via SSO UI + +Log into chef-automate and then switch to SSO UI i.e https://{your-chef-automate-fqdn}/sso + +Fill the required values :- + +CA Information: this is the X.509 Certificate from section 3 above. Copy the downloaded certificate contents and paste as the value for CA Information. + +SSO URL: This is the value for Identity Provider Single Sign-On URL. Use the Login URL value from Section 4 above. + + + +Email Attribute: This is the name of the claim for email. (eg: In our case, it is emailaddress) + +Username Attribute: This is the name of the claim for username. (eg: In our case, it is username) + +Entity Issuer: This should be the URL provide in section 1 for Identifier (Entity ID). +(eg: In our case, it ishttps://{your-chef-automate-fqdn}/dex/callback) + +Name Id Policy Format : This should be the Unique User Identifier (Name ID) value from value column for Name ID present in square brackets. +eg:- user.userprincipalname [nameid-format:emailAddress]and add it to end of urn:oasis:names:tc:SAML:1.1:. + + + + +So it should look like this urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress + +:warning: + +Azure AD lets you choose the NameID field and also apply transformations to it. The SAML configuration setting of the selected value in “Choose name identifier format” in Azure AD must match the name_id_policy_format configuration in Chef Automate. + +These values are accepted for name_id_policy_format: + +urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress + +urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified + +urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName + +urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName + +urn:oasis:names:tc:SAML:2.0:nameid-format:encrypted + +urn:oasis:names:tc:SAML:2.0:nameid-format:entity + +urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos + +urn:oasis:names:tc:SAML:2.0:nameid-format:persistent + +urn:oasis:names:tc:SAML:2.0:nameid-format:transient + +Click Submit button to patch the SSO settings on chef-automate + +Multiple options can be selected. + + + + \ No newline at end of file