diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..9111c7c --- /dev/null +++ b/TODO.md @@ -0,0 +1,24 @@ +# Description + +The following document describes missing JAAS documentation as well as any docs that need to be modernized. + +## Missing Docs +- Deploy JAAS tutorial (including going all the way to adding a controller, model and application) +- JAAS architecture +- Explain the difference between Juju, JAAS and jimmctl CLI tools. +- Auth doc explaining JIMM's authentication and authorization. +- How to enable/deploy/use the dashboard. +- JAAS Limitations - potentially (As an example, cross-controller relations don't work with JAAS currently) +- Relating JIMM and COS stack - general observability. +- What versions of Juju controllers and CLI does JIMM support. +- Managing access rights via jimmctl +- How to migrate existing Juju controllers and models to JAAS. +- How to bootstrap JAAS with an admin user and create user permissions. +- How to migrate models between Juju controllers in JAAS. + +## Docs requiring changes +- how-to/add_controller (possibly merge add_controller_no_dns into the original) +- how-to/deploy_jimm_k8s +- how-to/deploy_jimm (the machine charm is not currently on par with the k8s charm, this document could be removed until the machine charm is updated and ready for production use) +- how-to/route53 ensure this document is still up to date. +- tutorial/jaas_basics diff --git a/custom_conf.py b/custom_conf.py index f141bef..031f091 100644 --- a/custom_conf.py +++ b/custom_conf.py @@ -172,6 +172,7 @@ 'doc-cheat-sheet*', 'README.md', 'starter-guide.rst', + 'TODO.md' ] # Add CSS files (located in .sphinx/_static/) diff --git a/how-to/add_controller.rst b/how-to/add_controller.rst index 9fa40d0..e3e1409 100644 --- a/how-to/add_controller.rst +++ b/how-to/add_controller.rst @@ -1,6 +1,10 @@ JAAS: Add controller to JIMM ============================ +.. warning:: + This document has not been updated for JIMM.V3. + + Introduction ------------ diff --git a/how-to/add_controller_no_dns.rst b/how-to/add_controller_no_dns.rst index 9cfe805..e30797f 100644 --- a/how-to/add_controller_no_dns.rst +++ b/how-to/add_controller_no_dns.rst @@ -1,6 +1,10 @@ JAAS: Add controller to JIMM without DNS ======================================== +.. warning:: + This document has not been updated for JIMM.V3. + + Introduction ------------ diff --git a/how-to/candid_adfs_integration.rst b/how-to/candid_adfs_integration.rst deleted file mode 100644 index e874766..0000000 --- a/how-to/candid_adfs_integration.rst +++ /dev/null @@ -1,186 +0,0 @@ -JAAS: Candid ADFS Integration -============================= - -Introduction ------------- - -This how-to will teach you how to set up an ADFS identity provider for Candid. - -Prerequisites -------------- - -For this tutorial you will need the following: - -- A valid registered domain (regardless of the registrar) -- AWS credentials -- Basic knowledge of juju -- A subdomain registered with Route 53. To learn how to set that up, please follow :doc:`route53`. - -Candid ------- - -The first we need to deploy is Candid, so let’s begin by creating a model for Candid: - -``juju add-model candid`` - -To deploy Candid please download this `tarball `_, which contains everything you will need. -Extract the tarball: - -``tar xvf candid_v1.11.0.tar.xz`` - -Now you can move to the extracted ``candid`` folder: -``cd candid`` - -and deploy the bundle. We will be using certbot to obtain valid certificates so we can use the following command: - -``juju deploy ./bundle.yaml --overlay ./overlay-certbot.yaml`` - -and wait for the deployment to finish. You can observe the deployment status by running; - -``juju status --watch 2s –color`` - -Once the deployment is finished, you will see the certbot and HAProxy units are in an error state. This is because we still need to obtain a valid certificate for Candid. First we will need to get the public IP of the ``haproxy/0`` unit: - -``juju status --format json | jq '.applications.haproxy.units["haproxy/0"]["public-address"]'`` - -Now you will need to go to the `Route 53 dashboard `_, navigate to the hosted zone for the ``canonical.`` subdomain and select Create record. We will add an A record for ``candid.canonical.`` with the value of the IP of the ``haproxy/0`` unit we obtained in the previous step. -To obtain a valid certificate for Candid we will use an action of the certbot charm. Run: - -``juju run-action --wait certbot/0 get-certificate agree-tos=true aws-access-key-id= aws-secret-access-key= domains=candid.canonical. email= plugin=dns-route53`` - -It might take a while (5 minutes+ is normal) to get the certificate, but once complete: - -``juju status`` - -should show all units in an operational state. -Next we need to configure Candid. First we set the location configuration parameter: - -``juju config candid location=https://candid.canonical.`` -which will tell Candid which DNS it is running on. - -Azure ------ - -Usually you will already have a tenant set up in Azure Active Directory, but for the sake of -completeness, this how-to will guide you through the process of setting one up. -Open your web browser and navigate to the `Azure Portal `_. -Search for ``Azure Active Directory`` and click on Manage tenants and then click on Create. You -will be presented with the following form: - -.. image:: images/adfs_image5.png - -Select ``Azure Active Directory`` and click on ``Next: Configuration``, which will show you the -following form: - -.. image:: images/adfs_image12.png - -Enter the desired ``Organization name``, ``Initial domain name`` (record this value as we will need -it to configure Candid) and select an appropriate Country/Region, then click Review + create, -which will show you the review form: - -.. image:: images/adfs_image1.png - -If you’re satisfied with the entered data, click ``Create``. You will be presented with a form -displaying information about the created tenant. Record the ``Tenant ID``, as you will need it -later when configuring Candid. - -.. image:: images/adfs_image8.png - -To create a new user click on ``Users`` and then ``New user`` which will present you with the -following form where you can enter information about the new user. - -.. image:: images/adfs_image11.png - -Next we want to create a few groups, so select ``Groups`` from the left hand side menu and -create groups by clicking ``New group`` and entering relevant information. Created groups will -be displayed as shown in the following form: - -.. image:: images/adfs_image9.png - -To make the new user member of any of these groups, click on the group name, then click on -``Members`` and then ``Add members``. Start typing in the username and the portal should list -users matching the entered username. Select the newly created user and click ``Select`` as shown -in the following form: - -.. image:: images/adfs_image10.png - -Once you have finished creating groups and users it is time to register an application. Return -to the tenant overview form and click ``App registrations``. In the following form enter the -application name, select ``Accounts in this organizational directory only (Single tenant)`` and -for the ``Redirect URI`` select ``Web`` and enter ``https:///login/adfs/callback`` as -the redirect URI. - -.. image:: images/adfs_image3.png - -When you click ``Register`` you will be shown a form displaying data about the registered -application. Record the ``Application (client) ID`` as you will need it later when configuring -Candid. - -.. image:: images/adfs_image13.png - -To give Candid access, we need to create a secret it will use to authenticate. Click on -``Certificates & secrets`` and then ``New client secret``. - -.. image:: images/adfs_image4.png - -Record the displayed secret Value. - -To give Candid permission to read user groups navigate to ``API Permissions`` and add permissions -under ``Microsoft Graph: Group.Read.All``. - -.. image:: images/adfs_image14.png - -Then go to ``Token configuration`` to add additional claims. Click on ``Add groups claim`` so that -the Azure callback will include additional groups(s) claim. - -Configuring Candid ------------------- - -Next we need to add Azure as an identity provider to Candid, with the application (client) id -and the client secret we created in the previous step. Run: - -.. code-block:: bash - - juju config candid identity-providers='- type: adfs - domain: .onmicrosoft.com - url: https://login.microsoftonline.com//v2.0 - client-id: - client-secret: - match-email-addr: "@.onmicrosoft.com$"' - -For the domain name enter the ``Initial domain name`` you entered when creating the new tenant. And -the tenant id is the ID of the created tenant. For the client-id enter the ``Application (client) ID`` -you recorded when registering a new application. The client-secret is the Value you recorded when -creating a new client secret for the registered application. - -Then we can test Candid by opening your browser and going to -``https://candid.canonical./login``, which will present you with a page allowing you to -login with ADFS. - -.. image:: images/adfs_image7.png - - -After you select ADFS identity provider you will have to log in with Azure and then Candid will -present you with a page allowing you to register a new user by specifying the username. - -.. image:: images/adfs_image15.png - -After you click Register, Candid will show a page notifying you that you have successfully logged -in. - -.. image:: images/adfs_image6.png - -Conclusion ----------- - -In this how-to we have successfully deployed Candid and configured it to let you log in with your -ADFS credentials. - -To tear down your model and controller use the following command. -This will free all resources created on the cloud provider used. - -``juju destroy-controller --destroy-all-models --destroy-storage mycontroller`` - - - - diff --git a/how-to/candid_azure_integration.rst b/how-to/candid_azure_integration.rst deleted file mode 100644 index 022daa1..0000000 --- a/how-to/candid_azure_integration.rst +++ /dev/null @@ -1,104 +0,0 @@ -JAAS: Candid Azure Integration -============================== - -Introduction ------------- - -This how-to will teach you how to set up an Azure identity provider for Candid. - -Prerequisites -------------- - -For this tutorial you will need the following: - -- A valid registered domain (regardless of the registrar) -- AWS credentials -- Basic knowledge of juju -- A subdomain registered with Route 53. To learn how to set that up, please follow :doc:`route53`. - -Candid ------- - -The first we need to deploy is Candid, so let’s begin by creating a model for Candid: - -``juju add-model candid`` - -To deploy Candid please download this `tarball `_, which contains everything you will need. -Extract the tarball: - -``tar xvf candid_v1.11.0.tar.xz`` - -Now you can move to the extracted candid folder: -``cd candid`` - -and deploy the bundle. We will be using certbot to obtain valid certificates so we can use the following command: - -``juju deploy ./bundle.yaml --overlay ./overlay-certbot.yaml`` - -and wait for the deployment to finish. You can observe the deployment status by running; - -``juju status --watch 2s –color`` - -Once the deployment is finished, you will see the certbot and HAProxy units are in an error state. This is because we still need to obtain a valid certificate for Candid. First we will need to get the public IP of the ``haproxy/0`` unit: - -``juju status --format json | jq '.applications.haproxy.units["haproxy/0"]["public-address"]'`` - -Now you will need to go to the `Route 53 dashboard `_, navigate to the hosted zone for the ``canonical.`` subdomain and select Create record. We will add an A record for ``candid.canonical.`` with the value of the IP of the ``haproxy/0`` unit we obtained in the previous step. -To obtain a valid certificate for Candid we will use an action of the certbot charm. Run: - -``juju run-action --wait certbot/0 get-certificate agree-tos=true aws-access-key-id= aws-secret-access-key= domains=candid.canonical. email= plugin=dns-route53`` - -It might take a while (5 minutes+ is normal) to get the certificate, but once complete: - -``juju status`` - -should show all units in an operational state. -Next we need to configure Candid. First we set the location configuration parameter: - -``juju config candid location=https://candid.canonical.`` -which will tell Candid which DNS it is running on. - -Azure ------ - -With Candid deploy, we need credentials that will let Candid user Azure. -To do that open your browser and go to the Azure portal Find App Registration as we need to register a new application. The Azure portal will show you the following screen: - -.. image:: images/azure_image3.png - -where you will enter the application name and choose “Accounts in any organisational directory (Any Azure AD directory - Multi-tenant) and personal Microsoft accounts (e.g. Skype, Xbox)” when specifying who can access this API. -for the Redirect URI choose “Web” and enter ``https://candid.canonical./login/azure/callback`` as the callback URI. -After clicking “Register” you will be taken to the App Registration page, where you will find the “Application (client) ID”, which you need to copy. Then select “Certificates & secrets” in the management menu, because we will need to create a new secret. - -.. image:: images/azure_image2.png - -When you select “New client secret” it will prompt you to enter a name for it and then it will show you a page displaying the created secret value and ID. Copy the secret value as we will need it when configuring Candid. - -.. image:: images/azure_image5.png - -Configuring Candid ------------------- - -Next we need to add Azure as an identity provider to Candid, with the application (client) id and the client secret we created in the previous step. Run: - -.. code:: console - - juju config candid identity-providers='- type: azure - client-id: - client-secret: - -Then we can test Candid by opening your browser and going to ``https://candid.canonical./login``, which will present you with a page allowing you to login with Azure. - -.. image:: images/azure_image1.png - -After you select Azure identity provider you will have to log in with Azure and then Candid will present you with a page allowing you to register a new user by specifying the username. - -.. image:: images/azure_image4.png - -After you click Register, Candid will show a page notifying you that you have successfully logged in. - -Conclusion ----------- - -In this how-to we have successfully deployed Candid and configured it to let you log in with your Azure credentials. - diff --git a/how-to/candid_ldap_integration.rst b/how-to/candid_ldap_integration.rst deleted file mode 100644 index 08f2219..0000000 --- a/how-to/candid_ldap_integration.rst +++ /dev/null @@ -1,276 +0,0 @@ -JAAS: Candid LDAP Integration -============================= - -Introduction ------------- - -This how-to will teach you how to set up an LDAP identity provider for Candid. - -Prerequisites -------------- - -For this tutorial you will need the following: - -- A valid registered domain (regardless of the registrar) -- AWS credentials -- Basic knowledge of juju -- A subdomain registered with Route 53. To learn how to set that up, please follow :doc:`route53`. - -Candid ------- - -The first we need to deploy is Candid, so let’s begin by creating a model for Candid: - -``juju add-model candid`` - -To deploy Candid please download this `tarball `_, which contains everything you will need. -Extract the tarball: - -``tar xvf candid_v1.11.0.tar.xz`` - -Now you can move to the extracted candid folder: -``cd candid`` - -and deploy the bundle. We will be using certbot to obtain valid certificates so we can use the following command: - -``juju deploy ./bundle.yaml --overlay ./overlay-certbot.yaml`` - -and wait for the deployment to finish. You can observe the deployment status by running; - -``juju status --watch 2s –color`` - -Once the deployment is finished, you will see the certbot and HAProxy units are in an error state. This is because we still need to obtain a valid certificate for Candid. First we will need to get the public IP of the ``haproxy/0`` unit: - -``juju status --format json | jq '.applications.haproxy.units["haproxy/0"]["public-address"]'`` - -Now you will need to go to the `Route 53 dashboard `_, navigate to the hosted zone for the canonical. subdomain and select Create record. We will add an A record for candid.canonical. with the value of the IP of the ``haproxy/0`` unit we obtained in the previous step. -To obtain a valid certificate for Candid we will use an action of the certbot charm. Run: - -``juju run-action --wait certbot/0 get-certificate agree-tos=true aws-access-key-id= aws-secret-access-key= domains=candid.canonical. email= plugin=dns-route53`` - -It might take a while (5 minutes+ is normal) to get the certificate, but once complete: - -``juju status`` - -should show all units in an operational state. -Next we need to configure Candid. First we set the location configuration parameter: - -``juju config candid location=https://candid.canonical.`` -which will tell Candid which DNS it is running on. - -LDAP ----- - -In real-world scenarios you will already have a LDAP deploy, which you will use with candid. But for the sake of completeness this section will show you how to manually deploy and configure OpenLDAP (deploy using charms will be described in a separate document as we currently do not have an OpenLDAP machine charm). -First we create a model for the LDAP deploy: - -``juju add-model ldap`` - -Then we deploy a basic Ubuntu unit and a certbot charm: - -.. code:: - - juju deploy ubuntu ldap - juju deploy cs:~yellow/certbot - -and wait for the units to deploy. - -Install OpenLDAP -~~~~~~~~~~~~~~~~ - -As stated above, we will manually deploy OpenLDAP as we currently do not have a machine charm for it. -SSH into the unit: - -``juju ssh ldap/0`` - -And install OpenLDAP by running: - -``sudo apt install slapd ldap-utils`` - -Having installed OpenLDAP run: - -``sudo dpkg-reconfigure slapd`` - -Which will take you through the process of re-configuring OpenLDAP. -First, you will be presented with the following screen. - -.. image:: images/ldap_image2.png - -Answer “No”. -When asked to enter then DNS domain name - -.. image:: images/ldap_image1.png - -enter ``ldap.canonical.`` replacing the ```` part with the name of the domain you own. - -In the next screen enter ``canonical.`` as the name of the organisation again, replacing “domain.com” with the domain you own. - -.. image:: images/ldap_image3.png - -Next you will have to enter an administrator password. - -.. image:: images/ldap_image8.png - -And re-enter the chosen administrator password. - -.. image:: images/ldap_image4.png - -When asked if you want the database removed when ``slapd`` is purged, it is safe to answer “No.” as this is there is no content in the database yet. - -.. image:: images/ldap_image7.png - -Having configured OpenLDAP you can exit from the unit. - - -Configure TLS -~~~~~~~~~~~~~ - -To obtain a valid certificate for OpenLDAP we will use certbot. -First we need to tell certbot where to place obtained certificate, key and trust chain: - -.. code:: console - - juju config certbot chain-path=/etc/ldap/ldap-chain.pem - juju config certbot key-path=/etc/ldap/ldap-key.pem - juju config certbot cert-path=/etc/ldap/ldap-cert.pem - -Now we can add a relation between certbot and ldap applications: - -``juju add-relation certbot ldap`` - -Next we’ll need to create a DNS **A** record for the LDAP in Route53. -Run: - -``juju status --format json | jq '.applications.ldap.units["ldap/0"]["public-address"]'`` - -to obtain the public IP of the LDAP unit and use that IP to create an **A** record for the DNS ``ldap.canonical.``. -Then we can run the get-certificate action on the certbot unit to obtain certificates; - -``juju run-action –wait certbot/0 get-certificate agree-tos=true aws-access-key-id= aws-secret-access-key= domains=ldap.canonical. email= plugin=dns-route53`` - -This will result in creation of ``.pem`` files specified by the certbot configuration. -Now we can ssh back into the ldap unit: - -.. code:: console - - juju ssh ldap/0 - cd /etc/ldap - -Next we need to configure OpenLDAP to use created certificates. -We do that by creating a file ``certinfo.ldif`` with the following content - -.. code:: yaml - - dn: cn=config - replace: olcTLSCACertificateFile - olcTLSCACertificateFile: /etc/ldap/ldap-chain.pem - - - replace: olcTLSCertificateFile - olcTLSCertificateFile: /etc/ldap/ldap-cert.pem - - - replace: olcTLSCertificateKeyFile - olcTLSCertificateKeyFile: /etc/ldap/ldap-key.pem - -And then apply this configuration to OpenLDAP: - -``sudo ldapmodify -Y EXTERNAL -H ldapi:/// -f certinfo.ldif`` - -Allowing access to LDAP -~~~~~~~~~~~~~~~~~~~~~~~ - -As we have manually deployed OpenLDAP, we need to allow access to its ports. To do that go to the EC2 management console, to the list of running instances. Identify the OpenLDAP unit by its IP and edit its security groups. Add a rule that allows access to the LDAP port (389) from anywhere on the web. - -Initial LDAP content -~~~~~~~~~~~~~~~~~~~~ - -Next we create a file ``content.ldif`` with the following content: - -.. code:: yaml - - dn: ou=People,dc=canonical,dc=,dc= - objectClass: organizationalUnit - ou: People - - dn: ou=Groups,dc=canonical,dc=,dc= - objectClass: organizationalUnit - ou: Groups - -And add that to OpenLDAP: - -``ldapadd -x -D cn=admin,dc=canonical,dc=,dc= -W -f ./content.ldif`` - -Adding users -~~~~~~~~~~~~ - -To add an LDAP user, we create a file names ``.ldif`` with the following content: - -.. code:: yaml - - dn: uid=,ou=People,dc=canonical,dc=,dc= - objectClass: inetOrgPerson - objectClass: posixAccount - objectClass: shadowAccount - uid: - sn: - givenName: - cn: - displayName: - uidNumber: - gidNumber: - userPassword: {CRYPT}x - gecos: - loginShell: /bin/bash - homeDirectory: /home/ - -And use ``ldapadd`` to add the user: - -``ldapadd -x -D cn=admin,dc=canonical,dc=,dc= -W -f ./.ldif`` - -Next we need to set a password for the created user, which we do by running: - -``ldappasswd -x -D cn=admin,dc=canonical,dc=,dc= -W -S uid=,ou=People,dc=canonical,dc=,dc=`` - - -LDAP Identity Provider for Candid ---------------------------------- - -Once we have Candid deployed and LDAP configured all we need to do is let Candid know how to use OpenLDAP as an identity provider. We do this by setting its identity-providers config option: - -.. code:: console - - juju config candid identity-providers='- type: ldap - name: - description: - domain: ldap.canonical. - url: ldap://ldap.canonical./dc=canonical,dc=,dc= - dn: cn=admin,dc=canonical,dc=,dc= - password: - user-query-filter: (objectClass=inetOrgPerson) - user-query-attrs: - id: uid - email: mail - display-name: displayName - group-query-filter: (&(objectClass=groupOfNames)(member={{.User}})) - hidden: false - ca-cert: | - - - -Testing Candid with LDAP ------------------------- - -To test Candid you can open your browser and go to ``https://candid.canonical./login`` which will present you with the following page: - -.. image:: images/ldap_image6.png - -as we only have one identity provider configured - LDAP. Clicking on ldap will present you with the following page: - -.. image:: images/ldap_image5.png - -where you are asked to provide username and password for one of the users you added to LDAP. If you enter the correct credentials, Candid will show you a page notifying you that you have successfully logged in. - -Conclusion ----------- - -In this how-to we have successfully deployed Candid and OpenLDAP and configured Candid to let you log in with your OpenLDAP credentials. - diff --git a/how-to/deploy_candid.rst b/how-to/deploy_candid.rst deleted file mode 100644 index 9d0482c..0000000 --- a/how-to/deploy_candid.rst +++ /dev/null @@ -1,84 +0,0 @@ -JAAS: Deploy Candid -=================== - -Introduction -In this tutorial we will be deploying Candid. Candid provides a macaroon-based authentication service that is able to utilise many standard identity providers: - -- UbuntuSSO -- LDAP -- Google OpenID Connect -- ADFS OpenID Connect -- Azure OpenID Connect -- Keystore (username/password or token) -- Static identity provider (only used for testing) - -Prerequisites -------------- - -For this tutorial you will need the following: - -- A valid registered domain (regardless of the registrar) -- AWS credentials -- Basic knowledge of juju -- A subdomain registered with Route 53. To learn how to set that up, please follow :doc:`route53`. In this tutorial we will assume that you have registered the canonical.example.com subdomain - please replace this with the appropriate subdomain that you have registered with Route 53. - -Deploy Candid -------------- - -1. Bootstrap a controller: - ``juju bootstrap aws`` - -2. Download the candid bundle from `here `_. - -3. Extract the file: - ``tar xvf candid_v1.11.0.tar.xz`` - -4. Move to the ``candid`` folder: - ``cd candid`` - -5. Deploy the bundle: - ``juju deploy ./bundle.yaml --overlay ./overlay-certbot.yaml`` - -6. Once the bundle has been deployed, get the public IP of the ``haproxy/0`` unit: - ``juju status --format json | jq '.applications.haproxy.units["haproxy/0"]["public-address"]'`` - -7. Go to the `Route 53 dashboard `_. - -8. Add an A record for the deployed candid (e.g. ``candid.canonical.example.com``) with the IP obtained in step 6. - -9. Obtain a valid certificate for the deployed Candid by running: - ``juju run-action --wait certbot/0 get-certificate  agree-tos=true aws-access-key-id= aws-secret-access-key= domains= email=  plugin=dns-route53`` - -10. Let candid know its DNS name (replace ``candid.canonical.example.com`` with the DNS name you set up in step 8): - ``juju config candid location=https://candid.canonical.example.com`` - -11. Now all that is left is to set up the identity providers. In this tutorial we will set up a static identity provider with hard-coded usernames and passwords:  - - .. code:: - - juju config candid identity-providers='- type: static - name: static - description: Default identity provider - users: - user1: - name: User One - email: user1 - password: s3cre7Pa55w0rd1 - groups: - - group1 - - group3 - user2: - name: User Two - email: user2 - password: s3cre7Pa55w0rd2 - groups: - - group2 - - group3' - -Following these steps you have deployed Candid that uses a static identity provider -with two hard-coded users. **Please note that the static identity provider should not -be used in production**. - -To verify that Candid is working correctly, open your browser and go to -``https:///login`` and try to log in as ``user1`` or ``user2`` using one of the -hard-coded passwords. \ No newline at end of file diff --git a/how-to/deploy_candid_k8s.rst b/how-to/deploy_candid_k8s.rst deleted file mode 100644 index ca00127..0000000 --- a/how-to/deploy_candid_k8s.rst +++ /dev/null @@ -1,290 +0,0 @@ -JAAS: Deploy Candid on K8S -========================== - -Introduction ------------- - -In this topic we will be deploying Candid on Kubernetes. Candid provides a macaroon-based authentication service that is able to utilise many standard identity providers: - -- UbuntuSSO -- LDAP -- Google OpenID Connect -- ADFS OpenID Connect -- Azure OpenID Connect -- Keystore (username/password or token) -- Static identity provider (only used for testing) - -Prerequisites -------------- - - -For this tutorial you will need the following: - -- A valid registered domain (regardless of the registrar) -- AWS credentials -- Basic knowledge of juju -- A subdomain registered with Route 53. To learn how to set that up, please follow :doc:`route53`. -- Access to a Kubernetes cluster -- Access to a PostgreSQL database - -Deploy a Kubernetes cluster ---------------------------- - -In case you do not already have access to a Kubernetes cluster, you can deploy one on AWS. Start by bootstrapping a new controller in AWS: - -``juju bootstrap aws k8s-controller`` - -and then deploy the ``kubernetes-core`` bundle: - -``juju deploy kubernetes-core`` - -and the aws-integrator charm: - -``juju deploy aws-integrator`` - -which simplifies working with charmed Kubernetes on AWS. -Use the following commands to configure and relate aws-integrator to various applications: - -.. code:: console - - juju trust aws-integrator - juju relate aws-integrator kubernetes-control-plane - juju relate aws-integrator kubernetes-worker - -Once all applications settle down and start fetch the config file that will let you use ``kubectl``: - -``juju scp kubernetes-control-plane/0:config ~/.kube/config`` - -Deploy Candid -------------- - -Once you have access to a K8s cluster, you can verify it by running: - -``kubectl get nodes`` - -and if that works add the Kubernetes cluster as a cloud to your juju client: - -``juju add-k8s myk8s`` - -We can the bootstrap a new controller in the added k8s cluster by running: - -``juju bootstrap myk8s infrastructure`` - -and when this process finishes we can add a new model for Candid: - -``juju add-model candid`` - -Now we can deploy the Candid into the newly created model: - -``juju deploy candid-k8s –channel edge`` - -As Juju does not currently support exposing an application on a k8s cloud, we need to also deploy ``nginx-ingress-integrator`` charm. Run: - -.. code:: console - - juju deploy nginx-ingress-integrator ingress - juju trust ingress --scope=cluster - juju relate ingress candid-k8s - -Once deployed go to the management console of your domain and create an A record for the deployed Candid (e.g. ``candidcanonical.example.com``) with the IP of k8s worker nodes. - -Configure Candid ----------------- - -Once deployed we need to configure Candid. Run the following commands: - -.. code:: console - - juju config candid-k8s location=https://candid.canonical.stimec.net - juju config candid-k8s admin-agent-public-key='test-public-key' - - juju config candid-k8s identity-providers='- type: static - name: static - domain: stimec - description: Default identity provider - users: - admin: - name: User One - email: admin - password: password1 - groups: - - group1 - user1: - name: User Two - email: user1 - password: password1 - groups: - - group2 - my-user: - name: User Three - email: my-user - password: password1 - groups: - - group2' - juju config candid-k8s postgresql-dsn= - - -Next we also need to configure ingress. Usually the Kubernetes cluster operator will set up a Kubernetes secret for you containing a certificate and key for Candid’s FQDN (in case you need a certificate look at the next section) and give you the secret name. All you need to do next is: - -``juju config ingress tls-secret-name=`` - -and the ingress charm will get certificates from the Kubernetes secret and set up TLS for you. -Now you test Candid by opening your browser and navigating to ``https://candid./login`` - -Appendix --------- - -Don’t have a PostgreSQL database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In case you do not have access to a PostgreSQL database you can use Amazon's RDS to create one. Navigate to the RDS console and select "Create database". Under "Engine type" select "PostgreSQL", specify "Master username" and "Master password". Also make sure to select "Public access" as "Yes". You can customise all other options to your preference. Once the database is created, navigate to the database's dashboard. There you will see the "Endpoint" and "Port" strings, which you will need to connect to the database. :none:`wokeignore:rule=master,` -Use the following command to configure Candid: :none:`wokeignore:rule=master,` - - ``juju config candid-k8s dns=postgres://:@:/`` :none:`wokeignore:rule=master,` - -Don’t have certificates -~~~~~~~~~~~~~~~~~~~~~~~ - -In case the cluster operator did not set up a Kubernetes secret for you containing certificate and key for Candid’s FQDN, you can use Let’s Encrypt and cert-manager to get the certificate. -First, you will need to install helm: - -``sudo snap install helm`` - -Then run the following commands to deploy cert-manager: - -.. code:: console - - helm repo add jetstack https://charts.jetstack.io - helm repo update - helm install certmgr jetstack/cert-manager - --set installCRDs=true \ - --version v1.9.1 \ - --namespace cert-manager \ - --create-namespace - -Since the production Let’s Encrypt servers do some fancy rate limiting -and we don’t want to exceed the limit, we will first test our setup with -the staging server. - -Create a file ``stg-issuer.yaml`` with the following content: - -.. code:: yaml - - apiVersion: cert-manager.io/v1 - kind: Issuer - metadata: - name: letsencrypt-staging - spec: - acme: - # The ACME server URL - server: https://acme-staging-v02.api.letsencrypt.org/directory - # Email address used for ACME registration - email: - # Name of a secret used to store the ACME account private key - privateKeySecretRef: - name: letsencrypt-staging - # Enable the HTTP-01 challenge provider - solvers: - - http01: - ingress: - class: nginx - -and run: - -``kubectl apply -n candid -f stg-issuer.yaml`` - -which will create a certificate issuer in Candid’s namespace. - -The create ``stg-certs.yaml`` file with the following content: - -.. code:: yaml - - apiVersion: cert-manager.io/v1 - kind: Certificate - metadata: - name: candid-stg-cert #name of this object - namespace: candid #same namespace as - spec: - dnsNames: - - candid.canonical.stimec.net - secretName: letsencrypt-stg-certs - issuerRef: - name: letsencrypt-staging - kind: Issuer - -and run: - -``kubectl apply -n candid -f stg-certs.yaml`` - -This should create a certificate and key using the staging issuer. Inspect the created certificate by running: - -``kubectl describe certificate -n candid candid-stg-cert`` - -and: - -``kubectl describe secret letsencrypt-stg-certs -n candid`` - -which will show a Kubernetes secret and in its data you should see a stored ``tls.crt`` and ``tls.key``. -If this all worked (and i have no doubt it did :) ), then we can proceed by creating a production issuer. Create a ``prod-issuer.yaml`` file with the following content: - -.. code:: yaml - - apiVersion: cert-manager.io/v1 - kind: Issuer - metadata: - name: letsencrypt-prod - spec: - acme: - # The ACME server URL - server: https://acme-v02.api.letsencrypt.org/directory - # Email address used for ACME registration - email: ales.stimec@canonical.com - # Name of a secret used to store the ACME account private key - privateKeySecretRef: - name: letsencrypt-prod - # Enable the HTTP-01 challenge provider - solvers: - - http01: - ingress: - class: nginx - -and run: - -``kubectl apply -n candid -f prod-issuer.yaml`` - -Then create a ``prod-certs.yaml`` file with the following content: - -.. code:: yaml - - apiVersion: cert-manager.io/v1 - kind: Certificate - metadata: - name: candid-cert #name of this object - namespace: candid - spec: - dnsNames: - - candid.canonical.stimec.net - secretName: letsencrypt-certs - issuerRef: - name: letsencrypt-prod - kind: Issuer - -and run: - -``kubectl apply -n candid -f prod-certs.yaml`` - -This will create a ``letsencrypt-certs`` secrets for you, which you can inspect by running: - -``kubectl describe secret letsencrypt-certs -n candid`` - -which will show the created secret and in its data you should see a stored ``tls.crt`` and ``tls.key``. -To see the certificate data run: - -``kubectl describe certificate -n candid candid-cert`` - - -Once you have the production certificate, you can configure the ingress application by running: - -``juju config ingress tls-secret-name=letsencrypt-certs`` - - diff --git a/how-to/deploy_jimm_k8s.rst b/how-to/deploy_jimm_k8s.rst index a901f2f..ceac371 100644 --- a/how-to/deploy_jimm_k8s.rst +++ b/how-to/deploy_jimm_k8s.rst @@ -2,7 +2,7 @@ JAAS: Deploy JIMM on K8S ======================== .. warning:: - This document has not been updated for JIMM.V2. + This document has not been updated for JIMM.V3. Introduction ------------ diff --git a/how-to/index.rst b/how-to/index.rst index b09b6b9..e5e8d20 100644 --- a/how-to/index.rst +++ b/how-to/index.rst @@ -3,23 +3,6 @@ How-to guides These how-to guides cover key operations and processes in JAAS. -Candid Deployment and Configuration ------------------------------------ - -`Candid`_ serves as authentication service for JIMM. So you need a working Candid -before deploying JIMM. Depending on the platform/requirements, some details of -the Candid deployment could be different. - -.. toctree:: - :maxdepth: 1 - - Deploy Candid - Deploy Candid on K8S - Candid LDAP integration - Candid Azure integration - Candid ADFS integration - - JIMM Deployment --------------- diff --git a/index.rst b/index.rst index 30e3dc1..3f4a9ad 100644 --- a/index.rst +++ b/index.rst @@ -11,7 +11,6 @@ the ability to drill-in to the details when you need it. **JAAS** is composed of the following components: -- Candid - a macaroon-based authentication server, which can use a variety of identity providers to correctly identify users, - JIMM - Juju Intelligent Model Manager, which acts as a single point of contact for multiple Juju controllers, - Juju controllers - each controlling models in specific clouds or cloud regions, - Juju dashboard - providing a clear overview of your Juju real estate with the ability to drill down into details of your deploys. diff --git a/tutorial/group_management.rst b/tutorial/group_management.rst index 844ceb9..b1ad4ac 100644 --- a/tutorial/group_management.rst +++ b/tutorial/group_management.rst @@ -16,7 +16,6 @@ Prerequisites For this tutorial you will need the following: -- Deployed JAAS system (JIMM and Candid) with a few valid users (see :doc:`../how-to/deploy_jimm` and :doc:`../how-to/deploy_candid`) - At least one controller connected to JIMM (see :doc:`../how-to/add_controller`) - ``jimmctl`` command (either built from source or installed via a snap) diff --git a/tutorial/jaas_basics.rst b/tutorial/jaas_basics.rst index f301b18..0a3012e 100644 --- a/tutorial/jaas_basics.rst +++ b/tutorial/jaas_basics.rst @@ -2,7 +2,7 @@ JAAS Basics =========== .. warning:: - This document has not been updated to JIMM.V2. + This document has not been updated to JIMM.V3. Introduction ------------