docs: fix Microsoft SSO integration guide (#7699)

* Detailed steps for Azure AD App Registration Auth using OIDC * Detailed steps for Azure AD App Registration Auth using OIDC * Validation steps for both Web and CLI Signed-off-by: kulmam92 <kulmam92@gmail.com> * Images for Azure AD App Registration Auth using OIDC Images for Azure AD App Registration Auth using OIDC Signed-off-by: kulmam92 <kulmam92@gmail.com> * add more context for scope Signed-off-by: kulmam92 <kulmam92@gmail.com>
argoproj · Apr 29, 2022 · 1533698 · 1533698
1 parent cec1879
commit 1533698
Show file tree

Hide file tree

Showing 8 changed files with 99 additions and 17 deletions.
diff --git a/docs/assets/azure-app-registration-authentication.png b/docs/assets/azure-app-registration-authentication.png
diff --git a/docs/assets/azure-app-registration-overview.png b/docs/assets/azure-app-registration-overview.png
diff --git a/docs/assets/azure-app-registration-secret.png b/docs/assets/azure-app-registration-secret.png
diff --git a/docs/assets/azure-sso-cli-log-in-success.png b/docs/assets/azure-sso-cli-log-in-success.png
diff --git a/docs/assets/azure-sso-web-application.png b/docs/assets/azure-sso-web-application.png
diff --git a/docs/assets/azure-sso-web-log-in-via-azure.png b/docs/assets/azure-sso-web-log-in-via-azure.png
diff --git a/docs/assets/azure-sso-web-user-info.png b/docs/assets/azure-sso-web-user-info.png
diff --git a/docs/operator-manual/user-management/microsoft.md b/docs/operator-manual/user-management/microsoft.md
@@ -84,28 +84,60 @@ policy.default: role:readonly
 
 ## Azure AD App Registration Auth using OIDC
 
-1. Register a new Azure AD Application
+### Configure a new Azure AD App registration
 
-    [Quickstart: Register an application](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)
+#### Add a new Azure AD App registration
 
-        App Registrations Inputs
-            Redirect URI: https://argocd.example.com/auth/callback
-        Outputs
-            Application (client) ID: aaaaaaaa-1111-bbbb-2222-cccccccccccc
-            Directory (tenant) ID: 33333333-dddd-4444-eeee-555555555555
-            Secret: some_secret
+1. From the `Azure Active Directory` > `App registrations` menu, choose `+ New registration`
+2. Enter a `Name` for the application (e.g. `Argo CD`).
+3. Specify who can use the application (e.g. `Accounts in this organizational directory only`).
+4. Enter Redirect URI (optional) as follows (replacing `my-argo-cd-url` with your Argo URL), then choose `Add`.
+   - **Platform:** `Web`
+   - **Redirect URI:** https://`<my-argo-cd-url>`/auth/callback
+5. When registration finishes, the Azure portal displays the app registration's Overview pane. You see the Application (client) ID.
 
-2. Setup permissions for Azure AD Application
+   ![Azure App registration's Overview](../../assets/azure-app-registration-overview.png "Azure App registration's Overview")
+
+#### Configure additional platform settings for ArgoCD CLI
 
-    On "API permissions" page find `User.Read` permission (under `Microsoft Graph`) and grant it to the created application:
+1. In the Azure portal, in App registrations, select your application.
+2. Under Manage, select Authentication.
+3. Under Platform configurations, select Add a platform.
+4. Under Configure platforms, select the "Mobile and desktop applications" tile. Use the below value. You shouldn't change it.
+   - **Redirect URI:** `http://localhost:8085/auth/callback`
 
-    ![Azure AD API permissions](../../assets/azure-api-permissions.png "Azure AD API permissions")
+   ![Azure App registration's Authentication](../../assets/azure-app-registration-authentication.png "Azure App registration's Authentication")
 
-    Also, on "Token Configuration" page add groups claim for the groups assigned to the application:
+#### Add credentials a new Azure AD App registration
 
-    ![Azure AD token configuration](../../assets/azure-token-configuration.png "Azure AD token configuration")
+1. From the `Certificates & secrets` menu, choose `+ New client secret`
+2. Enter a `Name` for the secret (e.g. `ArgoCD-SSO`).
+   - Make sure to copy and save generated value. This is a value for the `client_secret`.
 
-3. Edit `argocd-cm` and configure the `data.oidc.config` section:
+   ![Azure App registration's Secret](../../assets/azure-app-registration-secret.png "Azure App registration's Secret")
+
+#### Setup permissions for Azure AD Application
+
+1. From the `API permissions` menu, choose `+ Add a permission`
+2. Find `User.Read` permission (under `Microsoft Graph`) and grant it to the created application:
+
+   ![Azure AD API permissions](../../assets/azure-api-permissions.png "Azure AD API permissions")
+
+3. From the `Token Configuration` menu, choose `+ Add groups claim`
+
+   ![Azure AD token configuration](../../assets/azure-token-configuration.png "Azure AD token configuration")
+
+### Associate an Azure AD group to your Azure AD App registration
+
+1. From the `Azure Active Directory` > `Enterprise applications` menu, search the App that you created (e.g. `Argo CD`).
+   - An Enterprise application with the same name of the Azure AD App registration is created when you add a new Azure AD App registration.
+2. From the `Users and groups` menu of the app, add any users or groups requiring access to the service.
+
+   ![Azure Enterprise SAML Users](../../assets/azure-enterprise-users.png "Azure Enterprise SAML Users")
+
+### Configure Argo to use the new Azure AD App registration
+
+1. Edit `argocd-cm` and configure the `data.oidc.config` section:
 
         ConfigMap -> argocd-cm
 
@@ -124,14 +156,14 @@ policy.default: role:readonly
                     - profile
                     - email
 
-4. Edit `argocd-secret` and configure the `data.oidc.azure.clientSecret` section:
+2. Edit `argocd-secret` and configure the `data.oidc.azure.clientSecret` section:
 
         Secret -> argocd-secret
 
         data:
             oidc.azure.clientSecret: {client_secret | base64_encoded}
 
-5. Edit `argocd-rbac-cm` to configure permissions. Use group ID from Azure for assigning roles
+3. Edit `argocd-rbac-cm` to configure permissions. Use group ID from Azure for assigning roles
 
     [RBAC Configurations](../rbac.md)
 
@@ -147,12 +179,23 @@ policy.default: role:readonly
             p, role:org-admin, repositories, delete, *, allow
             g, "84ce98d1-e359-4f3b-85af-985b458de3c6", role:org-admin
 
-6. Mapping role from jwt token to argo
+4. Mapping role from jwt token to argo
 
     If you want to map the roles from the jwt token to match the default roles (readonly and admin) then you must change the scope variable in the rbac-configmap.
 
+        policy.default: role:readonly
+        policy.csv: |
+            p, role:org-admin, applications, *, */*, allow
+            p, role:org-admin, clusters, get, *, allow
+            p, role:org-admin, repositories, get, *, allow
+            p, role:org-admin, repositories, create, *, allow
+            p, role:org-admin, repositories, update, *, allow
+            p, role:org-admin, repositories, delete, *, allow
+            g, "84ce98d1-e359-4f3b-85af-985b458de3c6", role:org-admin
         scopes: '[roles, email]'
 
+    Refer to [operator-manual/argocd-rbac-cm.yaml](https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/argocd-rbac-cm.yaml) for all of the available variables.
+
 ## Azure AD App Registration Auth using Dex
 
 Configure a new AD App Registration, as above.
@@ -176,3 +219,42 @@ data:
           groups:
             - DevOps
 ```
+
+## Validation
+
+### Log in to ArgoCD UI using SSO
+
+1. Open a new browser tab and enter your ArgoCD URI: https://`<my-argo-cd-url>`
+
+   ![Azure SSO Web Log In](../../assets/azure-sso-web-log-in-via-azure.png "Azure SSO Web Log In")
+
+3. Click `LOGIN VIA AZURE` button to log in with your Azure Active Directory account. You’ll see the ArgoCD applications screen.
+
+   ![Azure SSO Web Application](../../assets/azure-sso-web-application.png "Azure SSO Web Application")
+
+4. Navigate to User Info and verify Group ID. Groups will have your group’s Object ID that you added in the `Setup permissions for Azure AD Application` step.
+
+   ![Azure SSO Web User Info](../../assets/azure-sso-web-user-info.png "Azure SSO Web User Info")
+
+### Log in to ArgoCD using CLI
+
+1. Open terminal, execute the below command.
+```
+argocd login <my-argo-cd-url> --grpc-web-root-path / --sso
+```
+2. You will see the below message after entering your credentials from the browser.
+
+   ![Azure SSO CLI Log In](../../assets/azure-sso-cli-log-in-success.png "Azure SSO CLI Log In")
+
+3. Your terminal output will be similar as below.
+
+```
+WARNING: server certificate had error: x509: certificate is valid for ingress.local, not my-argo-cd-url. Proceed insecurely (y/n)? y
+Opening browser for authentication
+INFO[0003] RequestedClaims: map[groups:essential:true ]
+Performing authorization_code flow login: https://login.microsoftonline.com/XXXXXXXXXXXXX/oauth2/v2.0/authorize?access_type=offline&claims=%7B%22id_token%22%3A%7B%22groups%22%3A%7B%22essential%22%3Atrue%7D%7D%7D&client_id=XXXXXXXXXXXXX&code_challenge=XXXXXXXXXXXXX&code_challenge_method=S256&redirect_uri=http%3A%2F%2Flocalhost%3A8085%2Fauth%2Fcallback&response_type=code&scope=openid+profile+email+offline_access&state=XXXXXXXX
+Authentication successful
+'yourid@example.com' logged in successfully
+Context 'my-argo-cd-url' updated
+```
+You may get an warning if you are not using a correctly signed certs. Refer to [Why Am I Getting x509: certificate signed by unknown authority When Using The CLI?](https://argo-cd.readthedocs.io/en/stable/faq/#why-am-i-getting-x509-certificate-signed-by-unknown-authority-when-using-the-cli).